01 — Product Overview (Reports Module)

• 1. Purpose
• 2. Business goals
• 3. Scope — implemented today
• 4. Out of scope / not yet implemented
• 5. Platform context
• 6. PRD native-app exclusion (flagged)
• 7. Success metrics
• 8. Glossary (module-specific)

Async report generation and export. Client-facing definition of the Reports module against the NestJS backend. Source of truth: studylyon-blueprint/04-Modules/Reports.md and src/modules/reports/**. Shared platform contract: 00-shared/01.

1. Purpose

Reports lets institution users request heavy operational/academic data extractions (report cards, attendance summaries, fee summaries) that are generated asynchronously — the request returns a jobId immediately and the client polls until the job completes, then downloads or views the result.

Key rule from blueprint (studylyon-blueprint/04-Modules/Reports.md:48): "All generation is async (202 Accepted + job polling)."

2. Business goals

3. Scope — implemented today

• 3 report types (report-job.schema.ts:7-11): report_card, attendance_summary, fee_summary.
• Job lifecycle (report-job.schema.ts:13-18): queued → processing → completed | failed, with error message and completedAt timestamp.
• 2 endpoints (reports.controller.ts:14-24): POST /reports/generate, GET /reports/:jobId (status + JSON result polling).
• BullMQ worker on report-generate queue (report.worker.ts:7), tenant context restored per job.
• Scheduled generation: AttendanceReportJob enqueues daily/weekly attendance reports into the same report-generate queue (scheduler/jobs/attendance-report.job.ts:13-24).

4. Out of scope / not yet implemented

• GET /reports/:jobId/download exists only in the blueprint (04-Modules/Reports.md:26) — no controller route, no PDF/CSV serialization, no storage integration in code. Marked (planned) everywhere in this package.
• PDF / Excel / CSV export (04-Modules/Reports.md:14), streamed downloads (:49), file storage under sl/{tenantId}/reports/{uuid} with TTL cleanup (:50) — (planned).
• ReportGenerated domain event and completion notifications (04-Modules/Reports.md:33,42) — (planned); no report route exists in event-queue-map.ts.
• Coaching report types BATCH_PERFORMANCE, TEST_SERIES_ANALYSIS, DPP_COMPLETION (docs/IMPLEMENTATION_PLAN.md:646) — (planned).
• Templates, scheduling UI, email delivery, custom SQL (docs/IMPLEMENTATION_PLAN.md:233) — (planned).

5. Platform context

• Data sources (read-only): Students, Attendance, Fees/Invoices, Results — wired in reports.module.ts:20-23.
• Queue: QUEUE.REPORT_GENERATE = 'report-generate' (infrastructure/bullmq/queue.constants.ts:10).
• Files module exists (GET /files/:id/download, files.controller.ts:55-64) and is the intended delivery path for generated files once PDF export lands — today report results are JSON stored on the job doc (report-job.schema.ts:36).

6. PRD native-app exclusion (flagged)

00-shared/01 §9: PRODUCT_REQUIREMENTS_DOCUMENT.md:144 keeps native mobile apps out of Phase 1; roadmap Phase 3 plans a read-only companion. Decision made with the product owner: these docs specify a full-featured Flutter client now, to the complete API surface. This package follows that decision; screens assume an authenticated, permission-gated mobile/tablet client.

7. Success metrics

• POST → jobId round trip < 500 ms (excluding queue time).
• Job status poll → visible state within one poll interval (default 2 s).
• P95 time-to-complete: report_card < 5 s, attendance/fee summaries < 2 s on reference dataset (measured per tenant size class).
• 0% cross-tenant reads; report.read enforced on every result read.

8. Glossary (module-specific)