Attendance - API Reference

Audience: Frontend engineers, mobile engineers, backend engineers, QA, and API consumers. Scope: Admin (student and staff registers, overview, history, settings) and mobile/consumer (teacher, student, guardian portal) APIs owned by Attendance.

1. Documentation Evidence

2. Module Summary

3. Concepts and Terminology

4. API Surface Map

AttendanceSharedModule and AttendanceWorkersModule declare no controller and contribute nothing to either Swagger document — the two BullMQ sweeps have no HTTP surface at all.

5. Auth, Identity, and Permissions

Why no seeded role holds StudentAttendance_*, StaffAttendance_* or AttendanceSettings_*. packages/db/src/seed/seed-auth.ts grants none of these codes to any role. TEACHER_PERMISSIONS spreads STAFF_PERMISSIONS in that file, so anything granted to staff reaches every teacher, and both seeded roles carry scopeKind: "all" — so granting StudentAttendance_READ to staff would give every teacher an unscoped read over every pupil's attendance and history, with none of the class-teacher predicate the portal enforces. A school that wants a non-administrator to hold these codes creates a dedicated role for it; grantToRoles never revokes a grant, so withholding by default is the recoverable direction.

AttendanceView — the screen code, which gates no route. A fourth module, AttendanceView, gates the panel's attendance screens: a pupil's own (/dashboard/my-attendance), a guardian's per-child view (/dashboard/children/{studentId}/attendance) and a class teacher's register (/dashboard/my-class/attendance), plus their sidebar entries. It appears on no API route — the three portal surfaces above carry no @Permissions() and assert their audience instead — so holding it grants no data access. AttendanceView_READ is seeded to staff (and through the spread to teacher), guardian and student. It is one of the person-bound screen modules a superadmin's GET /api/auth/permissions list omits, because a superadmin account has no pupil, ward or class of its own; see the auth API page, §3.5. The calendar code, AcademicCalendarView_READ, stays separate because the calendar is also an administrator screen.

The portal's audience assertion is not a permission, and is not a row scope either. assertPortalAudience(actor, "student" | "guardian") and assertTeacherStaffRow(db, actor) (apps/api/src/modules/mobile/shared/portal-audience.ts:74,176) prove only who is calling. Which rows come back is decided entirely by the query each service builds — classes.class_teacher_id = staffId for the teacher, students.user_id = actor.id for the pupil, the student_guardian join for the guardian. None of the three ever delegates to PeopleAccessService.scopeFor, whose {kind: "all"} result for a staff/teacher session would defeat the whole point of a per-route predicate.

6. DTO and Model Reference

6.1 MarkAttendanceEntryDto (nested request)

status: null deletes that pupil's record for the date rather than storing a null status.

6.2 BulkMarkAttendanceDto (request, admin PUT)

expectedVersion: null means "I read a class/date with no session row yet" — the first write of the day has no token to send.

6.3 GetStudentAttendanceQueryDto (query, GET .../students)

6.4 PatchStudentAttendanceRecordDto (request, PATCH .../:recordId)

6.5 CompleteAttendanceDto / ReopenAttendanceDto / ResetAttendanceDto (requests)

ReopenAttendanceDto and ResetAttendanceDto extend CompleteAttendanceDto verbatim, with no additional fields (:172,180).

6.6 StudentAttendanceRosterEntryDto (response, nested)

6.7 AttendanceTallyDto (response, nested)

6.8 StudentAttendanceSessionDto / AttendanceCalendarDayDto (response, nested)

6.9 StudentAttendanceStateDto (response, the shared envelope)

This exact shape is returned by every read, write, and lifecycle endpoint under /attendance/students and /mobile/teacher/attendance — always a fresh re-read, never an echo of the request.

6.10 StudentAttendanceRecordDto (response, PATCH .../:recordId)

6.11 StudentAttendanceHistoryQueryDto / AttendanceHistoryEntryDto

6.12 AttendanceOverviewQueryDto / AttendanceOverviewRowDto

6.13 ListStaffAttendanceQueryDto

6.14 StaffAttendanceRowDto / StaffAttendanceTallyDto / StaffAttendanceListDto (response)

6.15 StaffAttendanceEntryDto / BulkStaffAttendanceDto (request, PUT /attendance/staff)

6.16 PatchStaffAttendanceDto (request, PATCH /attendance/staff/:recordId)

6.17 StaffAttendanceHistoryQueryDto / StaffAttendanceHistoryEntryDto

Same shape and semantics as §6.11, applied to subjectKind = 'staff' (dto/staff-attendance.dto.ts:211-250).

6.18 AttendanceSettingRowDto / AttendanceSettingsListDto / UpdateAttendanceSettingsDto

6.19 Portal DTOs

PortalAttendanceSummaryDto (response of both summary routes; portal/shared/portal-attendance-summary.dto.ts):

With no current session, or a window that has not opened yet (to earlier than the session start), every count is 0 and from, to and ratePct are null; academicSessionName is still set when a session exists.

7. Enum Reference

8. Endpoint Reference

8.1 GET /api/attendance/students

Purpose

Returns a class's full register for one date — every live pupil, marked or not — for the admin attendance screen to render. A session: null in the response is normal for a class/date never opened and is not a 404.

Source Evidence

Auth and Permissions

• Auth: JWT required.
• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: StudentAttendance_READ.
• Guest support: No.
• Rate limit: Global default only.
• Idempotency: N/A (read).

Request

Response

200, StudentAttendanceStateDto (§6.9):

{
  "success": true,
  "message": "Attendance fetched.",
  "data": {
    "classPublicId": "018f...",
    "classLabel": "Grade 5 A (Morning)",
    "date": "2026-09-13",
    "calendar": { "classification": "school_day", "attendanceExpected": true, "eventName": null },
    "session": { "id": "018f...", "status": "in_progress", "completedAt": null, "version": 2 },
    "version": 2,
    "roster": [
      { "studentId": "018f...", "rollNumber": 1, "admissionNumber": "A-1024", "studentCode": "S-2091", "fullName": "Aashna Rai", "recordId": "018f...", "status": "present", "note": null, "markedAt": "2026-09-13T02:35:00.000Z", "recordVersion": 0 },
      { "studentId": "018f...", "rollNumber": 2, "admissionNumber": "A-1025", "studentCode": "S-2092", "fullName": "Bibek Thapa", "recordId": null, "status": null, "note": null, "markedAt": null, "recordVersion": null }
    ],
    "tally": { "totalStudents": 2, "markedCount": 1, "unmarkedCount": 1, "presentCount": 1, "absentCount": 0, "lateCount": 0, "excusedCount": 0 }
  }
}

Side Effects

None — read-only. No cache read/write, no job, no notification, no audit write beyond the global request log.

Error Cases

Edge Cases

• Never-opened register: session: null, version: null, every roster row status: null.
• A pupil with no assigned roll number sorts last, ordered after by admission number.
• Empty class (zero active enrolments): roster: [], tally.totalStudents: 0.

Example Requests

GET /api/attendance/students?date=2026-09-13&classPublicId=018f2c4a-... HTTP/1.1
Authorization: Bearer TOKEN

curl -G "$API_URL/api/attendance/students" \
  -H "Authorization: Bearer TOKEN" \
  -d date=2026-09-13 \
  -d classPublicId=018f2c4a-...

8.2 PUT /api/attendance/students

Purpose

Marks or corrects a class's register for one date, as a set of changes rather than a full-state rewrite. Opens the register lazily if this is the first write of the day. Call this from the class register screen on every "save" action.

Source Evidence

Auth and Permissions

• Auth: JWT required.
• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: StudentAttendance_CREATE AND StudentAttendance_UPDATE.
• Guest support: No.
• Rate limit: Global default only.
• Idempotency: Yes — submissionId; a replay writes nothing and returns 200 with the current state.

Request

Minimal valid body:

{
  "classPublicId": "018f2c4a-...",
  "date": "2026-09-13",
  "expectedVersion": null,
  "submissionId": "018f2c4b-...",
  "entries": [
    { "studentId": "018f2c4c-...", "status": "present" }
  ]
}

Full body with a force-write:

{
  "classPublicId": "018f2c4a-...",
  "date": "2026-09-14",
  "expectedVersion": 0,
  "submissionId": "018f2c4d-...",
  "entries": [
    { "studentId": "018f2c4c-...", "status": "present", "note": "Makeup session" },
    { "studentId": "018f2c4e-...", "status": null }
  ],
  "force": true,
  "forcedReason": "Emergency makeup class on a public holiday"
}

Response

200, StudentAttendanceStateDto (same shape as §8.1).

Side Effects

• Database writes: student_attendance_sessions (insert-or-find), student_attendance_records (upsert marked entries, delete unmarked entries), attendance_change_log (one row per real status change, including the first marking), student_attendance_session_runtime (last_submission_id, and a status-advance UPDATE on student_attendance_sessions when the first record is written).
• Cache: None.
• Jobs: None enqueued synchronously.
• Notifications: None synchronous — the reminder sweep may later see this session already opened and skip its own candidate check.
• Audit: ActivityAuditInterceptor records the call under StudentAttendance/CREATE (the first declared permission).

Error Cases

Edge Cases

• Replayed submissionId: no error, no new side effect, returns the current state.
• force: true with forcedReason omitted: accepted; forced_reason stays null.
• A single entry with status: null on a class that was never marked: no session existed, none created (the delete matches nothing), no error.
• Every entry omits a pupil currently on the roll: that pupil is simply left unchanged — never implicitly unmarked.

Example Requests

PUT /api/attendance/students HTTP/1.1
Authorization: Bearer TOKEN
Content-Type: application/json

curl -X PUT "$API_URL/api/attendance/students" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"classPublicId":"018f2c4a-...","date":"2026-09-13","expectedVersion":null,"submissionId":"018f2c4b-...","entries":[{"studentId":"018f2c4c-...","status":"present"}]}'

8.3 PATCH /api/attendance/students/:recordId

Purpose

Corrects one pupil's already-existing record, keyed on the record's own version rather than the session's. Use this for a single fix after the fact — including against a completed register, which this route is deliberately permitted to touch.

Source Evidence

Auth and Permissions

• Auth: JWT required.
• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: StudentAttendance_UPDATE.
• Guest support: No.
• Idempotency: No — a repeated identical PATCH still requires the current expectedVersion and bumps version again.

Request

{ "status": "excused", "note": "Doctor's appointment", "reason": "Parent provided a note after the fact", "expectedVersion": 0 }

Response

200, StudentAttendanceRecordDto (§6.10).

Side Effects

• Writes: student_attendance_records (the one row), attendance_change_log (one row, reason carried from the DTO).
• No cache, job, or notification effects.

Error Cases

Edge Cases

• Correcting a completed register succeeds — this is the correction path for a closed day.
• reason is written only to the change log, never to the record itself.

Example Requests

curl -X PATCH "$API_URL/api/attendance/students/018f2c4c-.../history" \
  -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
  -d '{"status":"excused","expectedVersion":0}'

8.4 POST /api/attendance/students/complete

Purpose

Closes a register once every pupil on the current roll has a record. Called from the "finish taking attendance" action.

Source Evidence

student-attendance.controller.ts:110-125; admin/student-attendance-lifecycle.service.ts:57-102; dto/student-attendance.dto.ts:156-170.

Auth and Permissions

StudentAttendance_UPDATE. Same guard chain as above.

Request

Body: CompleteAttendanceDto (§6.5) — classPublicId, date, expectedVersion.

Response

200, StudentAttendanceStateDto with session.status: "completed".

Side Effects

Writes student_attendance_sessions only (status, completed_at, completed_by_user_id). No record/log write.

Error Cases

Edge Cases

A pupil enrolled after the register was opened but before completion is included in the same-transaction roster read, so completion still correctly requires them to be marked.

8.5 POST /api/attendance/students/reopen

Purpose

Returns a completed register to in_progress so it can be bulk-corrected via PUT again.

Source Evidence

student-attendance.controller.ts:127-139; admin/student-attendance-lifecycle.service.ts:104-137.

Auth and Permissions

StudentAttendance_UPDATE.

Request

Body: ReopenAttendanceDto (identical shape to CompleteAttendanceDto).

Response

200, StudentAttendanceStateDto with session.status: "in_progress", completedAt: null.

Error Cases

8.6 POST /api/attendance/students/reset

Purpose

Clears a class's entire register for one date — deletes every record, logs one deletion per previously-marked pupil, and returns the session to not_started. The most destructive route in this module; use it to recover from a mismarked day, not for a routine correction (which is PATCH .../:recordId).

Source Evidence

student-attendance.controller.ts:141-157; admin/student-attendance-lifecycle.service.ts:155-215.

Auth and Permissions

StudentAttendance_DELETE — a distinct permission code from the mark/correct/complete/reopen paths, which all use _UPDATE.

Request

Body: ResetAttendanceDto (identical shape to CompleteAttendanceDto). expectedVersion is required here for the same reason it is required on complete and reopen — a stale screen must not be able to erase marks someone else just saved.

Response

200, StudentAttendanceStateDto with session.status: "not_started", roster entirely unmarked, tally.markedCount: 0.

Side Effects

• Writes: DELETE on every student_attendance_records row for the session; one attendance_change_log row per deleted record (newStatus: null); student_attendance_sessions reset; student_attendance_session_runtime.last_submission_id cleared.

Error Cases

Edge Cases

Resetting a register with nothing marked yet: succeeds as a near no-op (session status write only; nothing to delete or log).

8.7 GET /api/attendance/students/:studentId/history

Purpose

A pupil's full attendance change history, including the first marking of every day, keyset-paginated. Use this for a pupil's attendance detail/history screen.

Source Evidence

student-attendance-history.controller.ts:20-45; admin/attendance-history.service.ts; dto/attendance-history.dto.ts.

Auth and Permissions

StudentAttendance_READ.

Request

Response

200:

{
  "success": true,
  "message": "History fetched.",
  "data": [
    { "id": "018f...", "attendanceDate": "2026-09-13", "previousStatus": null, "newStatus": "present", "reason": null, "classLabel": "Grade 5 A (Morning)", "changedByName": "Sunita Adhikari", "changedAt": "2026-09-13T02:35:00.123Z" }
  ],
  "nextCursor": "eyJ..."
}

data is the array; nextCursor is a top-level envelope field, null on the last page.

Error Cases

Edge Cases

• A day the pupil was marked once, never corrected: one entry, previousStatus: null.
• A bulk mark of many pupils on one day, viewed for one pupil: their single entry among the tied changed_at timestamps is still returned exactly once, at the correct page boundary.
• Empty result (no history yet): data: [], nextCursor: null.

8.8 GET /api/attendance/overview

Purpose

The whole school's attendance state for one date, one row per active class in the academic session containing that date — the office's "who hasn't taken the register yet" screen.

Source Evidence

attendance-overview.controller.ts; attendance-overview.service.ts; dto/attendance-overview.dto.ts.

Auth and Permissions

StudentAttendance_READ.

Request

Query: date (required).

Response

200, array of AttendanceOverviewRowDto (§6.12). Empty array when no active session contains the date, or the session has no active classes.

Error Cases

None specific — an unresolvable date returns [] rather than erroring.

Edge Cases

• A class with a published timetable but no period on that weekday: scheduleState: "no_period_today".
• A class never opened for the date: sessionStatus: null, all counts 0.
• unalertedAbsences can be nonzero even after the sweep has run, briefly, if the sweep tick has not yet reached that class's records.

8.9 GET /api/attendance/staff

Purpose

Lists the staff/teacher register for one date, optionally filtered by designationId for the Teachers/Staff tabs, paginated.

Source Evidence

staff-attendance.controller.ts:46-70; staff-attendance.service.ts:98-169.

Auth and Permissions

StaffAttendance_READ.

Request

Query: date (required), designationId (optional), page, size (default 1/20).

Response

200, StaffAttendanceListDto (§6.14), with pagination metadata (count, page, size) via PaginationUtil.

Side Effects

None — read-only.

Edge Cases

An unmarked staff member appears in the list with status: null, recordId: null — never omitted.

8.10 PUT /api/attendance/staff

Purpose

Marks the staff/teacher register for one date, including on a holiday or exam day (the calendar gate is never consulted here). Last write for the date wins — there is no concurrency token on this path.

Source Evidence

staff-attendance.controller.ts:72-90; staff-attendance.service.ts:183-311; dto/staff-attendance.dto.ts:159-169.

Auth and Permissions

StaffAttendance_CREATE AND StaffAttendance_UPDATE.

Request

Body: BulkStaffAttendanceDto — date, entries[] (§6.15). No expectedVersion, no submissionId.

{ "date": "2026-09-13", "entries": [{ "staffId": "018f...", "status": "present" }] }

Response

200, { date, entries: StaffAttendanceRowDto[], tally: StaffAttendanceTallyDto }.

Side Effects

Writes: staff_attendance_records (upsert marked, delete status: null), attendance_change_log (one row per real change, including the first marking).

Error Cases

Edge Cases

• Marking on a public holiday: succeeds.
• Two administrators submitting the same day simultaneously: whichever transaction commits last wins entirely; both are individually logged, with no conflict surfaced to either caller.

8.11 PATCH /api/attendance/staff/:recordId

Purpose

Corrects one staff attendance record, using that record's own version — unlike the bulk write, this path has a real row to check optimistically.

Source Evidence

staff-attendance.controller.ts:92-107; staff-attendance.service.ts:315-404; dto/staff-attendance.dto.ts:171-209.

Auth and Permissions

StaffAttendance_UPDATE.

Request

Params: recordId. Body: PatchStaffAttendanceDto (§6.16).

Response

200, StaffAttendanceRowDto — re-read after the write, never an echo.

Error Cases

8.12 GET /api/attendance/staff/:staffId/history

Purpose

One staff member's attendance change history, keyset-paginated identically to the student history route.

Source Evidence

staff-attendance-history.controller.ts; staff-attendance.service.ts:414-490; dto/staff-attendance.dto.ts:211-250.

Auth and Permissions

StaffAttendance_READ.

Request

Params: staffId. Query: from, to, cursor, size.

Response

200, { data: StaffAttendanceHistoryEntryDto[], nextCursor } — same envelope shape as §8.7, built from Postgres's own ::text rendering of changed_at rather than date_trunc, closing the identical precision gap by a different route.

Error Cases

8.13 GET /api/attendance/settings

Purpose

Reads both attendance notification settings rows, for the settings screen.

Source Evidence

attendance-settings.controller.ts:43-55; attendance-settings.service.ts:39-71.

Auth and Permissions

AttendanceSettings_READ.

Response

200, AttendanceSettingsListDto — always both kinds, each carrying effectiveNote.

Error Cases

8.14 PUT /api/attendance/settings/:kind

Purpose

Updates which channels one attendance notification kind may use. Never creates a row — both are seeded by migration and this endpoint only edits them.

Source Evidence

attendance-settings.controller.ts:57-73; attendance-settings.service.ts:73-146; dto/attendance-settings.dto.ts:53-71.

Auth and Permissions

AttendanceSettings_UPDATE.

Request

Params: kind (attendance.first_period_reminder | attendance.student_absent). Body: UpdateAttendanceSettingsDto.

{ "enabled": true, "channels": ["push", "in_app", "sms", "email"], "expectedVersion": 0 }

Response

200, AttendanceSettingRowDto, re-read after the write.

Side Effects

Writes attendance_notification_settings. No downstream effect on any already-sent notification.

Error Cases

Edge Cases

Enabling email/sms here does not notify any recipient who has never opened their own notification preferences — CATEGORY_DEFAULTS.attendance still applies afterwards, defaulting both off.

8.15 GET /api/mobile/teacher/attendance/classes

Purpose

Lists the classes the calling teacher is the class teacher of, with occupancy counts, for the teacher's class-picker screen.

Source Evidence

teacher-attendance-portal.controller.ts:41-51; teacher-attendance-portal.service.ts:42-83.

Auth and Permissions

• Auth: JWT required.
• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: None — audience-asserted via assertTeacherStaffRow.
• Guest support: No.

Response

200, TeacherClassSummaryDto[] — empty array if the caller teaches no active class in the current academic session.

Error Cases

8.16 GET /api/mobile/teacher/attendance

Purpose

Reads one of the teacher's own classes' register for one date — identical response shape to the admin GET, scoped to a class they actually teach.

Source Evidence

teacher-attendance-portal.controller.ts:53-64; teacher-attendance-portal.service.ts:85-94.

Auth and Permissions

No @Permissions(); assertTeacherStaffRow plus assertOwnClass.

Request

Query: date, classPublicId (§6.19).

Response

200, StudentAttendanceStateDto (§6.9) — same shape as §8.1.

Error Cases

8.17 PUT /api/mobile/teacher/attendance

Purpose

Marks the teacher's own class's register — today only, and refused once completed, since correcting a closed day is the admin surface's job.

Source Evidence

teacher-attendance-portal.controller.ts:66-81; teacher-attendance-portal.service.ts:99-121; dto/teacher-attendance-portal.dto.ts:30-53.

Auth and Permissions

No @Permissions(); assertTeacherStaffRow plus assertOwnClass.

Request

Body: TeacherMarkAttendanceDto (§6.19) — identical to BulkMarkAttendanceDto minus force/forcedReason; sending either is a 400 via forbidNonWhitelisted.

Response

200, StudentAttendanceStateDto.

Side Effects

Identical to §8.2 — this route calls the exact same StudentAttendanceWriteService.bulkMark transaction with { refuseIfCompleted: true, requireToday: true }.

Error Cases

Same as §8.2, plus:

Edge Cases

A teacher submitting exactly at the school-local midnight boundary is evaluated against SchoolClockService.now(), not the request's own clock.

8.18 POST /api/mobile/teacher/attendance/complete

Purpose

Completes the teacher's own class's register once every pupil is marked.

Source Evidence

teacher-attendance-portal.controller.ts:83-94; teacher-attendance-portal.service.ts:123-135.

Auth and Permissions

No @Permissions(); assertTeacherStaffRow plus assertOwnClass.

Request

Body: TeacherCompleteAttendanceDto (§6.19).

Response

200, StudentAttendanceStateDto with session.status: "completed".

Error Cases

Same as §8.4, plus 403 ATTENDANCE_NOT_CLASS_TEACHER.

8.19 GET /api/mobile/student/attendance

Purpose

A pupil's own attendance, date-ranged, for their own attendance-history screen.

Source Evidence

student-attendance-portal.controller.ts; student-attendance-portal.service.ts; dto/student-attendance-portal.dto.ts.

Auth and Permissions

• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: None — assertPortalAudience(actor, "student").
• Takes no id parameter; the pupil is students.user_id = actor.id.

Request

Query: from, to (both required, @IsDateString).

Response

200, StudentAttendancePortalEntryDto[] (§6.19) — no markedBy, no staff identity.

{
  "success": true,
  "message": "Attendance fetched.",
  "data": [
    { "attendanceDate": "2026-09-13", "status": "present", "classLabel": "Grade 5 A (Morning)", "bsYear": 2083, "bsMonth": 5, "bsDay": 29, "note": null }
  ]
}

Error Cases

Edge Cases

A date outside the Bikram Sambat converter's supported range (2000–2090 BS) returns bsYear/bsMonth/bsDay: 0/0/0 for that row rather than failing the page — unreachable in practice for any date attendance could have been recorded on.

8.20 GET /api/mobile/guardian/children/:studentId/attendance

Purpose

One child's attendance, date-ranged, as read by their guardian. Used by the guardian's per-child attendance screen.

Source Evidence

guardian-attendance-portal.controller.ts; guardian-attendance-portal.service.ts; dto/guardian-attendance-portal.dto.ts.

Auth and Permissions

• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: None — assertPortalAudience(actor, "guardian") plus a ward check.

Request

Params: studentId (uuid). Query: from, to.

Response

200, GuardianAttendancePortalEntryDto[] — same shape as §8.19, no markedBy.

Error Cases

Edge Cases

A guardian with two children can never distinguish, from this route's response, whether a 404 means "wrong id" or "not your child" — that ambiguity is deliberate, so the id space cannot be probed as an enumeration oracle.

8.21 GET /api/mobile/student/attendance/summary

Purpose

A pupil's attendance totals for the current academic session, from the session start to today. Feeds the pupil dashboard.

Source Evidence

student-attendance-portal.controller.ts (mySummary); student-attendance-portal.service.ts (resolveOwnStudentId); portal/shared/portal-attendance-summary.service.ts; portal/shared/portal-attendance-summary.dto.ts; apps/api/src/modules/reports/portal/queries/portal-attendance.query.ts; apps/api/src/common/utils/cache-race.util.ts.

Auth and Permissions

• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: None — assertPortalAudience(actor, "student"). The handler key StudentAttendancePortalController.mySummary is in NO_PERMISSION_ADMIN_HANDLERS.
• The route takes no id. The pupil is resolved from the token (students.user_id = actor.id, deleted_at only).

Request

No params, query or body.

Response

{
  "message": "Attendance summary fetched.",
  "data": {
    "academicSessionName": "2082/83",
    "from": "2026-04-14",
    "to": "2026-10-06",
    "expectedDays": 120,
    "marked": 118,
    "present": 104,
    "late": 6,
    "absent": 5,
    "excused": 3,
    "unmarked": 2,
    "ratePct": 93.22
  },
  "errorCode": null
}

Fields are described under Portal DTOs in §6.19.

Error Cases

Edge Cases

• The window ends at school-local today, never at the session's end date, so a required day that has not happened yet is not counted as expected. The end date is inclusive.
• A pupil is expected only on days inside an enrolment span in the current session (enrolled_on <= day and ended_on null or after the day), so a mid-year transfer counts each class for its own days.
• ratePct is null when marked is 0. unmarked counts expected days that have no mark yet, so a day the teacher has not registered is not treated as absent.
• The totals are cached for 60 seconds per pupil and school-local date, so a mark made in the register can take up to 60 seconds to appear. See §11.

Example Requests

curl -X GET "$API_URL/api/mobile/student/attendance/summary" \
  -H "Authorization: Bearer TOKEN"

8.22 GET /api/mobile/guardian/children/:studentId/attendance/summary

Purpose

One child's attendance totals for the current academic session, as read by their guardian. Same payload as §8.21.

Source Evidence

guardian-attendance-portal.controller.ts (childSummary); guardian-attendance-portal.service.ts (resolveChildId, resolveWard); portal/shared/portal-attendance-summary.service.ts.

Auth and Permissions

• Guard chain: JwtAuthGuard, RoleGuard.
• Permission: None — assertPortalAudience(actor, "guardian") plus the ward check. The handler key GuardianAttendancePortalController.childSummary is in NO_PERMISSION_ADMIN_HANDLERS.
• The ward check runs first; the cache is read only for an id that passed it.

Request

Params: studentId (uuid; a non-UUID value is a 400 from ParseUUIDPipe). No query or body.

Response

200, PortalAttendanceSummaryDto — the same shape as §8.21, with message: "Attendance summary fetched.".

Error Cases

Edge Cases

• The cache entry is keyed by pupil, not by caller, and is reachable only after identity is resolved, so the pupil route and the guardian route share one entry.
• Windowing, expected-day and rate rules are those of §8.21.

Example Requests

curl -X GET "$API_URL/api/mobile/guardian/children/01922e2d-3c4d-7c3a-9d2e-1a2b3c4d5e6f/attendance/summary" \
  -H "Authorization: Bearer TOKEN"

9. Flow Diagrams

9.1 Route Ownership

9.2 Request Sequence — bulk mark (either surface)

9.3 Error Branch

10. Pagination, Sorting, Filtering, and Search

No endpoint in this module supports free-text search or client-chosen sort fields. The staff list computes its full roster and tally before slicing to a page — the tally therefore always reflects the whole roster, never just the visible page. Both history routes reject a malformed cursor with 400 PAGINATION_CURSOR_INVALID rather than silently restarting; a caller should treat that specific code as "start over from page one."

11. Caching, Jobs, and External Integrations

13. Mandatory Deep API Documentation Pack

13.1 Route-by-Route Completeness Matrix

13.2 Request/Response Exhaustiveness

Covered per-endpoint in §8 above — every mutating route includes a minimal and (where the DTO has optional fields) a full example; every route documents its success response, its representative validation/domain errors, and (where applicable) its empty-result behavior.

13.3 API Diagram Pack

See §9 for the route-ownership graph, the bulk-mark sequence diagram, and the shared error decision tree — the same three shapes apply, with only the actor and the entry guard changing, across every mutating route in this module (admin PUT/PATCH/POST and the teacher portal's PUT/POST).

13.4 Consumer Integration Notes

13.5 API Tradeoffs and Rationale

13.6 API Change Impact

14. Zero-Omission API Checklist

• Every controller route is documented (§4, §8).
• Every parent route prefix and runtime URL is documented (§4).
• Every DTO field, nested field, enum, default, and validator is documented (§6, §7).
• Every response field, nullable field, and generated field is documented (§6.6–§6.19).
• Every auth, guard, permission, and audience-assertion branch is documented (§5, §8).
• Every success, validation, permission, not-found, conflict, and server-error branch is documented (§8's Error Cases tables).
• Every database touch, and the absence of any cache/queue/notification side effect where true, is documented (§8's Side Effects, §11).
• Every route has minimal/full-request and success/error examples where a body applies (§8).
• Every endpoint family has route, sequence, and error diagrams (§9).
• Every tradeoff is documented (§13.5).
• The API doc links to backend and features/flows (below).

15. Integration Checklist

• Every route from controllers is documented.
• Every DTO field is documented.
• Every enum value is documented.
• Every response envelope is documented.
• Every error code is documented.
• Every auth guard and permission (or its deliberate absence) is documented.
• Every cache key (none), queue job, and external call is documented.
• Every diagram matches the current code.
• The API doc links to backend and features/flows.

See Also

• Backend doc: /docs/developer/attendance/backend
• Features and flows doc: /docs/developer/attendance/feature