Rapporter — Dokumentation

Enterprise-scheman sparar en serververifierad evidence-snapshot när schemat skapas. Den schemalagda körningen återanvänder snapshoten, men kontrollerar fortfarande att organisationen har aktiv rapporttjänst, enterprise-rapporttjänst och rätt paket/audience. Ett schema kan bara pausas/aktiveras eller byta frekvens; skapa om schemat när signalen, mallen eller källurvalet ska bytas.

Om ett enterprise-schema hoppas över, auditloggas orsaken, till exempel inactive_subscription, missing_reports_entitlement, missing_enterprise_reports_entitlement, audience_not_entitled, missing_source_dataset, missing_source_version, missing_freshness, freshness_policy_missing, future_evidence eller stale_evidence.

Rapportfunktioner används via portalen och interna Pro-endpoints. /api/pro/reports kräver Firebase-inloggning med Authorization: Bearer <idToken> och organisationens Pro-medlemskap; rapporter använder inte API-nycklar. Den publika delningslänken är den enda rapport-endpointen utan inloggning.

Endpoints:

// Rapportjobb:
POST   /api/pro/reports/jobs                   Skapa rapport (asynkront)
GET    /api/pro/reports/jobs                   Lista rapporter (?limit=1-100, standard 20)
GET    /api/pro/reports/jobs/{jobId}            Hämta status + nedladdningslänk
GET    /api/pro/reports/jobs/{jobId}/evidence-export Hämta enterprise-evidence som CSV
POST   /api/pro/reports/jobs/{jobId}/archive    Arkivera rapportjobb

// Delning:
POST   /api/pro/reports/jobs/{jobId}/share      Skapa delningslänk
DELETE /api/pro/reports/jobs/{jobId}/share      Återkalla delningslänk
GET    /api/pro/reports/share/{jobId}           Publik nedladdning (org + token som query params)

// Schemaläggning:
POST   /api/pro/reports/schedules              Skapa schema
GET    /api/pro/reports/schedules              Lista scheman (max 20)
PATCH  /api/pro/reports/schedules/{id}         Uppdatera (enabled, frequency)
DELETE /api/pro/reports/schedules/{id}         Ta bort schema

Exempel: Skapa rapporter

// Skolprofil med rikssnitt och tidsfönster:
POST /api/pro/reports/jobs
{
  "reportType": "skolprofil",
  "schoolCode": "12345678",
  "comparisonLevel": "national",
  "kpis": ["meritRating9", "eligibleYR9", "certifiedTeachersPercent"],
  "fromYear": 2020,
  "toYear": 2025
}
→ 202 {
    "jobId": "abc",
    "status": "queued",
    "reportType": "skolprofil",
    "pollUrl": "/api/pro/reports/jobs/abc",
    "expectedStates": ["queued", "processing", "done", "failed"],
    "firstValue": { "milestone": "first_report_queued", "artifactReady": false }
  }

// Trendrapport — jämför tre skolor:
POST /api/pro/reports/jobs
{
  "reportType": "trendrapport",
  "schoolCodes": ["12345678", "23456789", "34567890"],
  "kpis": ["meritRating9", "eligibleYR9"],
  "title": "Jämförelse grundskolor Lund",
  "fromYear": 2019
}
→ 202 { "jobId": "def", "status": "queued", "reportType": "trendrapport" }

// Enterprise: nämndrapport från serverlagrad signal:
POST /api/pro/reports/jobs
{
  "reportType": "municipality_board_report",
  "signalId": "signal-demo"
}
→ 202 { "jobId": "ghi", "status": "queued", "reportType": "municipality_board_report" }

// Polla status:
GET /api/pro/reports/jobs/{jobId}
→ { "status": "done", "readyAt": "2026-03-18T09:15:42Z", "result": { "downloadUrl": "https://...", "fileName": "skolkoll-skolprofil-12345678-2026-03-18T09-15-42.pdf", "sizeBytes": 184320, "expiresAt": "2026-03-18T10:15:42Z", "firstValue": { "milestone": "first_report_ready", "artifactReady": true } } }

Exempel: Schemaläggning

// Skapa schema — månadsvis kommunöversikt:
POST /api/pro/reports/schedules
{
  "reportType": "kommunoversikt",
  "municipalityCode": "0180",
  "frequency": "monthly"
}
→ 201 { "id": "abc", "enabled": true, "frequency": "monthly", "spec": {...} }

// Skapa enterprise-schema — veckovis nämndrapport från verifierad signal:
POST /api/pro/reports/schedules
{
  "reportType": "municipality_board_report",
  "signalId": "signal-demo",
  "frequency": "weekly"
}
→ 201 { "id": "ent", "enabled": true, "frequency": "weekly", "spec": { "evidenceVerificationMode": "live", "evidenceHash": "..." } }

// Lista alla scheman:
GET /api/pro/reports/schedules

// Pausa/byta frekvens:
PATCH /api/pro/reports/schedules/{id}
{ "enabled": false }

// Ta bort:
DELETE /api/pro/reports/schedules/{id}
→ { "ok": true }

Exempel: Dela rapport

// Skapa delningslänk (30 dagar):
POST /api/pro/reports/jobs/{jobId}/share
{ "expiryDays": 30 }
→ { "shareUrl": "/api/pro/reports/share/{jobId}?org=X&token=abc...", "expiresAt": "2026-04-17T...", "expiryDays": 30 }

// Återkalla delningslänk:
DELETE /api/pro/reports/jobs/{jobId}/share
→ { "ok": true }

// Publik nedladdning (ingen autentisering):
GET /api/pro/reports/share/{jobId}?org=X&token=abc...
→ 302 redirect till signerad PDF-URL

Tillgängliga KPI-nycklar:

certifiedTeachersPercent och studentsPerTeacher har värden för enheter med grundskola eller gymnasieskola. En förskoleenhet utan grundskola eller gymnasieskola har i stället värden under de två förskolenycklarna. För en sådan förskoleenhet avser totalPupils inskrivna barn, och i en skolprofil ger en begärd lärarnyckel förskolans motsvarande personalmått.

Parametrar:

Detaljer:

Jobbstatus: queued → processing → done | failed. Vid done inkluderas result med downloadUrl, fileName, sizeBytes, storagePath och expiresAt. Nedladdningslänken förnyas vid varje anrop (1 timmes giltighet).

Enterprise evidence: API:et sparar evidenceRefs, evidenceManifest, evidenceHash, evidenceVerifiedAt och evidenceVerificationMode i jobbets eller schemats spec. Schemalagda enterprise-körningar återanvänder redan verifierad evidence med reused_verified.

Enterprise-scheman: PATCH /api/pro/reports/schedules/{id} accepterar bara enabled och frequency. Specen är immutabel efter skapande; radera och skapa ett nytt schema för ny signalId, nya evidenceRefs[], annan mall eller annan audience.

Delning: Token genereras med 32 bytes crypto randomBytes. Publik nedladdning (GET /share/:jobId) kräver org och token som query-parametrar. Utgångna delningslänkar returnerar 410 Gone.

Felkoder:

Begränsningar:

• Max 20 enheter per trendrapport
• Max 10 KPI:er per rapport
• Max 10 scheman per organisation
• Rapportfilen kan hämtas så länge den finns kvar och åtkomsten är giltig; spara en egen kopia vid behov
• Nedladdningslänkar har 1 timmes giltighet och förnyas automatiskt
• Delningslänkar: max 90 dagars utgång, standard 30 dagar
• Benchmark-PDF:er skapas via Benchmark-export, inte via rapporternas API
• Enterprise-rapporter är mallstyrda och källbelagda; ingen AI-genererad slutsatstext ingår i v1
• Enterprise-scheman återanvänder den evidence-snapshot som verifierades när schemat skapades