Academic Year Rollover - API Reference

Audience: Admin panel engineers, QA, and backend engineers integrating with rollover. Scope: Admin-only APIs owned by the Rollover module — no public, mobile, or webhook surface exists.

1. Documentation Evidence

2. Module Summary

3. Concepts and Terminology

4. API Surface Map

All three correction actions (move, realign, relink) share the single POST .../items/:studentPublicId/correct route; the action field of the request body selects the case. See Backend §6.9 for the write sequence each action follows.

5. Auth, Identity, and Permissions

No endpoint in this module supports guest or unauthenticated access; there is no public or mobile surface.

6. DTO and Model Reference

6.1 CreateRolloverCycleDto — body, POST /rollover/cycles

6.2 ListRolloverCyclesQueryDto — query, GET /rollover/cycles

6.3 RolloverCycleDetailDto — response, GET /rollover/cycles/:publicId

6.4 RolloverOverviewDto — response, GET /rollover/overview

6.5 ListRolloverItemsQueryDto — query, GET /rollover/cycles/:publicId/items

6.6 UpdateRolloverItemDto — body, PATCH /rollover/cycles/:publicId/items/:studentPublicId

6.7 ExcludeRolloverItemsDto / IncludeRolloverItemsDto

6.8 CapacityOverrideDto — body, POST /rollover/cycles/:publicId/items/capacity-override

6.9 SectionAllocationPreviewDto / SectionAllocationResultDto

Result: proposalToken (string, required unchanged on apply), gradePublicId, strategy, perClass[] (per-class assignment counts), assignments[] (per-student proposed class), unassignedCount (int), applied (boolean, present once applied). Each perClass[] entry carries genderAfter: { male, female, other } only when rollover_settings.balanceGender was on for this allocation AND the caller holds Students_READ — it is omitted entirely otherwise, never returned as null.

6.10 RollAllocationPreviewDto / RollAllocationResultDto

Result: proposalToken, gradePublicId, strategy, scope, assignments[], warnings[], applied.

6.11 AllocationApplyDto — body, both apply endpoints

6.12 RolloverProcessRequestDto — body, POST /rollover/cycles/:publicId/process

6.13 RolloverProcessResultDto — response, same endpoint

6.14 RolloverProgressDto — response, GET /rollover/cycles/:publicId/progress

6.15 RolloverSettingsDto / UpdateRolloverSettingsDto

UpdateRolloverSettingsDto makes every field above optional except version, which is always required on a write.

6.16 RolloverCorrectionDto / RolloverCorrectionResultDto — POST /rollover/cycles/:publicId/items/:studentPublicId/correct

RolloverCorrectionResultDto response: { item: RolloverItemDto | null } — the item's post-correction state, re-read after the transaction commits. A move performed with allowOverCapacity: true records overCapacity: true|false in the placement_corrected event's toValue, reflecting whether the destination class actually ended up over capacity after the enrollment; the field is absent from an ordinary move's event. Un-graduating a pupil through realign (cases d/e) always restores their pupil-scope role grants, and restores sign-in as well only when the actor performing the realign holds Users_UPDATE.

7. Enum Reference

Exception, warning, outcome, run-failure, integrity, preflight, and allocation-unassigned codes are enumerated in full in Backend §13 — they are not HTTP-facing enums but do appear verbatim in response payloads (exceptionCodes[], outcomeCode, failureCode, integrity report entries, preflight code lists).

8. Endpoint Reference

8.1 GET /rollover/overview

Purpose: The rollover dashboard's landing data — which session is current, what the suggested next target is, whether a cycle is already active, and headline counts of pupils and decisions. Call this first when opening the rollover screen.

Auth: Rollover_READ.

Response: RolloverOverviewDto — see §6.4.

Errors: none domain-specific — a caller lacking permission gets 403.

8.2 GET /rollover/cycles

Purpose: List past and present rollover cycles, optionally filtered by status, for the cycle-history screen.

Auth: Rollover_READ.

Query: status (optional).

Response: paginated array of RolloverCycleSummaryDto.

8.3 POST /rollover/cycles

Purpose: Start a new rollover cycle for a source/target session pair once the source's promotion cycle is finalized. This is the entry point to the whole module.

Auth: Rollover_CREATE.

Body: CreateRolloverCycleDto — see §6.1.

{
  "sourceSessionPublicId": "b1a2...",
  "targetSessionPublicId": "c3d4...",
  "promotionCyclePublicId": "e5f6..."
}

Side Effects: inserts a rollover_cycles row and syncs the roster into rollover_items in the same operation.

Error Cases

8.4 GET /rollover/cycles/:publicId

Purpose: The full cycle detail view, including the 15-check readiness checklist, for the cycle's own screen.

Auth: Rollover_READ. Response: RolloverCycleDetailDto — see §6.3.

Error Cases: 404 ROLLOVER_CYCLE_NOT_FOUND.

8.5 DELETE /rollover/cycles/:publicId

Purpose: Cancel a cycle before any placement or graduation has been made — for abandoning a rollover started against the wrong session pair or promotion cycle.

Auth: Rollover_DELETE.

Side Effects: status = cancelled, cancelled_at/cancelled_by_user_id/cancel_reason set, cycle_cancelled event inserted.

Error Cases: 409 ROLLOVER_CANCEL_NOT_ALLOWED if any item is already placed/graduated.

8.6 POST /rollover/cycles/:publicId/sync

Purpose: Re-pull the roster from the promotion cycle and the source session's live enrollments — call this whenever a promotion decision changes or a pupil's source enrollment changes after the cycle was created.

Auth: Rollover_UPDATE. Response: {inserted: number, updated: number}.

Side Effects: see Backend §6.3 for the exact insert/update rules, including auto-exclusion and manual-exclusion preservation.

8.7 POST /rollover/cycles/:publicId/review

Purpose: Snapshot the current settings and compute the confirmation fingerprint that POST /rollover/cycles/:publicId/process will later require, unchanged. Call this immediately before processing, after the admin is satisfied with the roster and allocations.

Auth: Rollover_UPDATE. Response (RolloverReviewResultDto): fingerprint, countsByStatus (array), countsByOutcome (array), excludedCount, exceptionCount, warningCount, toProcess, sections — a plain RolloverSectionGradeDemandDto[] of per-grade class capacity/demand (not wrapped in a {grades} object), rollConflicts, readiness (array), and summary: {sourceSessionName, targetSessionName}.

8.8 GET /rollover/cycles/:publicId/items

Purpose: List items for the cycle's roster screen, with the view/outcome/status/exceptionCode/class/grade filters.

Auth: Rollover_READ. Query: ListRolloverItemsQueryDto — see §6.5.

Edge Cases: an unrecognized view value is rejected by DTO validation (400); an empty result set for a valid filter returns an empty paginated array, not an error.

8.9 GET /rollover/cycles/:publicId/exceptions

Purpose: A grouped summary of every exception and warning code currently present in the cycle, with sample pupils per group — the screen an admin uses to triage before processing.

Auth: Rollover_READ. Response: {groups: [{code, severity: "error"|"warning", count, samples: RolloverItemSummaryDto[]}], total}. count is an exact per-code count computed in SQL over the scoped item set (included, non-terminal); samples is capped at 50 rows per code and never drives count or total. total is the count of scoped items carrying at least one exception or warning code.

8.10 PATCH /rollover/cycles/:publicId/items/:studentPublicId

Purpose: Edit a single pupil's target class and/or planned roll number by hand, for the exception-resolution workflow.

Auth: Rollover_UPDATE. Body: UpdateRolloverItemDto — see §6.6.

Error Cases: 404 ROLLOVER_ITEM_NOT_FOUND; 400 ROLLOVER_CLASS_INVALID if the class doesn't belong to the target grade/session; 400 ROLLOVER_ROLL_INVALID if the roll is out of range or already taken in scope; 409 ROLLOVER_ROLL_POLICY_AUTOMATIC if manual roll entry conflicts with settings.

8.11 POST /rollover/cycles/:publicId/items/assign-class

Purpose: Bulk-assign the same target class to a batch of pupils, for when an admin wants to hand-place a group without running the full allocation algorithm.

Auth: Rollover_UPDATE. Body: {studentPublicIds: uuid[], targetClassPublicId: uuid}.

8.12 POST /rollover/cycles/:publicId/items/exclude

Purpose: Manually exclude a batch of pupils from this rollover run — for pupils who are leaving the school, on long leave, or otherwise should not be placed even though their decision says otherwise.

Auth: Rollover_UPDATE. Body: ExcludeRolloverItemsDto — see §6.7. Requires reason.

Side Effects: inclusion = excluded, exclusionSource = manual; a later POST /rollover/cycles/:publicId/sync never reverts this.

8.13 POST /rollover/cycles/:publicId/items/include

Purpose: Reverse a manual exclusion.

Auth: Rollover_UPDATE. Body: IncludeRolloverItemsDto.

8.14 POST /rollover/cycles/:publicId/items/capacity-override

Purpose: Allow a specific pupil to be placed into a section that is already at capacity — for the rare case where a physical class genuinely needs to exceed its configured capacity.

Auth: RolloverOverrides_UPDATE (superadmin-only by default). Body: CapacityOverrideDto — see §6.8. reason required when enabling.

Error Cases: 403 ROLLOVER_OVERRIDE_NOT_ALLOWED when capacityPolicy = block and the caller lacks the permission.

8.15 GET /rollover/cycles/:publicId/sections

Purpose: Per-grade target class capacity/demand snapshot — the input an admin reviews before running a section-allocation preview.

Auth: Rollover_READ. Response: array of {classPublicId, capacity, occupied, planned, remaining} — see Backend §6.13.

8.16 POST /rollover/cycles/:publicId/section-allocation/preview

Purpose: Compute (without writing) how a chosen strategy would distribute one grade's pupils across its target classes.

Auth: Rollover_UPDATE. Body: SectionAllocationPreviewDto — see §6.9.

{
  "targetGradePublicId": "a1b2...",
  "strategy": "balanced",
  "onlyUnassigned": true,
  "preserveShift": true
}

Response: SectionAllocationResultDto with a proposalToken that must be replayed to apply.

Edge Cases: a grade with zero eligible classes returns every pupil unassigned with reason NO_CLASS; see the worked examples in Backend §6.4.

8.17 POST /rollover/cycles/:publicId/section-allocation/apply

Purpose: Commit a previously previewed section-allocation proposal.

Auth: Rollover_UPDATE. Body: AllocationApplyDto (proposalToken).

Error Cases: 409 ROLLOVER_PROPOSAL_STALE if the cycle's state changed since the matching preview.

8.18 POST /rollover/cycles/:publicId/roll-allocation/preview

Purpose: Compute (without writing) roll number assignments for one grade under a chosen strategy and scope.

Auth: Rollover_UPDATE. Body: RollAllocationPreviewDto — see §6.10.

8.19 POST /rollover/cycles/:publicId/roll-allocation/apply

Purpose: Commit a previously previewed roll-allocation proposal.

Auth: Rollover_UPDATE. Body: AllocationApplyDto.

Error Cases: 409 ROLLOVER_PROPOSAL_STALE.

8.20 POST /rollover/cycles/:publicId/process

Purpose: Start (or resume) background placement processing for every included, non-terminal item in the cycle. This is the point of no easy return — it is superadmin-only and requires an explicit, freshly-computed fingerprint.

Auth: RolloverProcessing_CREATE (superadmin-only by default). Body: RolloverProcessRequestDto — see §6.12.

{
  "fingerprint": "b6e1c9...",
  "confirm": true
}

Response: 201, RolloverProcessResultDto — see §6.13.

Side Effects: writes an outbox row that enqueues AcademicYearJob.PROCESS_ROLLOVER; no direct write to enrollments happens synchronously in this request.

Error Cases

8.21 GET /rollover/cycles/:publicId/progress

Purpose: Poll the state of an in-progress or just-finished processing run, for a progress bar on the admin screen.

Auth: Rollover_READ. Response: RolloverProgressDto — see §6.14.

8.22 GET /rollover/cycles/:publicId/activation-preflight

Purpose: Check whether the target year can be activated right now, and why not if it can't.

Auth: Rollover_READ. Response: {blocking: string[], warnings: string[]} drawn from the preflight code lists in Backend §13.

8.23 POST /rollover/cycles/:publicId/activate

Purpose: Make the target session current and queue placement notifications. The single most consequential action in the module — it moves the entire school forward a year.

Auth: RolloverActivation_UPDATE (superadmin-only by default).

Side Effects: academic_sessions.is_current flips (source → target) via switchCurrent(..., { via: "rollover" }); cycle status = activated; NOTIFY_PLACEMENTS enqueued if notifyPlacement is on and unnotified placements exist.

Error Cases: 409 ROLLOVER_ACTIVATION_BLOCKED if any preflight blocking code is present; 409 ROLLOVER_WARNINGS_UNACKNOWLEDGED if allowActivationWithExceptions = false and warnings remain.

8.24 POST /rollover/cycles/:publicId/finalize

Purpose: Close out an activated cycle, optionally locking the source session at the same time.

Auth: RolloverActivation_UPDATE (superadmin-only by default). Body: {lockSource?: boolean, lockReason?: string}.

Side Effects: status = finalized; if lockSource is true, the source session's locked_at/locked_by_user_id/lock_reason are set.

8.25 POST /rollover/sessions/:sessionPublicId/lock

Purpose: Lock a session independent of finalize — for locking a historical year at any later point.

Auth: AcademicYearLock_UPDATE (superadmin-only by default). Body: {reason: string} (3–1000 chars).

Error Cases: 409 if the session is currently is_current (a current session can never be locked, by database constraint).

8.26 POST /rollover/sessions/:sessionPublicId/unlock

Purpose: Reverse a lock.

Auth: AcademicYearLock_UPDATE (superadmin-only by default).

8.27 POST /rollover/cycles/:publicId/notify-placements

Purpose: Retry placement notifications for a cycle whose placementNotificationState is stuck at failed, or unsent at none on an already-activated/finalized cycle whose settings have notifyPlacement on.

Auth: RolloverActivation_UPDATE (superadmin-only by default).

Side Effects: sets rollover_cycles.placement_notification_state = 'queued', increments notification_attempt, and enqueues an outbox event (aggregateType: "rollover_cycle", eventType: "rollover.notify_placements_requested") on QueueName.ACADEMIC_YEAR with jobName: AcademicYearJob.NOTIFY_PLACEMENTS and dedupe key rollover-notify-${cyclePublicId}-${attempt} — the attempt number is part of the key, so each retry gets its own dedupe slot rather than colliding with the one it is retrying. A placement_notifications_queued row is written to rollover_events. The worker (shared/placement-notification.service.ts) then sends the rollover.placement_changed notification to guardians of every placed, un-notified item.

Error Cases: 409 ROLLOVER_NOTIFICATION_INVALID_STATE if the cycle's notification state is neither failed nor an eligible unsent none.

8.28 POST /rollover/cycles/:publicId/items/:studentPublicId/correct

Purpose: Repair a placement or graduation after processing has already run — the only way to change a placed/graduated item's outcome, since those statuses are otherwise terminal. One route handles all three corrective actions via the action field of RolloverCorrectionDto: "move" (relocate an active placed item to a different class/grade), "realign" (bring an item's status back in line with its current decision — see Backend §6.9 for the full case table), and "relink" (repoint a placed item's stale enrollment link at the pupil's current active enrollment, without changing status).

Body: RolloverCorrectionDto — { action: "move" | "realign" | "relink", targetClassPublicId?: string (UUID), reason: string (3–1000 chars) }.

Response: RolloverCorrectionResultDto — { item: RolloverItemDto | null }, message "Placement corrected.".

Auth: RolloverCorrections_UPDATE (superadmin-only by default).

Side Effects: each action follows the exact write sequence documented per-case in Backend §6.9 — always inside one transaction, always through ClassEnrollmentsService.enroll for any new placement, never a raw insert. A rollover.placement_changed notification is queued for the item's guardians when the correction leaves the item with an enrollment and the cycle is not still preparing/processed.

Error Cases: 409 ROLLOVER_INVALID_STATE if the cycle isn't processed/activated/finalized or has a run in progress; 404 ROLLOVER_ITEM_NOT_FOUND if the pupil has no item in this cycle; 409 ROLLOVER_CORRECTION_INVALID if the item's current state doesn't support the requested action; 409 ROLLOVER_CLASS_INVALID if the target class is missing, inactive, or in the wrong session; 409 ROLLOVER_CORRECTION_GRADE_MISMATCH (move only) if the target class's grade doesn't match the current decision; 409 ROLLOVER_ITEM_LINK_STALE (move only) if the item's current enrollment is no longer active — use relink first; 409 ACADEMIC_SESSION_LOCKED if the target session has since been locked; 404 ACADEMIC_SESSION_NOT_FOUND if the cycle's target session is missing.

8.29 GET /rollover/settings

Purpose: Read the school's rollover strategy and policy defaults.

Auth: RolloverSettings_READ (superadmin-only by default). Response: RolloverSettingsDto — see §6.15.

8.30 PATCH /rollover/settings

Purpose: Update rollover strategy and policy defaults.

Auth: RolloverSettings_UPDATE (superadmin-only by default). Body: UpdateRolloverSettingsDto, version required.

{
  "defaultSectionStrategy": "keep_previous",
  "capacityPolicy": "allow_override",
  "version": 4
}

Error Cases: 409 ROLLOVER_SETTINGS_STALE if version doesn't match the current row. The version is compared inside the UPDATE itself, so of two saves loaded at the same version exactly one succeeds.

8.31 GET /rollover/cycles/:publicId/events

Purpose: The full, newest-first, append-only audit timeline for a cycle.

Auth: Rollover_READ. Response: paginated array of RolloverEventDto (eventType, actorUserId, fromValue, toValue, reason, createdAt), one of the 29 event types listed in Backend §5.2.

8.32 GET /rollover/cycles/:publicId/integrity

Purpose: On-demand cross-check between rollover's own item bookkeeping and the live enrollment/graduation tables — the screen an admin checks if something looks inconsistent.

Auth: Rollover_READ. Response: array of findings, each carrying one of the 8 integrity codes in Backend §13 (DUPLICATE_ACTIVE_PLACEMENT, ITEM_LINK_STALE, DECISION_CHANGED_AFTER_PLACEMENT, ROLL_CONFLICT, SOURCE_SNAPSHOT_DRIFT, GRADUATE_WITH_PLACEMENT, ORPHAN_ITEM, ACTIVE_STUDENT_WITHOUT_ITEM).

8.33 GET /rollover/cycles/:publicId/id-cards

Purpose: Count of placed pupils who already have (or still need) an ID card for the target session — feeds the idCardReminder nudge.

Auth: Rollover_READ. Response: {needed: number, have: number}.

8.34 GET /rollover/cycles/:publicId/new-admissions

Purpose: List pupils who are active in the target session but were never part of this rollover cycle's roster — new admissions the admin should be aware of separately.

Auth: Rollover_READ. Response: paginated array of pupil references.

9. Flow Diagrams

9.1 Route Ownership

9.2 Request Sequence — process

9.3 Error Branch — activation

10. Pagination, Sorting, Filtering, and Search

No rollover endpoint supports pagination=false or cursor pagination; all lists use the shared offset utility with its default 20/max 100 page-size bounds.

11. Caching, Jobs, and External Integrations

See Backend §9 for the full queue/job table.

13. Mandatory Deep API Documentation 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 across cycles/items/allocation/processing/activation/corrections/settings/insights is documented.
• Every DTO field, enum, and default is documented.
• Every auth guard and permission — including which are superadmin-only by default — is documented.
• Every success and error branch documented has a corresponding error code from Backend §13.
• Every database write, queue job, and notification side effect per endpoint is documented.
• Route ownership, request-sequence, and error-branch diagrams are included.
• Tradeoffs and compatibility risks are documented.
• This doc links to backend and features/flows.

15. Integration Checklist

• Every route from the eight controllers is documented.
• Every DTO field is documented.
• Every enum value is documented.
• Every error code relevant to this surface is documented (cross-referenced to Backend §13).
• Every auth guard and permission is documented, including superadmin-only defaults.
• Every queue job and its trigger is documented.
• Diagrams match the current code.
• Links to backend and features/flows are present.

See Also

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