01 — Product Overview (Attendance Module)

• 1. Purpose
• 2. Business goals
• 3. User goals
• 4. Stakeholders
• 5. Why this exists
• 6. Scope boundaries (exact, from code)
• 7. Success metrics
• 8. Edge cases (backend-derived)
• 9. Assumptions (module)
• 10. Open questions (module; global ledger in 00-shared/12)
• 11. Glossary (this module)

StudyLyon — multi-tenant ERP / School Management API. This package designs the Attendance module client (Flutter, forward-looking spec) against the implemented NestJS backend. Every endpoint, DTO field, schema, index, event, worker, and permission is derived directly from src/modules/attendance/**, src/modules/biometric/**, src/infrastructure/workers/attendance.worker.ts, src/infrastructure/bullmq/**, src/modules/scheduler/**, src/modules/reports/**, and src/modules/rbac/**. No feature is invented; gaps are flagged in Assumptions & Open Questions (§10) and marked (planned) / (forward-looking) / (proposed) inline.

1. Purpose

Attendance records one status per student per day — the daily truth a school runs on: who came, who didn't, who was late, who took leave. It is captured by teachers in the classroom (manual marking), ingested from biometric devices (raw punch logs), corrected after the fact (edit), and consumed everywhere: monthly reports, dashboards, absentee alerting, and parent/student visibility.

The domain is deliberately small: one attendance document = one student, one date, one status (attendance.schema.ts:24-55), enforced by a unique index (attendance.schema.ts:59-62).

2. Business goals

3. User goals

• Teacher: mark a whole class in under a minute (bulk), fix a wrong status fast (PATCH), see today's marked/unmarked at a glance, never lose work on a slow connection.
• Org admin: monthly attendance rates per class, drill into per-student history, ensure devices are pushing punches (biometric-device.schema.ts:7-11).
• Parent: get alerted the moment a child is marked absent, view the child's month at a glance.
• Student: see own attendance % and history (END_TO_END_USER_FLOWS.md:324-325).
• Biometric operator: ingest device punches, verify device health, understand what becomes attendance (and what currently doesn't — see OQ-3).

4. Stakeholders

Teachers (primary marker), class teachers (roster ownership), org admins (reports and policy), parents/students (consumers), biometric device operators (integration), scheduler (jobs), support staff (correction disputes), QA/design/engineering.

5. Why this exists

Attendance is the highest-frequency daily data-entry task in a school and the basis of report cards, fee policy, and parent trust. The backend makes the write path idempotent and cheap; the client's job is to make the capture surface so fast that teachers actually use it, and the consumption surfaces so clear that parents trust it.

6. Scope boundaries (exact, from code)

In scope today (backend): single mark, bulk mark (sequential loop over mark(), attendance.service.ts:48-54), class-by-date read, student history read, summary counts, PATCH edit, biometric log ingest (store-only), async attendance summary report, dashboard KPI, scheduler cron registration, absentee watch (log-only).

Not implemented (flag labels used below):

• Session-based attendance (sessionId, attendanceMode: 'session') — (planned), schema additions sketched in docs/IMPLEMENTATION_PLAN.md:432-468; the live schema has no session field (attendance.schema.ts).
• POST /attendance/import bulk import endpoint — (planned); blueprint 04-Modules/Attendance.md:30 lists it; only the worker's bulk-import branch exists (attendance.worker.ts:49,83-102), and it creates records directly with per-record error swallowing (duplicate keys fail silently — OQ-2).
• Biometric logs → attendance derivation — (planned)/(forward-looking); biometric-sync queue + */15 * * * * cron exist (scheduler.service.ts:71-76, queue.constants.ts:7) but no worker consumes it; biometric.service.ts:14-16 only writes the log. Blueprint RELATIONSHIPS.md:100 intends biometric_logs.processed → attendance.
• Absentee notifications to parents — (planned); attendance.worker.ts:69-80 only logs "alert recommended". PLAN.md row 5.4 describes the target (AttendanceMarked → in-app + push queues).
• Push/QR device flows — (forward-looking) (shared ledger B3/B4: no device-token registry, no QR backend).
• Client-side analytics — (proposed) per 00-shared/10_QA_Baseline.md §8.
• RBAC enforcement — permissions attendance.mark/attendance.edit are defined (permissions.constants.ts:29-30) and seeded (role.schema.ts:31), global guards are RateLimitGuard → JwtAuthGuard → RbacGuard (app.module.ts:129-131), but the attendance controller declares no @Permissions() decorator (attendance.controller.ts:19-23) — treat 403 as expected contract (OQ-5).
• Pagination on attendance list endpoints — not implemented; reads return plain arrays without meta (OQ-4, see 12_API_Mapping.md).

7. Success metrics

• Teacher marks a 40-student class in < 60 s (bulk request ≤ 1 payload).
• 100% of mark attempts succeed or surface a clear error — the upsert means retries are safe (idempotent, attendance.repository.ts:23-29).
• Zero duplicate attendance docs per tenant (unique index enforcement, plus client dedupe in offline queue).
• Correction latency: PATCH round-trip < 500 ms p95; conflict-free because PATCH replaces only sent fields (update-attendance.dto.ts:4-22 + $set, base.repository.ts:57-66).
• Attendance report generated async without request timeout (reports.service.ts:28-44).

8. Edge cases (backend-derived)

• Remark same student+date → overwrite (upsert), source stays manual unless supplied; classId on an existing doc is not updated by remark (attendance.repository.ts:23-29).
• Same student marked for a different class on the same date → still one doc (unique on studentId+date), original classId wins — client must prevent cross-class remarking.
• Invalid status on POST → 400 VALIDATION_ERROR (IsEnum, mark-attendance.dto.ts:27-28; e2e p1-operations.e2e-spec.ts:222-228).
• Invalid status on PATCH → not enum-validated (update-attendance.dto.ts:8 is IsString only) — server may persist a bad status via $set (no runValidators); client must constrain the picker (OQ-6).
• Absentee count in the worker counts all absent records for the student, not consecutive days within a window (attendance.worker.ts:70-74) — UI must not promise "3 consecutive absences" semantics (OQ-1).
• Duplicate records in bulk-import → per-record catch → logged warn, not failed (attendance.worker.ts:91-101).
• date is sent as YYYY-MM-DD string and stored as Date (mark-attendance.dto.ts:21; attendance.schema.ts:31-32) — timezone discipline is a client responsibility (see 14_QA_Checklist.md §timezone).
• Deleted/cross-tenant record → 404 "Attendance record not found." (attendance.service.ts:77).
• Summary with no records → {total: 0, summary: {}} (attendance.service.ts:112).

9. Assumptions (module)

• Client is forward-looking (see shared ledger A1 — PRD Phase 1 is backend; these docs specify the full Flutter client per user instruction).
• One attendance per student per day is the only current model; "per session" is (planned) and the client's calendar/history must not assume per-period rows.
• Teacher role carries ['student.read','attendance.mark','attendance.edit'] (role.schema.ts:31); admin has everything (role.schema.ts:23). Parent and student roles have no attendance permission today (role.schema.ts:55,63) — the student profile and parent views must be built against student.read + the routes those roles reach (see 12_API_Mapping.md §9, OQ-7).
• Enrollment is the roster source: Student.classId/sectionId (student.schema.ts:38-39) and class_enrollments (class-enrollment.schema.ts:14-38); the marking grid renders students of one class.
• Retry safety: because mark is an upsert, a re-sent offline batch is harmless (repeated sends converge), but events fire per mark — network-layer dedupe is still recommended to avoid duplicate AttendanceMarked events.

10. Open questions (module; global ledger in 00-shared/12)

11. Glossary (this module)