From abb6cf81a8a22499e35264f8021aa3aef10f8442 Mon Sep 17 00:00:00 2001 From: Dotty Dotter Date: Wed, 6 May 2026 15:40:58 +0200 Subject: [PATCH] docs: API-Reference + mkdocs-Nav um Stimmverhalten/Aktuelle-Themen/Admin 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) --- docs/reference/api.md | 65 +++++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 9 ++++++ 2 files changed, 74 insertions(+) diff --git a/docs/reference/api.md b/docs/reference/api.md index bab350f..74d0969 100644 --- a/docs/reference/api.md +++ b/docs/reference/api.md @@ -35,6 +35,55 @@ Automatisch generierte Referenz der FastAPI-Endpoints. | 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 @@ -76,6 +125,22 @@ Liefert ein vollständiges Wahlprogramm-PDF mit gelb markierter Zitat-Stelle. |---|---|---|---| | 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 | diff --git a/mkdocs.yml b/mkdocs.yml index b4501dc..72d8749 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -22,11 +22,20 @@ nav: - "0002 Adapter-Architektur": adr/0002-adapter-architecture.md - "0003 Citation-Property-Tests": adr/0003-citation-property-tests.md - "0004 Deployment-Workflow": adr/0004-deployment-workflow.md + - "0005 Keycloak SSO mit Dev-Bypass": adr/0005-keycloak-sso-with-dev-bypass.md + - "0006 Embedding-Modell-Migration v3→v4": adr/0006-embedding-model-migration-v3-to-v4.md + - "0007 Test-Taxonomie": adr/0007-test-taxonomy.md + - "0008 DDD-Lightweight-Migration": adr/0008-ddd-lightweight-migration.md + - "0009 Protokoll-Parser-Registry": adr/0009-protokoll-parser-registry.md + - "0010 Stimmverhalten×GWÖ-Aggregat": adr/0010-stimmverhalten-gwoe-aggregat.md + - "0011 Aktuelle-Themen + PM-Generator": adr/0011-aktuelle-themen-pm-generator.md - Reference: - API-Endpoints: reference/api.md - Adapter-Capabilities: reference/adapter-capabilities.md - Datenmodelle: reference/models.md - Embeddings & Citations: reference/embeddings.md + - Analysen: + - Plenum-Vote-Parser-Roadmap: protokoll-parser-roadmap.md - How-to: - Keycloak einrichten: how-to/keycloak-setup.md - Archiv: