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:

{
  "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