67 lines
2.3 KiB
Markdown
67 lines
2.3 KiB
Markdown
# Phase 12: On-Prem Monthly Report Pull
|
|
|
|
**Status:** Not started
|
|
**Depends on:** Phase 11 (Monthly Reports)
|
|
|
|
## Goal
|
|
|
|
Hub pulls attendance summary data from each on-prem TapTrack instance on the 1st of the month
|
|
to populate monthly report data. Fallback: if on-prem is unreachable, report shows
|
|
"attendance data unavailable" for that section.
|
|
|
|
## Planned Scope
|
|
|
|
### On-Prem Side (TapTrack — separate repo, documented here for reference)
|
|
|
|
**New endpoint on TapTrack on-prem:**
|
|
`GET /api/hub/monthly-report?key={license_key}&month={YYYY-MM}`
|
|
|
|
Response:
|
|
```json
|
|
{
|
|
"month": "2026-02",
|
|
"total_students": 450,
|
|
"school_days": 20,
|
|
"present_days_total": 8100,
|
|
"absent_days_total": 900,
|
|
"late_days_total": 200,
|
|
"avg_attendance_rate": 90.0,
|
|
"sms_sent": 342
|
|
}
|
|
```
|
|
|
|
### Hub Side
|
|
|
|
**`school_monthly_stats` table** (new model)
|
|
- `id`, `school_id`, `report_month` (YYYY-MM date), `total_students`, `school_days`,
|
|
`present_days_total`, `absent_days_total`, `late_days_total`, `avg_attendance_rate`,
|
|
`sms_sent`, `pulled_at`, `pull_status` (success/failed/unavailable)
|
|
|
|
**New Celery task: `reports.pull_monthly_stats`**
|
|
- Runs on the 1st at 5:00am (before `send_monthly_reports` at 7:00am)
|
|
- For each active school with a `last_seen_ip` and `hub_base_url`:
|
|
- GET `{school.hub_base_url}/api/hub/monthly-report?key={license_key}&month={YYYY-MM}`
|
|
- On success: upsert `school_monthly_stats` with pull_status=success
|
|
- On failure/timeout: create record with pull_status=unavailable
|
|
- Timeout: 10 seconds per school
|
|
|
|
**School model** — add `hub_base_url: str | None` column (the on-prem instance URL)
|
|
- Set automatically from `last_seen_ip` or configured manually by super admin
|
|
|
|
**Super admin UI** — `hub_base_url` field in SchoolDetailPage edit panel
|
|
|
|
### Frontend
|
|
|
|
No new pages needed — data surfaces through monthly reports (Phase 11).
|
|
|
|
**SchoolDetailPage.vue** — show `hub_base_url` field in school info + edit modal
|
|
|
|
## Key Files to Create/Modify
|
|
|
|
- `backend/app/models/school.py` — add `hub_base_url` column
|
|
- `backend/app/models/report.py` — add `SchoolMonthlyStats` model
|
|
- `backend/app/tasks/reports.py` — add `pull_monthly_stats` task
|
|
- `backend/app/worker.py` — schedule pull task at 5am on 1st
|
|
- `backend/migrations/versions/004_school_monthly_stats.py` (new)
|
|
- `frontend/src/pages/SchoolDetailPage.vue` — hub_base_url field
|