TapTrack-Hub/.paul/phases/11-monthly-reports/README.md

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