65 lines
2.5 KiB
Markdown
65 lines
2.5 KiB
Markdown
# 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
|