Leave - API Reference

Audience: Frontend engineers, mobile engineers, backend engineers, QA, and API consumers. Scope: Admin (office/permission-holder) and mobile-audience (guardian, student, teacher, staff) APIs owned by Leave.

1. Documentation Evidence

2. Module Summary

3. Concepts and Terminology

4. API Surface Map

37 routes total: 5 leave-type, 10 pupil-admin, 10 staff-admin, 3 student-portal, 4 guardian-portal, 2 teacher-portal, 3 staff-portal. LeaveTypesModule, StudentLeavesModule and StaffLeavesModule are named in ADMIN_MODULES (swagger-documents.ts); the four portal modules are reached via MOBILE_CHILDREN in mobile.module.ts and appear in the mobile document by reflection, never by a second listing in ADMIN_MODULES.

5. Auth, Identity, and Permissions

Every route in this module requires a valid session. There is no @Public() route and no guest-accessible route anywhere in Leave.

Which permission a caller must hold. LeaveTypes_*, StudentLeaves_*, StaffLeaves_*, StudentLeaveDecisions_UPDATE, StaffLeaveDecisions_UPDATE are all held by superadmin only, among the five seeded system roles (superadmin, staff, teacher, guardian, student). staff/teacher/guardian/student hold LeaveView_READ only (gates a panel screen, zero API routes). A school delegating office/admin leave duties creates a role and grants it the specific codes it needs.

The twelve permission-less mobile handlers and why they are still safe. RoleGuard returns true at the point it checks NO_PERMISSION_ADMIN_HANDLERS, BEFORE it reads request.user or refuses a missing active role — so the ONLY control on these routes is JwtAuthGuard (proves a session exists) plus the handler's own assertPortalAudience/assertTeacherStaffRow/assertStaffRow call (proves WHO is calling) plus the service's own hand-built row predicate (decides WHICH rows). None of the three routes to PeopleAccessService.scopeFor, which would have returned {kind: "all"} for the seeded staff/teacher roles and leaked every pupil's requests to any teacher session.

403 vs. 404, precisely. An audience mismatch (a guardian session calling a teacher route, for instance — not directly possible here since each controller is mounted under its own audience, but relevant if a caller forges the wrong role) is 403. A row outside the caller's own scope — someone else's child, another teacher's class, an already-decided request — is 404, identical to a row that does not exist at all. This is deliberate: an id space over a roll of children must never become an enumeration oracle.

6. DTO and Model Reference

6.1 CreateLeaveTypeDto (request, admin POST /api/leave-types)

6.2 UpdateLeaveTypeDto (request, admin PATCH /api/leave-types/:publicId)

Every field from §6.1 except code, all optional. code is deliberately absent — immutable after create.

description is the one field whose omission and null differ: omitting it leaves the stored description unchanged, while null, an empty string or whitespace clears it to null. Any other value is trimmed. On create, an empty or whitespace-only description is stored as null too.

description is the only nullable field. Sending null for label, appliesToStudent, appliesToStaff, isActive or sortOrder is refused with 400 VALIDATION_FAILED; omit the field to leave it unchanged.

6.3 ListLeaveTypesQueryDto (query, admin GET /api/leave-types)

Extends QueryDto (pagination, page, size, sort, order, search — see §10). Adds:

search matches label OR code.

6.4 LeaveTypeDto (response)

6.5 CreateStudentLeaveDto (request, admin POST /api/student-leaves)

Extends CreateLeaveRequestBaseDto (§6.9) and adds:

studentId is the ONLY field beyond the shared base — every other server-derived column (subjectKind, origin, status, classId, enrollmentId, academicSessionId, dayCount, raisedByUserId) is fixed by the service, never accepted here. Naming which pupil is unavoidable on a flat /api/student-leaves collection route with no :studentId path segment.

6.6 UpdateStudentLeaveDto (request, admin PATCH /api/student-leaves/:id)

Identical to UpdateLeaveRequestBaseDto (§6.10) — no pupil-specific field. Dates are immutable after create; only leaveTypeId and reason are accepted.

6.7 ListStudentLeavesQueryDto (query, admin GET /api/student-leaves)

Extends ListLeaveRequestsQueryDto (§6.11) and adds:

6.8 CreateStaffLeaveDto / UpdateStaffLeaveDto / ListStaffLeavesQueryDto (staff admin equivalents)

CreateStaffLeaveDto extends CreateLeaveRequestBaseDto and adds staffId: string (uuid, required) — the colleague this leave is filed for (staff.id). UpdateStaffLeaveDto is identical to UpdateLeaveRequestBaseDto. ListStaffLeavesQueryDto adds NO field beyond ListLeaveRequestsQueryDto — staff carry no class to filter by. Source: staff-leave.dto.ts.

6.9 CreateLeaveRequestBaseDto (shared base)

6.10 UpdateLeaveRequestBaseDto (shared base)

6.11 ListLeaveRequestsQueryDto (shared admin query base)

Extends QueryDto (§10). Adds:

6.12 LeaveRequestDto (response, admin)

The three attendance* fields are present on every response that returns this DTO — list, detail, create (including an idempotent replay by submissionId), update, restore, decision and reapply-attendance — for both pupil and staff requests. They are null together for a request with no runtime row.

6.13 LeaveDecisionDto (response, admin — GET .../:id/decisions)

6.14 LeaveSummaryDto (response, admin GET .../summary)

6.15 DecideLeaveDto (request, admin POST .../:id/decision)

Carries deliberately NO subject, status, or actor field — the next status is derived from the row's CURRENT status inside the decision transaction, never sent by the caller.

6.16 CreateGuardianLeaveRequestDto (request, mobile POST /api/mobile/guardian/leaves)

6.17 GuardianLeaveDecisionDto / GuardianCancelLeaveRequestDto (request)

GuardianLeaveDecisionDto: decision ("approved"|"rejected", required), note (optional string), expectedVersion (optional, nullable int — when omitted, the service uses the row's OWN current version rather than refusing). GuardianCancelLeaveRequestDto: expectedVersion only, same optionality.

6.18 GuardianLeaveRequestDto (response, mobile)

6.19 CreateStudentLeaveRequestDto / CancelLeaveRequestDto / StudentLeaveRequestDto (mobile, pupil self-serve)

CreateStudentLeaveRequestDto: leaveTypePublicId, startDate, endDate, reason (min 3), submissionId (optional) — no studentId field, since the route resolves the caller's own id. CancelLeaveRequestDto: expectedVersion only. StudentLeaveRequestDto matches GuardianLeaveRequestDto's shape (§6.18) minus studentId/studentName (the caller IS the subject) — reason is present, since this is the pupil's own record. Source: student-leave-portal.dto.ts.

6.20 ListTeacherLeaveRequestsQueryDto / TeacherLeaveDecisionDto / TeacherLeaveRequestDto

ListTeacherLeaveRequestsQueryDto adds nothing beyond QueryDto. TeacherLeaveDecisionDto: decision, note (optional), expectedVersion (optional, nullable). TeacherLeaveRequestDto:

Deliberately carries NO reason field. This is the ONLY teacher-facing leave projection — there is no GET .../:id detail route, so there is nothing else to keep in step. Source: teacher-leave-portal.dto.ts.

6.21 CreateStaffLeaveRequestDto / StaffCancelLeaveRequestDto / StaffLeaveRequestDto

CreateStaffLeaveRequestDto: leaveTypePublicId, startDate, endDate, reason (min 3), submissionId (optional) — no staffId field. StaffCancelLeaveRequestDto: expectedVersion only. StaffLeaveRequestDto matches StudentLeaveRequestDto's shape, with dayCount documented as CALENDAR days (staff are not calendar-gated) and origin restricted to "self" | "staff_on_behalf" (a staff member never sees guardian origin on their own record — that value exists only for student-subject rows). Source: staff-leave-portal.dto.ts.

7. Enum Reference

8. Endpoint Reference

8.1 GET /api/leave-types

Purpose

Lists the leave-type catalogue for a select box, a management screen, or any consumer needing to resolve a code/label pair. Supports the reference-table convention: pagination=false is ALLOWED here (bounded at 1000 rows), unlike every leave-request list.

Source Evidence

Auth and Permissions

• Auth: JWT
• Guard chain: JwtAuthGuard, RoleGuard
• Permission: LeaveTypes_READ
• Guest support: No
• Rate limit: None specific
• Idempotency: N/A (read)

Request

Response

{
  "success": true,
  "message": "Leave types fetched.",
  "data": [
    {
      "publicId": "0199a1e0-0000-7000-8000-0000000f5e01",
      "code": "sick",
      "label": "Sick leave",
      "description": null,
      "appliesToStudent": true,
      "appliesToStaff": true,
      "isActive": true,
      "sortOrder": 10,
      "version": "0",
      "createdAt": "2026-08-01T00:00:00.000Z",
      "updatedAt": "2026-08-01T00:00:00.000Z"
    }
  ],
  "count": 3,
  "currentPage": 1,
  "totalPage": 1
}

Side Effects

None — read only.

Error Cases

Edge Cases

• Empty catalogue (never happens in a seeded environment — three types always exist unless deleted): empty array, count: 0.
• ?search= blank: no filter applied (query DTO trims and drops empty strings).
• pagination=false: allowed, capped at PaginationUtil.UNPAGINATED_HARD_CAP (1000).

Example Requests

curl -X GET "$API_URL/api/leave-types?isActive=true" \
  -H "Authorization: Bearer TOKEN"

8.2 POST /api/leave-types

Purpose

Creates a new leave type. Called from a settings/catalogue management screen.

Source Evidence

Auth and Permissions

• Permission: LeaveTypes_CREATE
• Idempotency: None — no submissionId on this DTO; a genuine duplicate code is refused by the unique index, not silently deduplicated.

Request

{ "code": "sick", "label": "Sick leave", "appliesToStudent": true, "appliesToStaff": true }

Response

201, same shape as §8.1's array element (one object, not wrapped in an array).

Side Effects

• leave_types insert.

Error Cases

Edge Cases

• Omitting both appliesTo* flags: defaults both to true (applies to everyone).
• Reusing a code held by a RETIRED (soft-deleted) type: refused — the partial unique index still counts a live row with that code as taken only while it's live, but a NEW create with a colliding code against a retired one is fine (the retired row is excluded by the partial index); the refusal above is for a collision with a LIVE type.

Example Requests

curl -X POST "$API_URL/api/leave-types" \
  -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
  -d '{"code":"maternity","label":"Maternity leave","appliesToStudent":false,"appliesToStaff":true}'

8.3 PATCH /api/leave-types/:publicId

Purpose

Corrects a leave type's label, description, applicability, active state, or sort order. code is not accepted.

Source Evidence

Same files as §8.2, plus UpdateLeaveTypeDto.

Auth and Permissions

Permission: LeaveTypes_UPDATE.

Request

{ "label": "Sick / medical leave", "isActive": false }

All fields optional; only supplied fields are written.

Response

200, updated LeaveTypeDto — version incremented by the bump_row_version trigger.

Side Effects

• leave_types update. Trigger bumps version/updated_at.

Error Cases

Edge Cases

• Sending code: silently stripped by ValidationPipe's whitelist (the DTO has no such field) — never a 400, never applied.
• Deactivating a type currently in use: succeeds; existing requests are unaffected, only NEW requests against it are refused.

8.4 DELETE /api/leave-types/:publicId

Purpose

Retires a leave type (soft delete). Existing requests filed against it keep displaying it.

Source Evidence

Same files as §8.2.

Auth and Permissions

Permission: LeaveTypes_DELETE.

Request

No body.

Response

{ "success": true, "message": "Leave type retired.", "data": null }

Side Effects

• leave_types.deleted_at set.

Error Cases

Edge Cases

• Deleting a type currently pending_guardian/pending_school on a live request: succeeds; reads never filter deleted_at on leave_types from the leave_requests join, so those requests still show the type's code/label.

8.5 POST /api/leave-types/:publicId/restore

Purpose

Restores a retired leave type.

Source Evidence

Same files as §8.2.

Auth and Permissions

Permission: LeaveTypes_RESTORE.

Response

200, restored LeaveTypeDto.

Side Effects

• leave_types.deleted_at cleared.

Error Cases

Edge Cases

• The restore-collision case above is the one place remove/restore on this table can surface a conflict a naive reading of "it's just an undelete" would not expect.

8.6 GET /api/student-leaves

Purpose

The office's roll of pupil leave requests — the primary list screen for processing consents and decisions.

Source Evidence

Auth and Permissions

Permission: StudentLeaves_READ. Pagination CANNOT be disabled (PAGINATION_LIMIT_INVALID if attempted) — this is a roll of children, not a reference table.

Request

Response

{
  "success": true,
  "message": "Student leaves fetched.",
  "data": [
    {
      "id": "0199b2c0-1111-7000-8000-000000000001",
      "subjectKind": "student",
      "subjectId": "...",
      "subjectName": "Aarav Sharma",
      "subjectCode": "2026-A-0142",
      "classId": "...",
      "leaveTypeId": "0199a1e0-0000-7000-8000-0000000f5e01",
      "leaveTypeCode": "sick",
      "leaveTypeLabel": "Sick leave",
      "academicSessionId": "...",
      "startDate": "2026-08-10",
      "endDate": "2026-08-12",
      "dayCount": 3,
      "status": "pending_guardian",
      "origin": "self",
      "reason": "Fever, advised bed rest.",
      "submissionId": null,
      "raisedByUserId": "...",
      "decidedByUserId": null,
      "decidedAt": null,
      "decisionNote": null,
      "cancelledByUserId": null,
      "cancelledAt": null,
      "attendanceAppliedAt": null,
      "attendanceDaysWritten": null,
      "attendanceRevertedAt": null,
      "version": "0",
      "createdAt": "2026-08-08T09:00:00.000Z",
      "updatedAt": "2026-08-08T09:00:00.000Z"
    }
  ],
  "count": 1,
  "currentPage": 1,
  "totalPage": 1
}

Side Effects

None.

Error Cases

Edge Cases

• ?search= matches the reason OR the pupil's name (an EXISTS subquery, not a join, so the same builder still serves /summary and the count).
• ?classId= naming a class publicId nobody owns: matches nothing (filtered to -1), never ignored.
• Rows filed against a RETIRED leave type still show the type's code/label (no deleted_at filter on that join).
• Default sort is createdAt, not updatedAt — the shared QueryDto's documented default (updatedAt) is NOT honored here; only sort=startDate changes the order column, any other value (including the literal updatedAt) falls through to createdAt.

8.7 GET /api/student-leaves/summary

Purpose

Status tallies (total / pending / approved / rejected) for a dashboard tile or the list screen's header, over the SAME filters the list accepts.

Source Evidence

Same controller/service as §8.6. Declared BEFORE :id in the controller, or Nest would match summary as a request id.

Auth and Permissions

Permission: StudentLeaves_READ.

Request

Same query fields as §8.6 (minus pagination/sort, which are irrelevant to a count).

Response

{
  "success": true,
  "message": "Student leave summary fetched.",
  "data": { "total": 42, "pendingApproval": 5, "approved": 30, "rejected": 7 }
}

Error Cases

None specific beyond the shared auth failures.

Edge Cases

• pendingApproval sums BOTH pending_guardian and pending_school — there is no separate count per step.
• Counted over a count(*) FILTER (WHERE ...) against the identical buildWhere predicate the list uses, so the numbers are guaranteed to agree with what the list under the same filter would show.

8.8 GET /api/student-leaves/:id

Purpose

One pupil leave request, in full.

Source Evidence

Same as §8.6.

Auth and Permissions

Permission: StudentLeaves_READ.

Request

Response

Single LeaveRequestDto (§6.12), wrapped: { "success": true, "message": "Student leave fetched.", "data": { ... } }.

Error Cases

Edge Cases

• Requesting a staff-subject id through this pupil-only route: 404, not a type-mismatch error — the WHERE clause filters subject_kind = student unconditionally.
• Soft-deleted rows ARE returned here (no deleted_at filter on findOne) — deletion status is visible on data, not hidden.

8.9 GET /api/student-leaves/:id/decisions

Purpose

The full decision trail for one request — every consent/refusal, in capacity and order.

Source Evidence

Same as §8.6, plus leave_request_decisions.

Auth and Permissions

Permission: StudentLeaves_READ.

Response

{
  "success": true,
  "message": "Decisions fetched.",
  "data": [
    {
      "id": "...",
      "step": "guardian",
      "decision": "approved",
      "actedAs": "guardian",
      "decidedByUserId": "...",
      "decidedByNameSnapshot": "Priya Sharma",
      "note": null,
      "previousStatus": "pending_guardian",
      "newStatus": "pending_school",
      "decidedAt": "2026-08-09T10:00:00.000Z"
    }
  ]
}

Error Cases

Edge Cases

• A brand-new request: empty array, not an error.
• Ordered decidedAt DESC, id DESC — a reversal writing two rows in one transaction (identical decided_at) still orders deterministically by the monotonic uuid v7 id.

8.10 POST /api/student-leaves

Purpose

The office files a pupil leave request on someone's behalf — a note received by phone or on paper.

Source Evidence

Same as §8.6, plus LeaveResolutionService.

Auth and Permissions

Permission: StudentLeaves_CREATE.

Request

{
  "studentId": "...",
  "leaveTypeId": "0199a1e0-0000-7000-8000-0000000f5e01",
  "startDate": "2026-08-10",
  "endDate": "2026-08-12",
  "reason": "Family travel, three days.",
  "submissionId": "0199b300-0000-7000-8000-000000000099"
}

subjectKind, origin, status, classId, enrollmentId, academicSessionId, dayCount, raisedByUserId are NEVER accepted — sending any of them is silently stripped (whitelist) rather than a 400, since they are not declared fields on the DTO.

Response

201, LeaveRequestDto. Always status: pending_guardian, origin: staff_on_behalf.

Side Effects

• leave_requests insert.

Error Cases

Edge Cases

• Retried POST with the same submissionId: returns the ORIGINAL row, 201-shaped, not a 409.
• Range partially inside the past: accepted — no "cannot be in the past" rule exists on the admin path either.

8.11 PATCH /api/student-leaves/:id

Purpose

Correct a filed request's leave type or reason. Dates, subject and status are immutable after create.

Source Evidence

Same as §8.6.

Auth and Permissions

Permission: StudentLeaves_UPDATE.

Request

{ "version": "0", "reason": "Fever, doctor's note attached." }

Response

200, updated LeaveRequestDto.

Side Effects

• leave_requests update (locked FOR UPDATE first); bump_row_version fires.

Error Cases

Edge Cases

• Sending startDate/endDate/studentId: stripped by whitelist, never applied — the docblock states plainly why (recomputing day_count/the exclusion window for an already-decided request would desync it from a register the decision may already have rewritten).
• Omitting leaveTypeId and reason both: succeeds as a no-op WRITE (the updatedAt stamp alone still fires the trigger, bumping version).

8.12 DELETE /api/student-leaves/:id

Purpose

Soft-delete a non-approved pupil leave request.

Source Evidence

Same as §8.6.

Auth and Permissions

Permission: StudentLeaves_DELETE.

Response

{ "success": true, "message": "Student leave deleted.", "data": null }

Error Cases

Edge Cases

• Deleting a pending_guardian/pending_school/rejected/cancelled row: succeeds — only approved is refused.

8.13 POST /api/student-leaves/:id/restore

Purpose

Restore a soft-deleted pupil leave request.

Source Evidence

Same as §8.6.

Auth and Permissions

Permission: StudentLeaves_RESTORE.

Response

200, restored LeaveRequestDto.

Error Cases

Edge Cases

• Restoring does not revive an approved status's side effects — a delete could not have happened to an approved row in the first place (§8.12).

8.14 POST /api/student-leaves/:id/decision

Purpose

Take the school's decision on a pupil request — OR reverse an already-approved one. This is the only route that can reach the reversal.

Source Evidence

Auth and Permissions

Permission: StudentLeaveDecisions_UPDATE — a SEPARATE permission from StudentLeaves_UPDATE, so correcting a typo never implies the power to decide.

Request

{ "decision": "approved", "expectedVersion": 1 }

Response

200, updated LeaveRequestDto.

Side Effects

• Approve from pending_school: status → approved; leave_request_decisions insert (step: school, actedAs: permission_holder); leave_request_runtime armed; LeaveJob.APPLY_ATTENDANCE enqueued via the outbox.
• Approve from pending_guardian: status → pending_school; decision row only, no job.
• Refuse: status → rejected; decision row only.
• Refuse an ALREADY-approved row (the reversal): status → rejected; decision row; LeaveJob.REVERT_ATTENDANCE enqueued.

Error Cases

Edge Cases

• No status pre-filter on this route (unlike the guardian/teacher portal decide routes) — it accepts ANY id and lets resolveNextStatus decide legality, which is what makes the reversal reachable here and nowhere else.
• The register write from an approval is ASYNC — this response returns before the attendance job runs; the register is not guaranteed rewritten by the time 200 is returned.

8.15 POST /api/student-leaves/:id/reapply-attendance

Purpose

Re-queue the attendance write for an approved request whose worker attempt dead-lettered — the decision committed and the register never caught up.

Source Evidence

Auth and Permissions

Permission: StudentLeaveDecisions_UPDATE.

Request

No body.

Response

200, LeaveRequestDto (unchanged status — this route only re-queues, it does not itself write the register).

Side Effects

• Outbox enqueue of LeaveJob.APPLY_ATTENDANCE, with a FRESH, timestamped dedupeKey (${jobName}_retry_${id}_${Date.now()}) — reusing the original key would let onConflictDoNothing silently swallow the retry.

Error Cases

Edge Cases

• Calling this against a request whose apply already succeeded: not refused — it re-queues anyway, and the worker's own idempotent claim (attendance_applied_at IS NULL) makes the redundant run a no-op.

8.16–8.25 Staff-leaves admin routes (/api/staff-leaves)

Mirror §8.6–§8.15 exactly, with these differences:

Response shape for every one of these ten is the SAME LeaveRequestDto/LeaveDecisionDto/LeaveSummaryDto as the pupil surface — subjectKind: "staff", classId: null always, subjectCode is the employee code rather than the admission number.

8.26 GET /api/mobile/student/leaves

Purpose

A pupil's own leave requests, for their leave screen.

Source Evidence

Auth and Permissions

• Auth: JWT
• Guard chain: JwtAuthGuard, RoleGuard
• Permission: NONE — assertPortalAudience(actor, "student")
• Guest support: No
• Rate limit: None specific
• Idempotency: N/A (read)

Request

ListMyLeaveRequestsQueryDto — QueryDto fields only, no leave-specific filter. pagination=false is REFUSED (PAGINATION_LIMIT_INVALID).

Response

{
  "success": true,
  "message": "Leave requests fetched.",
  "data": [
    {
      "id": "...",
      "leaveType": { "id": "...", "code": "sick", "label": "Sick Leave" },
      "startDate": "2026-09-20",
      "endDate": "2026-09-22",
      "dayCount": 3,
      "status": "pending_guardian",
      "origin": "self",
      "reason": "Fever and viral cold, advised bed rest.",
      "decisionNote": null,
      "decidedAt": null,
      "cancelledAt": null,
      "version": 0,
      "createdAt": "2026-09-18T08:00:00.000Z"
    }
  ],
  "count": 1,
  "currentPage": 1,
  "totalPage": 1
}

Error Cases

Edge Cases

• No results: empty array — a brand-new pupil with no leave history.
• version here is a NUMBER, not a string (unlike the admin LeaveRequestDto).

8.27 POST /api/mobile/student/leaves

Purpose

A pupil raises their own leave.

Source Evidence

Same as §8.26, plus guardian-leave-portal.resolvers.ts (shared resolution helpers).

Auth and Permissions

None — assertPortalAudience(actor, "student").

Request

{
  "leaveTypePublicId": "0199a1e0-0000-7000-8000-0000000f5e01",
  "startDate": "2026-09-20",
  "endDate": "2026-09-22",
  "reason": "Fever and viral cold, advised bed rest.",
  "submissionId": "0199b300-0000-7000-8000-0000000000aa"
}

No studentId field — the caller's own id is resolved server-side.

Response

201, StudentLeaveRequestDto. Always status: pending_guardian, origin: self.

Side Effects

• leave_requests insert.

Error Cases

Edge Cases

• Retroactive startDate (in the past): accepted.
• Retried with the same submissionId: returns the original row.

8.28 POST /api/mobile/student/leaves/:id/cancel

Purpose

Withdraws a request the pupil raised themselves, while it is still pending.

Source Evidence

Same as §8.26.

Auth and Permissions

None — assertPortalAudience(actor, "student").

Request

{ "expectedVersion": 0 }

expectedVersion is OPTIONAL and nullable — omitted, the check is skipped entirely.

Response

200, StudentLeaveRequestDto with status: cancelled.

Side Effects

• leave_requests update: status, cancelled_at, cancelled_by_user_id.

Error Cases

Edge Cases

• Cancelling a request the pupil's OWN guardian raised about them: refused (404) — the predicate is raised_by_user_id = actor.id, and the guardian, not the pupil, raised it.
• Cancelling after approval: refused (404) — approved is outside the cancellable-status set.

8.29 GET /api/mobile/guardian/leaves

Purpose

A guardian's view of every one of their children's leave requests.

Source Evidence

Auth and Permissions

None — assertPortalAudience(actor, "guardian").

Request

ListGuardianLeaveRequestsQueryDto — QueryDto fields only. pagination=false refused.

Response

Array of GuardianLeaveRequestDto (§6.18) — includes studentId/studentName per row, since one guardian can have several children.

Error Cases

Edge Cases

• Own-children predicate filters deleted_at ONLY (on guardians/students/users), never record_status — the identity layer's rule (Backend §11, and CLAUDE.md's own worked example).
• Multiple children: rows for all of them, interleaved by createdAt DESC.

8.30 POST /api/mobile/guardian/leaves

Purpose

A guardian files leave for their own child. Raising it IS the consent.

Source Evidence

Same as §8.29, plus guardian-leave-portal.resolvers.ts.

Auth and Permissions

None — assertPortalAudience(actor, "guardian"), then the child is resolved through ownChildrenWhere.

Request

{
  "studentId": "...",
  "leaveTypePublicId": "0199a1e0-0000-7000-8000-0000000f5e01",
  "startDate": "2026-09-20",
  "endDate": "2026-09-22",
  "reason": "Family travel, pre-arranged with the class teacher.",
  "submissionId": "0199b300-0000-7000-8000-0000000000bb"
}

Response

201, GuardianLeaveRequestDto. Always status: pending_school, origin: guardian — skips pending_guardian entirely.

Side Effects

• leave_requests insert.

Error Cases

Note: NO LEAVE_NO_GUARDIAN_TO_CONSENT on this path — the caller IS a guardian, filing.

Edge Cases

• A non-ward studentId: 404, never a 403 — an id space over a roll of children must not become an enumeration oracle.
• A child whose graduate access has ENDED (not merely grace) never resolves as a ward at all — ownChildrenWhere excludes them, so the request 404s as STUDENT_NOT_FOUND rather than reaching the graduate-access check.

8.31 POST /api/mobile/guardian/leaves/:id/decision

Purpose

The guardian's consent (or refusal) on a child's self-raised or office-filed request — the ONE decision this flow exists for.

Source Evidence

Same as §8.29, plus leave-decision.service.ts.

Auth and Permissions

None — assertPortalAudience(actor, "guardian"), row re-resolved through own-children + pending_guardian + the addressed-guardian precedence (isAddressedGuardian).

Request

{ "decision": "approved", "note": "Consented — travel dates confirmed.", "expectedVersion": 0 }

expectedVersion OPTIONAL — omitted, the service uses the row's own current version (never refuses on that basis alone).

Response

200, GuardianLeaveRequestDto.

Side Effects

• Approve: status → pending_school; decision row (step: guardian, actedAs: guardian). NO attendance job yet — that only arms on the SCHOOL step's approval.
• Refuse: status → rejected (terminal); decision row. No permission was needed to reach this.

Error Cases

Edge Cases

• A stranger's child's request: 404, never 403.
• The addressed-guardian precedence: legally flagged guardian first, then primary, then any live guardian — computed in JS over a small row set, not a correlated SQL subquery.

8.32 POST /api/mobile/guardian/leaves/:id/cancel

Purpose

Withdraws a request the guardian raised themselves, while pending.

Source Evidence

Same as §8.29.

Auth and Permissions

None — assertPortalAudience(actor, "guardian").

Request

{ "expectedVersion": 0 }

Response

200, GuardianLeaveRequestDto with status: cancelled.

Error Cases

Edge Cases

• Cancelling AFTER guardian consent moved it to pending_school: still cancellable — the predicate accepts either pending status, and raised_by_user_id is still the guardian regardless of which step it's now at.

8.33 GET /api/mobile/teacher/leaves

Purpose

The class teacher's decision queue — pupil requests routed to a class they are the class teacher of, awaiting the school step.

Source Evidence

Auth and Permissions

None — assertTeacherStaffRow(db, actor): the active role must be teacher, and the caller must have a live staff row.

Request

ListTeacherLeaveRequestsQueryDto — QueryDto fields only. pagination=false refused.

Response

Array of TeacherLeaveRequestDto (§6.20) — no reason field.

Error Cases

Edge Cases

• A class with class_teacher_id IS NULL: leaks to nobody — the predicate is never conditionally omitted.
• Superadmin calling this route: 403 — the active role is superadmin, not teacher; handled by the panel as an empty state rather than an error surface.

8.34 POST /api/mobile/teacher/leaves/:id/decision

Purpose

The class teacher's approve/refuse decision — the terminal decision for a pupil's leave (subject to the admin-only reversal, §8.14).

Source Evidence

Same as §8.33, plus leave-decision.service.ts.

Auth and Permissions

None — assertTeacherStaffRow, row re-resolved through classes.class_teacher_id = staffId + pending_school + subject_kind = student.

Request

{ "decision": "approved", "note": "Approved — informed of the missed unit test.", "expectedVersion": 0 }

Response

200, TeacherLeaveRequestDto.

Side Effects

• Approve: status → approved; decision row (actedAs: class_teacher); leave_request_runtime armed; LeaveJob.APPLY_ATTENDANCE enqueued.
• Refuse: status → rejected; decision row.

Error Cases

Edge Cases

• This route can NEVER reach approved a second time or reverse it — the WHERE clause requires pending_school, so an approved row is invisible to it, not merely refused inside the transaction.
• A staff (non-student) request: never matches — filtered out before the row is even locked.

8.35 GET /api/mobile/staff/leaves

Purpose

A staff member's own leave requests.

Source Evidence

Auth and Permissions

None — assertStaffRow(db, actor): any active role that is not guardian/student scoped, plus a live staff row. The teacher role is not required — non-teaching staff use this route, and so does a teacher acting as either staff or teacher.

Request

ListMyStaffLeaveRequestsQueryDto — QueryDto fields only. pagination=false refused.

Response

Array of StaffLeaveRequestDto (§6.21) — reason present (the caller IS the subject); dayCount documented as CALENDAR days.

Error Cases

Edge Cases

• A class teacher using this route sees only THEIR OWN staff-subject requests — never their pupils' (that's /api/mobile/teacher/leaves, a completely separate query).

8.36 POST /api/mobile/staff/leaves

Purpose

A staff member raises their own leave — no guardian step, no calendar gate.

Source Evidence

Same as §8.35.

Auth and Permissions

None — assertStaffRow(db, actor), as §8.35.

Request

{
  "leaveTypePublicId": "0199a1e0-0000-7000-8000-0000000f5e02",
  "startDate": "2026-09-20",
  "endDate": "2026-09-22",
  "reason": "Family emergency, need three days.",
  "submissionId": "0199b300-0000-7000-8000-0000000000cc"
}

Response

201, StaffLeaveRequestDto. Always status: pending_school, origin: self.

Side Effects

• leave_requests insert.

Error Cases

Note: NO LEAVE_STUDENT_NOT_ENROLLED, LEAVE_CALENDAR_NOT_GENERATED, or LEAVE_NO_SCHOOL_DAYS_IN_RANGE — none of these questions apply to a staff subject.

Edge Cases

• A leave request spanning a public holiday or exam block: accepted and counted in full — staff work those days and the register needs to describe them.

8.37 POST /api/mobile/staff/leaves/:id/cancel

Purpose

Withdraws a staff member's own request while it is pending.

Source Evidence

Same as §8.35.

Auth and Permissions

None — assertStaffRow(db, actor), as §8.35.

Request

{ "expectedVersion": 0 }

Response

200, StaffLeaveRequestDto with status: cancelled.

Error Cases

Edge Cases

• The cancellable-status set here is {pending_school} ONLY — narrower than the pupil/guardian portals' {pending_guardian, pending_school}, because a staff request never enters pending_guardian in the first place.

9. Flow Diagrams

9.1 Route Ownership

9.2 Request Sequence — decide (any surface)

9.3 Error Branch

10. Pagination, Sorting, Filtering, and Search

PaginationUtil.normalize/getDrizzleParams/buildMetadata are the shared implementation — see docs/BACKEND_RULES_DIGEST.md's pagination rules for the mechanism itself. The sort field's documented QueryDto default is updatedAt, but no leave list orders by it — the admin lists special-case sort=startDate only and fall through to createdAt for everything else (including the literal string "updatedAt"); every portal list ignores sort entirely.

11. Caching, Jobs, and External Integrations

13. Mandatory Deep API Documentation Pack

13.1 Route-by-Route Completeness Matrix

13.2 Request/Response Exhaustiveness

13.3 API Diagram Pack

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 — 37 routes).
• Every parent route prefix and runtime URL is documented (§4).
• Every DTO field, nested field, enum, default, transform, and validator is documented (§6, §7).
• Every response field, nullable field, generated field is documented (§6).
• Every auth, guard, permission, and guest identity branch is documented (§5).
• Every success, validation, auth, permission, not-found, conflict, and rate-limit (none) branch is documented (§8 per route).
• Every database read/write, queue job, and audit consequence is documented (§8 Side Effects, §11).
• Every route has examples for minimal request, success response, and representative failures (§8).
• Every endpoint family has route, sequence, and error diagrams (§9).
• Every tradeoff and compatibility risk is documented (§13.5, §13.6).
• The API doc links to backend and features/flows docs (below).

15. Integration Checklist

• Every route from controllers is documented — 37/37.
• Every DTO field is documented (§6).
• Every enum value is documented (§7).
• Every response envelope is documented (§8, ResponseDto shape).
• Every error code is documented (§8 per route; all 21 LEAVE_* codes accounted for, 4 explicitly marked unused).
• Every auth guard and permission (or its deliberate absence) is documented (§5).
• Every queue job is documented (§11, Backend §9); no cache key or external call exists.
• Every diagram matches the current code (§9).
• The API doc links to backend and features/flows docs.

See Also

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