Reports & Analytics - API Reference

Audience: Admin panel engineers, mobile/panel engineers, backend engineers, QA. Scope: Every admin route under /api/reports/... (catalog, live run, builder, dashboards, saved reports, templates, schedules, settings, overview/year-closing, profiles, export jobs) plus the two pupil/guardian portal routes mounted under /api/mobile.

1. Documentation Evidence

2. Module Summary

3. Concepts and Terminology

4. API Surface Map

Every leaf module under ReportsModule declares its own controllers. GET /reports/schedules/recipient-options is declared before GET /reports/schedules/:id in the controller so Nest's route matching never treats the literal "recipient-options" segment as an :id.

5. Auth, Identity, and Permissions

Every permission module this surface enforces, from packages/db/src/authorization/permission-catalog.ts:

6. DTO and Model Reference

6.1 RunReportDto (body of POST /reports/run)

6.2 ReportResultDto (response of POST /reports/run, POST /reports/builder/preview, and the value inside every dashboard/profile/portal section)

ReportKpiDto

ReportChartDto

ReportTableDto

6.3 ReportCatalogItemDto (one entry of GET /reports/catalog)

The catalog lists only reports the caller may run — a report whose domain code or scope the caller lacks is absent from the response entirely, never shown as a locked/greyed entry.

6.4 MetricDefinitionDto (one entry of GET /reports/metrics)

key, name, description, formula, numerator, denominator (nullable), sourceModule, scope, unit, yearBehaviour, excludes — all string. Every one of the finance/complaints/communication metric keys is now referenced by at least one live report (see the feature doc's inventory), unlike the earlier state of this module.

6.5 FilterOptionsDto (response of GET /reports/filter-options)

6.6 CreateReportJobDto (body of POST /reports/jobs)

Header: Idempotency-Key (optional) — 8–128 chars of [A-Za-z0-9_-]; a repeat with the same body within its lifetime returns the same job (created: false); a repeat with a different body 409s.

6.7 ListReportJobsQueryDto (query of GET /reports/jobs)

6.8 ReportJobDto (one job, returned by list/get/create/cancel/retry/delete/run-now)

6.9 ReportJobEventDto (one entry of GET /reports/jobs/:id/events)

6.10 BuilderDatasetDto (one entry of GET /reports/builder/datasets)

6.11 BuilderQueryDto (body of POST /reports/builder/preview)

This DTO enforces shape only; every field/op/aggregate is re-validated against the chosen dataset's frozen field list by resolveBuilderQuery (§6.9 of the backend doc), because which fields exist depends on which dataset was chosen.

6.12 Dashboard DTOs

DashboardWidgetPositionDto: {x: 0-11, y: 0-200, w: 1-12, h: 1-12} (a 12-column grid). DashboardWidgetDto: {id (uuid), title (1-80 chars), reportKey, config: ReportConfigDto, view (one of 9 DASHBOARD_WIDGET_VIEWS), position}. DashboardDto (create body): {name (1-120), description? (≤500), scope ("personal"|"school"), defaultFilters?, widgets (≤24)}. UpdateDashboardDto adds a required expectedVersion and makes every other field optional. DashboardResponseDto adds id, version, editable (false when the caller cannot edit a school-scope dashboard), createdAt, updatedAt. DeleteDashboardQueryDto.expectedVersion is the one optional optimistic-lock field in the whole module. RenderDashboardDto: {filters?} merged over the dashboard's own default_filters. DashboardRenderResultDto: {dashboardId, generatedAt, widgets: DashboardWidgetResultDto[]}, each {widgetId, result, error, alerts?} — error is {errorCode, message} when that one widget failed; the rest of the array still contains results.

6.13 Saved report and template DTOs

SaveReportDto (create): {name (1-120, trimmed), description? (≤500), reportKey (matches REPORT_KEY_PATTERN), config: ReportConfigDto, status? ("draft"|"active", default "active")}. TemplateDto is the same shape without status (templates are always active). UpdateSavedReportDto/UpdateTemplateDto require expectedVersion and make every other field optional. SavedReportVersionDto/ExpectedVersionQueryDto: {expectedVersion} only, used by archive/restore/delete. SavedReportDto (response, shared by both saved reports and templates): {id, kind ("saved"|"template"), name, description, reportKey, config, status ("draft"|"active"|"archived"), version, createdAt, updatedAt, archivedAt, runnable, source?} — runnable: false means the caller no longer holds the codes the reportKey needs; source ("owner"|"system") appears only in the templates list, distinguishing a school-authored template from a built-in system preset. ListSavedQueryDto: {page?, size?, includeTemplates?} — includeTemplates appends the caller's runnable templates, unpaginated, after the saved page. ListTemplatesQueryDto: {includeSystem?} (default true).

6.14 Schedule DTOs

CreateReportScheduleDto: {name (≤120, single line, no control chars), reportKey, config: ReportConfigDto, format (csv|xlsx|pdf), frequency (daily|weekly|monthly|monthly_bs), timeOfDay ("HH:MM" school-local), weekday? (0-6, required iff weekly), dayOfMonth? (-1 or 1-28, required iff monthly/monthly_bs), timezone? (IANA, defaults to school_profile.timezone), recipients: {users?: uuid[≤50], roles?: uuid[≤10]}, activate? (boolean — true creates it already active with next_run_at computed), sourceDefinitionId? (uuid, a saved report owned by the caller)}. UpdateReportScheduleDto is every field of the create DTO made optional (minus sourceDefinitionId, which cannot be changed after creation) plus a required expectedVersion. ListReportSchedulesQueryDto: {status? (comma-separated), page?, size?}. DeleteReportScheduleQueryDto.expectedVersion is required here (unlike the dashboard delete). ScheduleTransitionDto.expectedVersion is optional on activate/pause/archive. RecipientOptionsQueryDto: {reportKey, q?}. RecipientOptionsDto/ScheduleRecipientsOutDto: {users: {id,name}[], roles: {id,name}[]}. ReportScheduleDto (response) adds, beyond the create fields: id, status, nextRunAt/nextRunAtBs, lastRunAt/lastRunAtBs (Bikram Sambat twins of every timestamp, in the schedule's own timezone), lastOutcome, consecutiveFailures, needsAttention, attentionReason, recipients (resolved to names), version, createdAt, updatedAt.

6.15 Settings DTOs

UpdateReportSettingsDto: expectedVersion (required) plus every report_settings field made optional on its own DB-mirrored range (defaultDateRangeDays 1-366, artifactRetentionDays 1-90, jobHistoryRetentionDays 30-3650, maxExportRows 1000-100000, minGroupSize 3-50, ageBucketBounds 1-12 ascending ints 1-30, attendanceThresholdPercent 0-100 with ≤2 decimals — the only field converted to a different unit for storage (basis points), absenceStreakDays 2-60, failedSubjectsThreshold 1-20, overdueFeeThresholdPaisa 0-100000000000, scheduleFailureAlertThreshold 1-20, includeSchoolLogo boolean). ReportSettingsDto (response) mirrors every column, presenting attendanceThresholdPercent (derived) rather than the stored basis points.

6.16 Profile and portal DTOs

ProfileQueryDto: {sessionId? (uuid)} — see §8.13-8.15 for what an out-of-scope or mismatched session does per profile kind. ReportProfileDto: {generatedAt, subject (a small identifying summary specific to the profile kind), sections: ProfileSectionDto[]}, each section {key, title, available, result: ReportResult | null} — available: false sections carry result: null rather than being omitted from the array. PortalReportsDto: {generatedAt, student: {id, fullName, currentPlacement: {grade,section,rollNumber,sessionName} | null}, sections: PortalReportSectionDto[]}, always exactly four sections (placements, attendance, results, assignments, promotions — five keys, four of which are always present alongside placements) with no availability gating, since no permission code applies to the caller's own record.

7. Enum Reference

7.1 ReportCategory (19 values, shared/report-types.ts)

students, demographics, attendance, leave, academics, assignments, exams, promotions, teachers, staff, classes, subjects, calendar, communication, complaints, id_cards, finance, cross_domain, academic_year. teachers, classes and subjects are declared members of the union with no registered report using them directly — staff.* reports use staff/teachers-adjacent vocabulary but are tagged category: "staff".

7.2 REPORT_FORMATS

csv, xlsx, pdf — packaged exports (package.*) accept only xlsx/pdf.

7.3 REPORT_JOB_STATUSES (state machine)

Every transition above is one UPDATE ... WHERE status = '<from>' [AND lease_token = $t] — there is no separate application-level lock, so two concurrent actions (a user cancel racing the worker's finalize; two tabs both clicking retry) always resolve to exactly one winner and the loser sees the 409 for the state it lost to.

7.4 ReportColumnType

text, number, percent, paisa, date, datetime, status (requires enumKey), grade, boolean, hours, days.

7.5 REPORT_SCHEDULE_STATUSES / REPORT_SCHEDULE_FREQUENCIES / REPORT_SCHEDULE_ATTENTION_REASONS

Statuses: draft, active, paused, archived (see the state table in the feature doc). Frequencies: daily, weekly, monthly, monthly_bs. Attention reasons: failures, owner_inactive, owner_permission, invalid_config, schedule_error.

7.6 DASHBOARD_WIDGET_VIEWS (9 values)

kpi, bar, stacked_bar, line, scatter, donut, table, alerts, shortcut. All but shortcut are actually executed at render time; shortcut returns its stored navigation target unresolved.

7.7 The Central Metric Catalogue (GET /reports/metrics)

key, name, formula, unit for every entry — covering attendance, exams, assignments, promotions, fees, finance (payroll/assets), complaints, leave, notices/notifications, ID cards, enrollment, demographics, and cross-domain correlation. Every metric key in the catalogue is referenced by at least one currently-registered report (finance, complaints and communication now ship reports, closing the gap an earlier version of this module had).

Attendance shares (rate, absence, late, excused, staff rate, register coverage) are clamped to 0.01–99.99 when strictly between none and all; none stays 0, all stays 100. Other percentages (pass, promotion, completion, collection, per-100) are not clamped. The formula of each attendance metric states the clamp.

8. Endpoint Reference

8.1 GET /api/reports/catalog

Purpose

Returns every report the caller may run, given their current permissions and scope. The admin panel's report picker calls this to build its list — never a hardcoded list of report keys, since availability is permission-dependent and changes per role.

Source Evidence

Auth and Permissions

• Auth: Bearer JWT
• Guard chain: JwtAuthGuard, RoleGuard
• Permission: Reports_READ
• Rate limit: none beyond global defaults

Request

GET /api/reports/catalog?category=attendance&kind=analytic HTTP/1.1
Authorization: Bearer TOKEN

Response

{
  "success": true,
  "message": "Catalog fetched.",
  "data": [
    {
      "key": "attendance.class_summary",
      "title": "Class attendance",
      "description": "Attendance rate, absence and late rates per class for the selected period.",
      "category": "attendance",
      "kind": "analytic",
      "filters": ["sessionId", "dateFrom", "dateTo", "dateFromBs", "dateToBs", "period", "gradeIds", "sectionIds", "classIds"],
      "requiredFilters": [],
      "columns": [{ "key": "className", "label": "Class", "type": "text", "enumKey": null, "contact": false }],
      "defaultColumns": ["className", "students", "requiredDays", "registersTaken", "registersMissing", "marked", "present", "late", "absent", "excused", "ratePct", "absenceRatePct", "lateRatePct"],
      "sortable": [],
      "groupable": [],
      "metrics": ["attendance.rate", "attendance.absence_rate", "attendance.late_rate"],
      "exportFormats": ["csv", "xlsx", "pdf"],
      "heavy": false,
      "cacheScope": "shared",
      "scopeMode": "teaching",
      "presets": []
    }
  ]
}

Side Effects

None — read-only, no cache write, no audit record.

Error Cases

Edge Cases

• No reports match the filters → data: [], still success: true.
• A caller with only Reports_READ and no domain codes → data: [] (the catalog is never "everything, greyed out").

8.2 GET /api/reports/metrics

Returns the full central metric-definition catalogue. Used for a "what does this number mean" tooltip/glossary next to any KPI. Permission: Reports_READ only — the definitions reveal no data, only vocabulary. No parameters. Response: array of MetricDefinitionDto, unfiltered, identical for every caller. Errors: 401/403 only, as in §8.1.

8.3 GET /api/reports/filter-options

Populates the report filter bar: sessions, grades, sections, classes (scoped to the caller), subjects, departments, designations, exams, leave types, complaint categories, fee categories, rooms. Query: sessionId? (uuid, defaults to the current session). Response: FilterOptionsDto (§6.5). No side effects. Edge cases: no current session and no sessionId → classes: [], exams: [], reference lists still populated; a caller with no teaching assignment → classes: [] (the scope predicate is sql\false``, not an error).

8.4 POST /api/reports/run

Purpose

Runs exactly one report live and returns its full result. This is the single route every report page's "load" and "apply filters" actions call, and the route dashboards, profiles, overview and year-closing internally route through for each of their constituent reports. Results are cached briefly (60–120s) and keyed on the resolved filters/columns/sort/scope, so identical requests within the TTL do not re-query the database.

Source Evidence

Auth and Permissions

• Auth: Bearer JWT
• Guard chain: JwtAuthGuard, RoleGuard, IpThrottlerGuard
• Permission: Reports_READ plus every code in the target report's requires
• Rate limit: ADMIN_REPORT_RUN — 60 requests/minute, keyed per user
• Idempotency: not idempotent by design for refresh: true (each is a fresh compute); otherwise served from cache

Request

Minimal:

{ "reportKey": "attendance.class_summary" }

Full:

{
  "reportKey": "students.directory",
  "filters": { "sessionId": "0198c1e4-...", "gradeIds": ["0198c1e4-..."], "gender": ["female"] },
  "columns": ["studentCode", "fullName", "grade", "section", "phone"],
  "sort": { "key": "fullName", "dir": "asc" },
  "page": 1,
  "size": 25,
  "refresh": false
}

Response

ReportResultDto (§6.2), status 200. Example (analytic report, truncated):

{
  "success": true,
  "message": "Report generated.",
  "data": {
    "reportKey": "attendance.class_summary",
    "title": "Class attendance",
    "category": "attendance",
    "kind": "analytic",
    "generatedAt": "2026-09-24T04:12:00.000Z",
    "cached": false,
    "context": { "sessions": [{ "id": "...", "name": "2082 BS" }], "dateFrom": "2026-08-25", "dateTo": "2026-09-24", "filters": [], "scopeLimited": false, "minGroupSize": 5 },
    "summary": [{ "key": "rate", "label": "Attendance rate", "value": 92.4, "unit": "percent", "metricKey": "attendance.rate", "suppressed": false }],
    "charts": [{ "key": "rateByClass", "title": "Attendance rate by class", "type": "bar", "xKey": "className", "xLabel": "Class", "series": [{ "key": "ratePct", "label": "Attendance rate", "unit": "percent" }], "data": [], "note": null }],
    "table": { "columns": [], "rows": [], "totals": null, "page": null, "suppressedCells": [] },
    "warnings": [],
    "metrics": ["attendance.rate", "attendance.absence_rate", "attendance.late_rate"]
  }
}

Side Effects

• Cache: read/write via ReportCacheService, keyed as in the backend doc §8. No explicit invalidation route exists — TTL expiry (or a report_settings.version bump) is the only eviction.
• Database: one REPEATABLE READ, READ ONLY transaction per uncached run.
• No jobs, no notifications, no realtime events, no audit record.

Error Cases

Edge Cases

• Empty result set → table.rows: [], warnings may include NO_SOURCE_ROWS or SOURCE_NOT_CONFIGURED.
• A small demographic group → cells blanked, suppressedCells populated, GROUPS_SUPPRESSED warning present.
• attendance.daily requested over more than 31 days → 400 REPORT_DATE_RANGE_INVALID (its own live-only span cap).
• leave.balances live without exactly one leaveTypeIds → 400 REPORT_REQUIRED_FILTER_MISSING.
• attendance.class_summary returns seven summary KPIs. The rates are over marked pupil records only, so they stay high while registers go untaken; the last four give the base, with the same meaning as the overview's attendance section. Values are numbers or null; the percent unit is 0–100; no small-group suppression applies to them (suppressed is always false). The rate, absence, late and coverage shares are clamped to 0.01–99.99 when strictly between none and all, so one absence among tens of thousands of marked records never reads 100% and one untaken register among them never reads full coverage; none stays 0 and all stays 100.

Example Requests

curl -X POST "$API_URL/api/reports/run" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reportKey":"attendance.class_summary","filters":{"period":"last_30_days"}}'

8.5 GET /api/reports/overview

Purpose

Returns cross-domain KPIs and alerts for the admin panel's landing dashboard — one section per domain (students, attendance, academics, assignments, promotions, complaints, finance, staff, id_cards, communication), each with its own KPIs and threshold-driven alerts (e.g. classes below the attendance threshold, overdue fees, schedules needing attention).

Source Evidence

overview/reports-overview.controller.ts, overview/reports-overview.service.ts, overview/overview-sections.query.ts, overview/overview-register-tally.query.ts, overview/overview-alerts.service.ts, overview/overview.dto.ts.

Auth and Permissions

Permission: Reports_READ. Each section's KPIs/alerts are independently gated by that domain's own Reports*_READ code — a section the caller cannot see is omitted from sections entirely. Every section that is returned has available: true; it carries empty kpis and alerts only when no academic session resolves.

Request

Query: sessionId? (uuid) — defaults to the current academic session.

Response

OverviewDto: {generatedAt, session: {id,name}, sections: OverviewSectionDto[]}, each {key, available, kpis: ReportKpiDto[], alerts: OverviewAlertDto[]}. An OverviewAlertDto is {code, label, count, reportKey, filters} — clicking one navigates to reportKey pre-filtered with filters.

The attendance section's KPIs cover the 30 days ending today (school-local date) — today and the 29 days before it — restricted to required calendar days and, for a caller who is not school-wide, to the classes they teach. Every value is a number or null; the percent unit is 0–100.

The rate, the absence, late and excused shares and the register coverage are clamped to 0.01–99.99 whenever the share is strictly between none and all, so one absence among many marked records never reads 100%, one present record never reads 0%, and one untaken register never reads full coverage; none stays 0 and all stays 100.

The rate is a quality of what was marked and the coverage says how much was marked, so a client shows them together: ratePct 100 with coverageRatePct 20 means the registers that were taken were all clean and most were never taken. expectedCount − markedCount is the untaken remainder of the window; the ATTENDANCE_UNMARKED_REGISTERS alert ("Registers not taken in the last 7 days") counts the same quantity over the trailing 7 days (today and the 6 days before it), so its count never exceeds that remainder. The BELOW_THRESHOLD alert reads the same 30-day window as the rates.

Side Effects

None — read-only; an explicit ReportAuditService VIEW record is written (this GET is not covered by the global mutating-request interceptor).

Error Cases

401/403 AUTH_ACTIVE_ROLE_REQUIRED only.

8.6 GET /api/reports/year-closing

Purpose

Returns the blocking and informational checks (open leave/complaints, unpublished exams, missing ID cards, etc.) plus summary KPI sections an administrator reviews before closing an academic year.

Source Evidence

overview/reports-overview.controller.ts, overview/reports-year-closing.service.ts, overview/year-closing-checks.query.ts, overview/year-closing-gating.util.ts.

Auth and Permissions

Permission: Reports_READ and ReportsSchoolWide_READ — enforced in the service via ReportCompositeAuthorizer, 403 REPORT_SCOPE_FORBIDDEN without the latter (year-closing figures are never meaningful per-class).

Request

Query: sessionId? (uuid).

Response

YearClosingDto: {generatedAt, session, checks: YearClosingCheckDto[], summary: YearClosingSummarySectionDto[]}. Each check is {code, label, count, unit: "count"|"paisa", reportKey, filters, severity: "blocking"|"info"} — unit tells the client how to render count: as a plain number, or as a paisa amount needing the same money formatting as any other paisa-typed value. Every check is unit: "count" except FEES_OUTSTANDING (label "Outstanding fee balance", reportKey: "finance.fee_balances", severity: "info"), which is unit: "paisa" and carries the sum of outstanding balances in paisa, not a count of pupils. A check or summary section the caller lacks the underlying domain permission for is omitted from the response entirely — never shown as a locked row.

Error Cases

8.7 GET /api/reports/profiles/students/:studentId, /classes/:classId, /teachers/:staffId

Purpose

Three composite, read-only analytic profile screens — everything about one student, one class, or one teacher, assembled from several underlying reports/queries into named sections.

Source Evidence

profiles/reports-profiles.controller.ts, profiles/student-profile.service.ts, profiles/class-profile.service.ts, profiles/teacher-profile.service.ts, profiles/dto/profile-query.dto.ts, profiles/dto/profile-result.dto.ts.

Auth and Permissions

Permission: Reports_READ only at the route level — the finer-grained per-section domain-code and scope checks, and the 404-on-out-of-scope-or-missing-target rule, live in ReportCompositeAuthorizer.authorizeProfile, run inside each service.

Request

Path: studentId/classId/staffId (UUID, ParseUUIDPipe). Query: ProfileQueryDto {sessionId?}.

?sessionId= behaves differently per profile kind:

• Student: must be a session visible to the caller; an unknown or out-of-scope id is 404 REPORT_PROFILE_NOT_FOUND.
• Class: a class belongs to exactly one session, so sessionId cannot select a different one — a mismatch is 400 REPORT_FILTER_INVALID, not a 404.
• Teacher: any session is acceptable.

Absent → the caller's current session.

Response

ReportProfileDto: {generatedAt, subject, sections: ProfileSectionDto[]}, each {key, title, available, result: ReportResult | null}.

A subject teacher (holding the domain read code but not the class-teacher relationship) sees only published exam results, and overall (cross-subject) results only for classes where they are the class teacher. The class profile's "class sections grid" is scoped to the caller's own visible classes (school-wide callers see every sibling class; a teaching-scoped caller sees only their own), with small groups suppressed the same as any other breakdown, and every classId on the grid is the class's public UUID.

Side Effects

None mutating; an explicit ReportAuditService VIEW record is written per profile read.

Error Cases

8.8 GET /api/reports/builder/datasets

Lists the datasets and fields the caller may compose a custom report from. Permission: ReportBuilder_READ. A dataset whose domain codes (or school-wide scope, for a school_only dataset) the caller lacks is omitted; a contact-flagged field is omitted unless the caller holds ReportsContacts_READ. Response: BuilderDatasetDto[] (§6.10). No side effects.

8.9 POST /api/reports/builder/preview

Purpose

Runs a user-composed query against one dataset live, read-only, authorised and cached exactly like any other report (the run is registered under the single key builder.custom).

Source Evidence

builder/report-builder.controller.ts, builder/report-builder.service.ts, builder/builder-compiler.ts (resolveBuilderQuery), builder/builder-query-runner.ts, builder/dto/builder-query.dto.ts.

Auth and Permissions

• Guard chain: JwtAuthGuard, RoleGuard, IpThrottlerGuard
• Permission: ReportBuilder_READ, plus every domain code the chosen dataset requires (resolved by resolveBuilderQuery and checked exactly like ReportDefinition.requires)
• Rate limit: ADMIN_REPORT_RUN (shared with the live-run route)

Request

BuilderQueryDto (§6.11).

{ "dataset": "students", "columns": ["grade", "gender"], "groupBy": ["grade", "gender"], "aggregates": [{ "fn": "count" }] }

Response

ReportResultDto, identical shape to a catalog report's run response, with reportKey: "builder.custom".

Side Effects

Same as POST /reports/run: cache read/write only, no database writes.

Error Cases

Edge Cases

• A group whose row count falls under report_settings.min_group_size is dropped from the result entirely (not blanked) — the builder has no fixed column set to blank a cell in.
• Sort tiebreak and GROUP BY are always deterministic (group key, then a stable column), so paginated pages never reorder between requests.

8.10 Report Dashboards (/api/reports/dashboards)

Six routes: GET (list mine + every school dashboard), POST (create), GET /:id, PATCH /:id (requires expectedVersion), DELETE /:id (optional expectedVersion), POST /:id/render.

Create/update body: DashboardDto/UpdateDashboardDto (§6.12). Render body: RenderDashboardDto {filters?}, merged over the dashboard's default_filters. Render response: DashboardRenderResultDto — every widget's result or per-widget error, concurrency 2, 18s deadline for the whole batch; one widget failing never blanks the others.

Permissions: ReportDashboards_READ/_CREATE/_UPDATE/_DELETE; creating or editing a scope: "school" dashboard additionally needs ReportDashboardsShared codes — attempting it without them is 403 REPORT_DASHBOARD_SCOPE_FORBIDDEN. Rate limit on render: ADMIN_REPORT_RUN.

Edge case: a view: "shortcut" widget's render entry returns its stored {target: {reportKey, savedId?, templateId?}} unresolved — the client navigates to it rather than rendering inline data.

8.11 Saved Reports (/api/reports/saved) and Templates (/api/reports/templates)

Saved reports — seven routes, all scoped to the caller's own owner_user_id: GET (list, ?includeTemplates=true appends runnable templates unpaginated), POST (create), GET /:id, PATCH /:id (expectedVersion required), POST /:id/archive, POST /:id/restore, DELETE /:id.

Templates — five routes, school-wide (no owner): GET (?includeSystem= default true), POST (ReportTemplates_CREATE), GET /:id, PATCH /:id (ReportTemplates_UPDATE), DELETE /:id (ReportTemplates_DELETE). Reading a template needs only Reports_READ.

Both validate config against the named reportKey's definition (unknown filter/column/sort keys rejected exactly as a live run would reject them) before writing.

Response DTO for both: SavedReportDto (§6.13). Example create:

{ "name": "My weekly attendance", "reportKey": "attendance.class_summary", "config": { "filters": { "period": "last_7_days" } } }

8.12 Report Schedules (/api/reports/schedules)

Ten routes, all owner-scoped: GET (list), GET /recipient-options (declared before :id), POST (create), GET /:id, PATCH /:id (expectedVersion required), POST /:id/activate, POST /:id/pause, POST /:id/archive (each with an optional expectedVersion), POST /:id/run-now (returns a ReportJobDto, 202 Accepted), DELETE /:id (expectedVersion required).

Create/update validate config against the report definition, the cadence fields' interdependencies (weekday iff weekly, dayOfMonth iff monthly/monthly_bs), and every named recipient's eligibility to receive this exact report+config via the same predicate the sweep will use — an ineligible name is refused up front rather than silently skipped later.

GET /recipient-options?reportKey=attendance.class_summary&q=ram returns {users, roles} of eligible people/roles, bounded by a candidate pool and result limit.

8.13 Report Settings (/api/reports/settings)

GET (ReportSettings_READ) and PATCH (ReportSettings_UPDATE, expectedVersion required, body §6.15). The update converts attendanceThresholdPercent to basis points and bumps version in the same UPDATE, which is also the report cache's own version key — a threshold change is visible on the very next report run, no cache flush needed.

8.14 GET /api/reports/jobs

Lists export jobs — the requester's own by default, or every job with scope=all and ReportJobs_READ. "Mine" includes jobs where the caller is a recipient, not only the requester. Query: ListReportJobsQueryDto (§6.7). Response: paginated ReportJobDto[]. Error: 403 REPORT_SCOPE_FORBIDDEN on scope=all without ReportJobs_READ.

8.15 POST /api/reports/jobs

Purpose

Requests a background export — a single report, builder.custom, or a package (package.annual_academic, package.custom) — in CSV, XLSX or PDF.

Source Evidence

jobs/report-jobs.controller.ts, jobs/report-jobs.service.ts (create), jobs/report-job-planner.service.ts, jobs/report-job-writer.service.ts, jobs/dto/report-job.dto.ts.

Auth and Permissions

Permission: ReportExports_CREATE, plus (via the planner) every code the target report(s) require. Idempotency: Idempotency-Key header, scoped per user.

Request

Minimal:

{ "reportKey": "attendance.daily", "config": { "filters": { "dateFrom": "2026-08-01", "dateTo": "2026-08-31" } }, "format": "xlsx" }

Package:

{
  "reportKey": "package.annual_academic",
  "config": { "filters": { "sessionId": "0198c1e4-..." } },
  "format": "pdf",
  "title": "Annual report 2082"
}

Response

202 Accepted, ReportJobDto. message is "Export queued." on a new job or "Export already requested." when the same Idempotency-Key matched an existing one.

Side Effects

• Database: one report_jobs row inserted inside a transaction holding pg_advisory_xact_lock(hashtext('report_jobs:{userId}')), with an outbox_events row.
• Outbox → BullMQ: relayed to QueueName.REPORTS as reports.generate.
• No file exists yet — poll GET /reports/jobs/:id or wait for the report.ready notification.

Error Cases

Edge Cases

• package.annual_academic silently omits parts the caller cannot see and adds a PACKAGE_PARTS_OMITTED warning once the file is generated.
• Sending recipients (schedule-only, not exposed on this manual-create route) excludes principal-scoped parts from being generated at all for a job that will have recipients.

8.16 GET /api/reports/jobs/:id

Polls one export job's current state. Permission: ReportExports_READ. Visibility (canView): requester, a recipient, or ReportJobs_READ/superadmin. 404 REPORT_JOB_NOT_FOUND for both "does not exist" and "not visible" — identical response either way.

8.17 GET /api/reports/jobs/:id/events

Shows the job's full lifecycle history. Response: ReportJobEventDto[] (§6.9), oldest-first, capped at 500 events. Same 404 rule as §8.16.

8.18 POST /api/reports/jobs/:id/cancel

Cancels a job still queued or processing. Permission: ReportExports_UPDATE; manageable = requester or ReportJobs_UPDATE/superadmin. A conditional UPDATE ... WHERE status IN ('queued','processing'); a processing job's worker notices at its next checkpoint (its lease-conditional UPDATE returns zero rows) and cleans up — it does not stop instantly. Errors: 404 REPORT_JOB_NOT_FOUND, 409 REPORT_JOB_NOT_CANCELLABLE.

8.19 POST /api/reports/jobs/:id/retry

Re-queues a failed job with the same configuration. Response: ReportJobDto (status: "queued", retryCount incremented), a fresh outbox delivery event. Error: 409 REPORT_JOB_NOT_RETRYABLE (not failed, or retryCount >= 10).

8.20 DELETE /api/reports/jobs/:id/artifact

Deletes the generated file immediately. Response: ReportJobDto (status: "expired", artifactKey: null). Storage deletion is attempted synchronously; on failure the tracking row is left for the maintenance sweep. Error: 409 REPORT_JOB_NOT_READY.

8.21 GET /api/reports/jobs/:id/download

Purpose

Streams the generated file — the only route in the module whose response is not the standard JSON envelope.

Auth and Permissions

• Permission: ReportExports_READ.
• canDownload() re-checks, at download time: requester-or-recipient, every required_codes still held, contacts code if includesContacts, and ReportsSchoolWide_READ if generatedScope === "school_wide".

Response

Raw file bytes. Headers: Content-Type, Content-Disposition: attachment; filename="..."; filename*=UTF-8''..., Content-Length, Cache-Control: no-store, private, X-Content-Type-Options: nosniff.

Side Effects

download_count incremented, last_downloaded_at set, a downloaded report_job_events row, and an explicit ReportAuditService.record(..., "DOWNLOAD", ...) call (metadata carries reportKey, format, rowCount, scopeKind, includesContacts, asRecipient — never a file name or content).

Error Cases

8.22 GET /api/mobile/student/reports

Purpose

The pupil's own reports screen: placements, attendance, results, assignments, promotions — always their own record, never any permission-gated selection.

Source Evidence

portal/reports-student-portal.controller.ts, portal/reports-portal.service.ts, portal/dto/portal-reports.dto.ts.

Auth and Permissions

No @Permissions(). assertPortalAudience(actor, "student"), then the controller resolves students by userId = actor.id AND deleted_at IS NULL directly (the identity layer, per the repo's portal rules — never PeopleAccessService.scopeFor).

Response

PortalReportsDto (§6.16).

Error Cases

Edge Cases

• Assignment counts include only published or closed assignments, and "already due" counts only assignments whose due date has passed as of now — nothing draft or not-yet-due is counted.
• Attendance's "expected days" figure is bounded at today — no future school day counts as a day the pupil should already have a mark for.

8.23 GET /api/mobile/guardian/children/:studentId/reports

Same shape and rules as §8.22, for a guardian viewing one child. assertPortalAudience(actor, "guardian"), then GuardianPortalService.resolveOwnChildId(actor, studentId) — the identity-layer predicate that is the authorization decision; a mismatch is 404 STUDENT_NOT_FOUND, never 403, so studentId is not an enumeration oracle over the pupil roll.

9. Flow Diagrams

9.1 Route Ownership

9.2 Error Branch (POST /reports/run)

9.3 Optimistic Concurrency (any PATCH/archive/restore/delete on saved/template/dashboard/schedule)

10. Pagination, Sorting, Filtering, and Search

An analytic-kind report's table.page is null — its table is a bounded aggregation, not a paginated roll. Only dataset-kind reports and the builder carry page.

11. Caching, Jobs, and External Integrations

12. Consumer Integration Notes

13. API Change Impact

Zero-Omission API Checklist

• Every controller route documented (49 admin routes across 10 controllers + 2 portal routes = 51, matching apps/api/test/structure/structure.baseline.json).
• Every DTO field, enum and default documented.
• Every error code this surface can throw documented with its condition.
• Every auth guard and permission documented.
• Every cache key and queue documented.
• Optimistic-concurrency behaviour documented per surface (required vs optional expectedVersion).

See Also

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