Promotions - API Reference

Audience: Frontend engineers, mobile/panel engineers, backend engineers, QA. Scope: Admin routes at /api/promotions/* and two consumer-facing (portal) routes at /api/mobile/student/promotion-history and /api/mobile/guardian/children/:id/promotion-history.

1. Documentation Evidence

2. Module Summary

3. Concepts and Terminology

4. API Surface Map

5. Auth, Identity, and Permissions

Every route requires a valid JWT (the guard is global; there is no public/guest route in this module). Nothing in this module trusts a client-supplied identity field — the acting userId always comes from the verified token.

6. DTO and Model Reference

6.1 CreatePromotionCycleDto

6.2 UpdatePromotionCycleDto

6.3 RecomputeCycleDto / FinalizeCycleDto / CancelPromotionCycleDto / SupplementaryDto

6.4 PromotionCycleSummaryDto / PromotionCycleDetailDto

6.5 RecomputeResultDto / SupplementaryResultDto

6.6 Decision write DTOs (PutPromotionDecisionDto / BulkPromotionDecisionDto / CorrectPromotionDecisionDto / ConditionResolutionDto)

All extend the common outcome/targetGradePublicId/conditionText/conditionDeadline fields.

6.7 PromotionDecisionDto (response)

6.8 PromotionDecisionHistoryEntryDto (response)

Same core fields as PromotionDecisionDto minus studentName/studentIdCode/grade-class snapshot, plus isCurrent: boolean, decidedByName: string | null (null when the acting user's account is gone), and supersededAt: Date | null.

6.9 PromotionSettingsDto / UpdatePromotionSettingsDto

6.10 PromotionProgressionDto / PutPromotionProgressionDto

6.11 AcademicHistoryEntryDto (shared by admin + both portals)

{
  "academicSession": { "publicId": "...", "name": "2081", "startDate": "2024-04-01", "endDate": "2025-03-31", "isCurrent": false },
  "placements": [
    { "classPublicId": "...", "gradeName": "Grade 8", "sectionName": "B", "shift": "morning", "rollNumber": 12, "status": "active", "enrolledOn": "2024-04-05", "endedOn": null }
  ],
  "outcome": {
    "outcome": "promoted", "targetGradeName": "Grade 9", "conditionStatus": null,
    "conditionText": null, "conditionDeadline": null, "decidedAt": "2025-03-20T10:00:00Z", "corrected": false
  },
  "graduation": null
}

outcome is null unless the session's cycle is finalized. graduation is null unless a live (non-revoked) student_graduations row exists for that session. Never includes reason, recommendationReason, basis, decidedByUserId, superseded versions, or an exclusion reason — this shape is read by the pupil and their guardian.

7. Enum Reference

8. Endpoint Reference

8.1 POST /api/promotions/cycles

Purpose

Creates a new draft promotion cycle for an academic session, linking its final (and optional supplementary) basis exams. Called once per session, typically after the term's final exams have been scheduled.

Source Evidence

Auth and Permissions

• Auth: JWT
• Guard chain: JwtAuthGuard, RoleGuard
• Permission: Promotions_CREATE
• Guest support: No
• Idempotency: None — a second identical call creates a second cycle, unless refused by promotion_cycles_one_live_per_session.

Request

{
  "academicSessionPublicId": "b6c1...",
  "name": "2081 Final Promotion",
  "finalExamPublicIds": ["e1..."],
  "supplementaryExamPublicIds": []
}

Response

201:

{
  "success": true,
  "message": "Promotion cycle created.",
  "data": {
    "publicId": "...", "name": "2081 Final Promotion",
    "academicSessionPublicId": "...", "academicSessionName": "2081",
    "status": "draft", "publicationState": "none", "version": 0,
    "finalizedAt": null, "createdAt": "...", "updatedAt": "..."
  }
}

Side Effects

• DB writes: promotion_cycles insert, promotion_cycle_exams inserts.
• No cache, no job, no notification.

Error Cases

Edge Cases

• Empty finalExamPublicIds — refused by @ArrayMinSize(1) before the service runs.
• Duplicate ids in either list — refused by @ArrayUnique().
• Same exam in both lists — 400 PROMOTION_EXAM_INVALID.

8.2 GET /api/promotions/cycles

List cycles, filterable by status and academicSessionPublicId, standard QueryDto pagination. Ordered newest-first (createdAt desc, id asc as a tiebreaker).

8.3 GET /api/promotions/cycles/:publicId

Cycle detail: adds basisExams, countsByOutcome, countsBySource, pendingReasons (all over current decisions), and basisDrift (0 unless status === "finalized", in which case it is a fresh, on-the-fly recompute-and-diff count).

8.4 PATCH /api/promotions/cycles/:publicId

Draft only. Optional name and/or exam-id list replacement, version required. 409 PROMOTION_CYCLE_NOT_DRAFT / PROMOTION_CYCLE_STALE on failure.

8.5 DELETE /api/promotions/cycles/:publicId

Draft only. Body: { "reason": "..." } (3–1000 chars). Cancels the cycle. 409 PROMOTION_CYCLE_IN_USE if a non-cancelled rollover cycle references it.

8.6 POST /api/promotions/cycles/:publicId/recompute

Purpose

Recomputes every roster member's recommendation against current exam results and writes only what changed. Call this whenever exam results are published or corrected, before finalizing.

Auth and Permissions

• Permission: Promotions_UPDATE. Draft only.

Request

{ "version": 3 }

Response

{ "success": true, "message": "Promotion cycle recomputed.", "data": { "added": 2, "changed": 5, "unchanged": 118 } }

Error Cases

404 PROMOTION_CYCLE_NOT_FOUND, 409 PROMOTION_CYCLE_NOT_DRAFT, 409 PROMOTION_CYCLE_STALE (version mismatch).

8.7 POST /api/promotions/cycles/:publicId/finalize

Purpose

Locks in every current decision, moves the cycle to finalized, and (unless settings disable it) enqueues family notifications. This is the point past which draft-phase writes (manual, bulk, reset) are no longer possible for this cycle.

Auth and Permissions

• Permission: PromotionFinalize_UPDATE (withheld from the automatic admin grant — must be explicitly assigned).

Request

{ "version": 4, "acknowledgePending": false }

Response

200 with the updated PromotionCycleSummaryDto (status: "finalized", publicationState: "queued" if notifications are on).

Side Effects

• DB: promotion_cycles status flip; outbox_events row (if notifyOnPublish).
• Jobs: enqueues academic_year.publish_promotion_decisions.
• No notification is sent synchronously — delivery happens in the worker.

Error Cases

Edge Cases

• A pupil left the session between recompute and finalize — still counted correctly because finalize reuses the same computeCycleRecommendations call.
• acknowledgePending: true with zero pending decisions is a no-op flag — finalize proceeds regardless.

8.8 POST /api/promotions/cycles/:publicId/republish

Only from publication_state of none or failed. Re-enqueues with a fresh publication_attempt. 409 PROMOTION_CYCLE_NOT_FINALIZED / PROMOTION_PUBLICATION_INVALID_STATE otherwise. Permission: PromotionFinalize_UPDATE.

8.9 POST /api/promotions/cycles/:publicId/supplementary

Purpose

Attaches a supplementary exam to a finalized cycle and re-evaluates every eligible current decision against it — used after a pupil sits a make-up exam.

Auth and Permissions

• Permission: PromotionCorrections_UPDATE (withheld from automatic admin grant).

Request

{ "examPublicId": "f9..." }

Response

{
  "success": true, "message": "Supplementary results applied.",
  "data": { "upgraded": 3, "conditionsSatisfied": 2, "skippedManual": ["stu_..."], "unchanged": 40 }
}

Error Cases

404 PROMOTION_CYCLE_NOT_FOUND, 409 PROMOTION_CYCLE_NOT_FINALIZED, 400 PROMOTION_EXAM_INVALID (exam missing, cancelled, or session ordering invalid — must be in the cycle's own session or a session that starts after it).

Side Effects

Writes promotion_cycle_exams (if not already linked) and new promotion_decisions versions; sends promotion.decision_updated per changed pupil, inline, subject to notifyOnPublish.

8.10 GET /api/promotions/cycles/:publicId/decisions

List current decisions. Filters: outcome, recommendedOutcome, source, gradePublicId, classPublicId, reason (a recommendation-reason code), overridden (boolean), search (name/student-id). pagination=false is refused with 400 PAGINATION_LIMIT_INVALID — a decisions roster is never returned unpaginated.

8.11 GET /api/promotions/cycles/:publicId/students/:studentPublicId/history

Every version (current and superseded) for one pupil in one cycle, newest first.

8.12 PUT /api/promotions/cycles/:publicId/students/:studentPublicId/decision

Purpose

Manually overrides one pupil's draft-phase decision — used for exam-board edge cases the algorithm cannot resolve, or a deliberate policy override.

Auth and Permissions

• Permission: Promotions_UPDATE. Draft only.

Request

{
  "outcome": "promoted",
  "targetGradePublicId": "g9...",
  "reason": "Board override — exceptional circumstances",
  "expectedDecisionPublicId": "pd_..."
}

Response

200 with the full PromotionDecisionDto.

Error Cases

404 PROMOTION_CYCLE_NOT_FOUND, 409 PROMOTION_CYCLE_NOT_DRAFT, 409 PROMOTION_DECISION_STALE, 400 PROMOTION_TARGET_GRADE_INVALID, 400 PROMOTION_CONDITION_REQUIRED, 400 PROMOTION_REASON_REQUIRED.

Side Effects

Never notifies — draft-phase writes are silent.

8.13 POST /api/promotions/cycles/:publicId/decisions/bulk

Same field set as 8.12 plus studentPublicIds (1–500, unique) and a required reason. All pupils get the same outcome/target/condition. The body also carries expectedDecisionPublicIds — the current decision publicId the operator saw for each pupil in studentPublicIds, 1–500 unique uuids, the same length as studentPublicIds. If any selected pupil's current decision publicId is not present in that array — including a length mismatch — the whole request is refused with 409 PROMOTION_DECISION_STALE and nothing is written. Refuses (400 PROMOTION_STUDENT_NOT_IN_CYCLE) if any listed pupil has no current decision — all-or-nothing.

8.14 POST /api/promotions/cycles/:publicId/decisions/reset

Body: { "studentPublicIds": [...], "expectedDecisionPublicIds": [...] }, both 1–500 unique uuids of the same length, expectedDecisionPublicIds carrying the current decision publicId the operator saw for each pupil. A mismatch against any pupil's current decision refuses the whole request with 409 PROMOTION_DECISION_STALE and nothing is written. Otherwise recomputes and overwrites exactly those pupils back to recommendation/supplementary, discarding any manual/bulk override; a pupil who has since left the academic session is reset with the shared LEFT_SESSION_REASON, the same reason ordinary recompute uses. 400 PROMOTION_STUDENT_NOT_IN_CYCLE for a pupil with no current decision.

8.15 POST /api/promotions/cycles/:publicId/students/:studentPublicId/correct

Purpose

Corrects a pupil's decision after the cycle has already been finalized and (possibly) published — used when an error is discovered post-publication.

Auth and Permissions

• Permission: PromotionCorrections_UPDATE. Finalized only.

Request

{
  "outcome": "retained",
  "reason": "Result recheck changed the outcome",
  "expectedDecisionPublicId": "pd_..."
}

expectedDecisionPublicId may be omitted only when the pupil truly has no decision yet — in that case the service requires an active enrollment in the cycle's session to snapshot source class/grade from.

Response

200 with the updated PromotionDecisionDto.

Error Cases

409 PROMOTION_CYCLE_NOT_FINALIZED, 409 PROMOTION_DECISION_STALE, 400 PROMOTION_STUDENT_NOT_IN_CYCLE (no active enrollment for a first-ever write), 400 PROMOTION_TARGET_GRADE_INVALID, 400 PROMOTION_CONDITION_REQUIRED, 400 PROMOTION_REASON_REQUIRED.

Side Effects

Sends promotion.decision_updated inline (subject to notifyOnPublish).

8.16 POST /api/promotions/cycles/:publicId/students/:studentPublicId/condition

Purpose

Resolves a pupil's outstanding condition on a conditionally_promoted decision.

Auth and Permissions

• Permission: PromotionCorrections_UPDATE. Finalized only, current decision must already be conditionally_promoted.

Request

{ "conditionStatus": "satisfied", "reason": "Cleared the outstanding subject on recheck", "expectedDecisionPublicId": "pd_..." }

Response

200 with the updated PromotionDecisionDto. conditionStatus: "failed" rewrites outcome to retained at the pupil's own source grade; "satisfied"/"waived" leaves outcome and target grade untouched.

Error Cases

409 PROMOTION_CYCLE_NOT_FINALIZED, 409 PROMOTION_DECISION_NOT_CONDITIONAL, 409 PROMOTION_DECISION_STALE, 400 PROMOTION_REASON_REQUIRED.

8.17–8.18 GET / PATCH /api/promotions/settings

Singleton settings row. PATCH requires version; an explicit graduatingGradePublicId: null clears the field, an absent field leaves it untouched. 404 PROMOTION_SETTINGS_STALE if the row is somehow missing (should not happen — seeded by migration 0036); 409 PROMOTION_SETTINGS_STALE on a version mismatch.

8.19–8.21 Progression overrides

GET /api/promotions/settings/progressions lists every override. PUT /api/promotions/settings/progressions/:gradePublicId sets exactly one of graduates: true or a nextGradePublicId (never both, never neither — 400 PROMOTION_PROGRESSION_INVALID; also refused if nextGradePublicId equals the grade itself). DELETE removes the override, reverting to the default "next grade by sort order" rule.

8.22 GET /api/promotions/students/:studentPublicId/academic-history

Admin read of the shared academic-history shape (§6.11). Requires Students_READ and passes PeopleAccessService.assertCanAccess — the same object-level check every other student read uses. studentPublicId is validated by ParseUUIDPipe (400 on a malformed id), and because assertCanAccess returns early for a caller with scope: "all" without resolving the row, the controller separately re-reads the pupil and returns 404 for an unknown or soft-deleted studentPublicId — otherwise a superadmin caller would get a 200 with an empty array.

8.23 GET /api/mobile/student/promotion-history

Purpose

Lets a logged-in pupil view their own promotion and academic history.

Auth and Permissions

• Auth: JWT. No permission code.
• Guard chain: JwtAuthGuard, RoleGuard (allowlisted in NO_PERMISSION_ADMIN_HANDLERS).
• Audience: assertPortalAudience(actor, "student").

Response

200 with AcademicHistoryEntryDto[] (§6.11 shape).

Error Cases

403 (wrong audience — before any row is read), 404 STUDENT_NOT_FOUND (no live students row for the caller).

Edge Cases

Empty array for a brand-new pupil with no enrollment, decision, or graduation yet.

8.24 GET /api/mobile/guardian/children/:id/promotion-history

Purpose

Lets a logged-in guardian view one specific child's promotion and academic history.

Auth and Permissions

• Auth: JWT. No permission code.
• Audience: assertPortalAudience(actor, "guardian").
• Ownership: GuardianPortalService.resolveOwnChildId(actor, childId) — the one implementation of "is this pupil this guardian's ward" in the codebase.

Response

200 with AcademicHistoryEntryDto[].

Error Cases

403 (wrong audience), 404 (child id does not resolve to this guardian's own ward — never 403 for someone else's child, to avoid an id-space enumeration oracle).

9. Flow Diagrams

9.1 Route Ownership

9.2 Request Sequence (finalize)

9.3 Error Branch

10. Pagination, Sorting, Filtering, and Search

GET .../history, GET .../academic-history, and both portal reads return unpaginated arrays — they are bounded by a pupil's own version/session count, not by roster size.

11. Caching, Jobs, and External Integrations

13.1 Route-by-Route Completeness Matrix

14. Zero-Omission API Checklist

• Every controller route is documented.
• Every parent route prefix and runtime URL is documented.
• Every DTO field, enum, default, and validator is documented.
• Every response field and nullable field is documented.
• Every auth, guard, permission, and audience branch is documented.
• Every success, validation, permission, not-found, and conflict branch is documented.
• Every database write, queue job, and notification is documented.
• Route/sequence/error diagrams included.
• Tradeoffs (versioned decisions, audience-not-permission portal reads) are documented in the sibling docs.
• Links to backend and features/flows docs included.

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 is documented.
• Every queue job is documented.
• Diagrams match the current code.
• Links to backend and features/flows docs included.

See Also

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