abb6cf81a8
api.md ergaenzt um die ~20 neuen Endpoints (Stimmverhalten-Aggregate, Aktuelle-Themen, PM-Drafts, Admin-Stand, Auth, Score-Histogram, Vote-Orphans). Filter-Parameter-Tabelle dokumentiert. mkdocs.yml-Nav vollstaendig auf alle 11 ADRs erweitert plus Plenum-Vote-Parser-Roadmap unter "Analysen". Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
149 lines
6.6 KiB
Markdown
149 lines
6.6 KiB
Markdown
# API-Endpoints
|
||
|
||
Automatisch generierte Referenz der FastAPI-Endpoints.
|
||
|
||
## Analyse
|
||
|
||
| Methode | Pfad | Auth | Beschreibung |
|
||
|---|---|---|---|
|
||
| POST | `/api/analyze-drucksache` | Keycloak (geplant) | Antrag aus Landtag-Portal analysieren |
|
||
| POST | `/analyze` | Keycloak (geplant) | Freitext-Upload analysieren |
|
||
| GET | `/status/{job_id}` | - | Job-Status abfragen |
|
||
| GET | `/result/{job_id}` | - | Analyse-Ergebnis (HTML) |
|
||
| GET | `/result/{job_id}/pdf` | - | Analyse-Ergebnis (PDF) |
|
||
|
||
## Assessments
|
||
|
||
| Methode | Pfad | Auth | Beschreibung |
|
||
|---|---|---|---|
|
||
| GET | `/api/assessments` | - | Alle Bewertungen (optional `?bundesland=`) |
|
||
| GET | `/api/assessment` | - | Einzelne Bewertung (`?drucksache=`) |
|
||
| GET | `/api/assessment/pdf` | - | PDF-Download einer Bewertung |
|
||
|
||
## Suche
|
||
|
||
| Methode | Pfad | Auth | Beschreibung |
|
||
|---|---|---|---|
|
||
| GET | `/api/search` | - | Interne DB-Suche (`?q=`, max 200 Zeichen) |
|
||
| GET | `/api/search-landtag` | - | Live Landtags-Suche (`?q=&bundesland=`) |
|
||
|
||
## Auswertungen
|
||
|
||
| Methode | Pfad | Auth | Beschreibung |
|
||
|---|---|---|---|
|
||
| GET | `/auswertungen` | - | Dashboard (HTML) |
|
||
| GET | `/api/auswertungen/matrix` | - | Aggregations-Matrix (JSON, `?wahlperiode=`) |
|
||
| GET | `/api/auswertungen/zeitreihe` | - | Score-Verlauf (JSON) |
|
||
| GET | `/api/auswertungen/export.csv` | - | Long-Format-CSV aller Anträge |
|
||
| GET | `/api/auswertungen/score-histogram` | - | Score-Verteilung in 11 Buckets (`?bundesland=&wahlperiode=`) |
|
||
|
||
### Stimmverhalten × GWÖ (siehe ADR 0010)
|
||
|
||
| Methode | Pfad | Auth | Beschreibung |
|
||
|---|---|---|---|
|
||
| GET | `/api/auswertungen/stimm-index` | - | Stimm-Index pro Fraktion (`Ø(GWÖ\|JA) − Ø(GWÖ\|NEIN)`) |
|
||
| GET | `/api/auswertungen/heuchelei` | - | Anteil NEIN trotz `wahlprogramm.score≥7` pro Fraktion |
|
||
| GET | `/api/auswertungen/empfehlungs-konsistenz` | - | NEIN trotz GWÖ-Empfehlung „unterstützen" |
|
||
| GET | `/api/auswertungen/stimm-index-pro-wert` | - | Heatmap Fraktion × {Würde, Solidarität, Nachhaltigkeit, Gerechtigkeit, Demokratie} |
|
||
| GET | `/api/auswertungen/stimm-index-pro-gruppe` | - | Aufschlüsselung nach Berührungsgruppe (A–E) |
|
||
| GET | `/api/auswertungen/stimm-index-cross-bl` | - | Gleiche Fraktion in mehreren Bundesländern |
|
||
| GET | `/api/auswertungen/stimm-index-zeitreihe` | - | Stimm-Index pro Quartal × Fraktion |
|
||
| GET | `/api/auswertungen/stimmverhalten.csv` | - | Long-Format-CSV Stimmverhalten |
|
||
| GET | `/api/auswertungen/vote-orphans` | - | Drucksachen mit Vote ohne Bewertung (`?bundesland=&limit=`) |
|
||
| POST | `/api/auswertungen/vote-orphans/auto-rate` | Admin | Bulk-Bewerten Top-N Vote-Orphans (rate-limited 3/min) |
|
||
|
||
**Filter-Parameter** (für die Stimmverhalten-Endpoints):
|
||
|
||
| Param | Default | Beschreibung |
|
||
|---|---|---|
|
||
| `bundesland` | alle | BL-Filter (z.B. `NRW`, `BB`, …) |
|
||
| `wahlperiode` | alle | WP-Filter (z.B. `NRW-WP18`) |
|
||
| `exclude_antragsteller` | `1` | Antragstellende Fraktion ausschließen (Default an) |
|
||
| `min_n` | `5` | Mindest-Sample-Size für „ausreichend"-Flag |
|
||
|
||
## Aktuelle Themen × PM-Generator (siehe ADR 0011)
|
||
|
||
| Methode | Pfad | Auth | Beschreibung |
|
||
|---|---|---|---|
|
||
| GET | `/aktuelle-themen` | Keycloak | Dashboard (HTML, 5 Tabs) |
|
||
| GET | `/api/aktuelle-themen/top` | - | Top-News mit Antrags-Match (`?days=&top_k=&only_relevant=&date=`) |
|
||
| GET | `/api/aktuelle-themen/cluster` | - | News-Themen-Cluster (`?days=`) |
|
||
| GET | `/api/aktuelle-themen/top-antraege` | - | Hoch-bewertete Anträge mit News-Resonanz (`?min_gwoe_score=&days=`) |
|
||
| GET | `/api/aktuelle-themen/news-fuer-antrag` | - | News passend zu einem Antrag (`?drucksache=`) |
|
||
| GET | `/api/aktuelle-themen/anträge-fuer-news` | - | Anträge passend zu einer News (`?url=`) |
|
||
| GET | `/api/aktuelle-themen/zeitreihe` | - | News-Volumen pro Tag×Source (`?days=30`) |
|
||
| POST | `/api/aktuelle-themen/generate-presse` | Admin | PM-Generator (qwen-max, rate-limited 5/min, `?force=` für neue Version) |
|
||
| GET | `/api/aktuelle-themen/drafts` | - | Liste der PM-Entwürfe (`?limit=`) |
|
||
| GET | `/api/aktuelle-themen/drafts/{id}` | - | Einzelner PM-Entwurf |
|
||
| GET | `/api/aktuelle-themen/drafts-versions` | - | Alle Versionen für `(drucksache, news_url)` |
|
||
|
||
## Admin
|
||
|
||
| Methode | Pfad | Auth | Beschreibung |
|
||
|---|---|---|---|
|
||
| GET | `/v2/admin/stand` | Admin | System-Stand-Dashboard (HTML, Auto-Refresh 30s) |
|
||
| GET | `/api/admin/stand` | Admin | Datenstand-Aggregation (Counts, KPIs, pro-BL-Stats) |
|
||
| POST | `/api/batch-analyze` | Admin | Batch-Analyse (`?bundesland=&limit=`, ALL-BL-Modus) |
|
||
|
||
## Wahlprogramme
|
||
|
||
| Methode | Pfad | Auth | Beschreibung |
|
||
|---|---|---|---|
|
||
| GET | `/quellen` | - | Wahlprogramm-Übersicht (HTML) |
|
||
| GET | `/api/programme` | - | Liste aller Programme (JSON) |
|
||
| GET | `/api/programme/status` | - | Indexierungsstatus |
|
||
| POST | `/api/programme/index` | Keycloak (geplant) | Programm(e) indexieren |
|
||
| GET | `/api/wahlprogramm-cite` | - | PDF-Seite mit Zitat-Highlighting |
|
||
|
||
## Zitat-Highlighting
|
||
|
||
`GET /api/wahlprogramm-cite`
|
||
|
||
Liefert ein vollständiges Wahlprogramm-PDF mit gelb markierter Zitat-Stelle.
|
||
|
||
**Parameter:**
|
||
|
||
| Param | Typ | Beschreibung |
|
||
|---|---|---|
|
||
| `pid` | string | PROGRAMME-Key (z.B. `gruene-grundsatz`) — alternativ `pdf` |
|
||
| `pdf` | string | PDF-Dateiname (z.B. `gruene-grundsatzprogramm.pdf`) — Reverse-Lookup auf `pid` |
|
||
| `seite` | int | Ziel-Seitennummer (1-indexed) |
|
||
| `q` | string | Snippet-Text zum Highlighten (max 200 Zeichen) |
|
||
| `ds` | string | Drucksache-Nr. (optional, für Auto-Re-Analyse bei nicht-verifizierbarem Zitat) |
|
||
| `bl` | string | Bundesland-Code (optional, zusammen mit `ds` für Re-Analyse) |
|
||
|
||
**Verhalten:**
|
||
|
||
- Text gefunden → PDF mit gelber Highlight-Annotation, `X-Found-Page` Header
|
||
- Text NICHT gefunden + `ds`+`bl` vorhanden → Assessment wird automatisch neu analysiert, HTML-Warte-Seite zurück
|
||
- Unbekanntes Programm → 404
|
||
- Ungültige Seite → 400
|
||
|
||
## Bundesländer
|
||
|
||
| Methode | Pfad | Auth | Beschreibung |
|
||
|---|---|---|---|
|
||
| GET | `/api/bundeslaender` | - | Liste aller konfigurierten Bundesländer |
|
||
|
||
## Auth (Keycloak)
|
||
|
||
| Methode | Pfad | Auth | Beschreibung |
|
||
|---|---|---|---|
|
||
| GET | `/api/auth/me` | - | Auth-Status (`{"authenticated": bool, "user": {...}}`) |
|
||
| GET | `/api/auth/login-url` | - | Keycloak-Login-URL (`?redirect=`) |
|
||
| GET | `/api/auth/callback` | - | OIDC-Callback nach Login |
|
||
| POST | `/api/auth/logout` | - | Logout |
|
||
|
||
## Methodik / Transparenz
|
||
|
||
| Methode | Pfad | Auth | Beschreibung |
|
||
|---|---|---|---|
|
||
| GET | `/methodik` | - | Methodik-/Transparenz-Seite (HTML) |
|
||
| GET | `/quellen` | - | Wahlprogramm-Übersicht (HTML) |
|
||
|
||
## System
|
||
|
||
| Methode | Pfad | Auth | Beschreibung |
|
||
|---|---|---|---|
|
||
| GET | `/health` | - | Health-Check |
|