# Phase 11: Monthly Report Generation + Email

**Status:** Not started
**Depends on:** Phase 9 (Email), Phase 12 (On-Prem Data Pull)

## Goal

On the 1st of each month, automatically generate and email a comprehensive report to each
active school summarising their SMS usage, credit consumption, and invoice for the period.
Super admin can manually trigger reports. School portal shows report history.

## Planned Scope

### Backend

**Enhance `reports.send_monthly_reports` Celery task** (currently a stub)
- For each active school:
  1. Fetch SMS stats for prior month (sent, failed, delivery rate, credit burn)
  2. Fetch attendance data from `school_monthly_stats` (populated by Phase 12)
  3. Fetch invoice for the period (if exists)
  4. Render `monthly_report.html` Jinja2 template
  5. Send email to `school.billing_email`
  6. Store report record in `monthly_reports` table

**`monthly_reports` table** (new model)
- `id`, `school_id`, `report_month` (YYYY-MM), `email_sent_at`, `report_data` (JSON),
  `created_at`

**Manual trigger endpoint**
- `POST /api/reports/send/{school_id}` — super admin triggers report for a specific school

**School portal: report history**
- `GET /api/portal/reports` — school admin lists their past reports
- `GET /api/portal/reports/{id}` — view report detail (JSON data rendered as HTML)

**`monthly_report.html`** Jinja2 email template
- School name + period header
- SMS stats: sent, failed, delivery rate, credit burn
- Attendance summary (if available from Phase 12, else "data unavailable")
- Invoice summary for the period
- Credit balance as of report date

### Frontend

**PortalReportsPage.vue** (new portal page)
- List of past monthly reports (month, email sent date, SMS count, status)
- Click to view report detail

**Super admin** — manual report trigger button in SchoolDetailPage

**Router + sidebar** — add /portal/reports route and nav item

## Key Files to Create/Modify

- `backend/app/models/report.py` (new — monthly_reports table)
- `backend/app/tasks/reports.py` — enhance from stub
- `backend/app/routers/reports.py` (new)
- `backend/app/templates/email/monthly_report.html` (new)
- `backend/app/main.py` — include reports router
- `backend/migrations/versions/003_monthly_reports.py` (new)
- `frontend/src/pages/portal/PortalReportsPage.vue` (new)
- `frontend/src/router/index.ts` — add /portal/reports
- `frontend/src/components/sidebar/PortalSidebar.vue` — add Reports nav item
- `frontend/src/lib/api.ts` — portal report functions