# 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