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