gwoe-antragspruefer/README.md

# GWÖ-Antragsprüfer

**Automatische Gemeinwohl-Bilanzierung von Parlamentsanträgen nach der GWÖ-Matrix 2.0 für Gemeinden**

![Python](https://img.shields.io/badge/Python-3.12-blue)
![FastAPI](https://img.shields.io/badge/FastAPI-0.109-green)
![Code-License](https://img.shields.io/badge/Code-MIT-yellow)
![Data-License](https://img.shields.io/badge/Daten-CC--BY--4.0-blue)
![Version](https://img.shields.io/badge/Release-1.0.0-success)

Live unter <https://gwoe.toppyr.de/>.

## Was macht das Tool?

Der GWÖ-Antragsprüfer analysiert Anträge aus deutschen Landesparlamenten und dem Bundestag und bewertet sie nach den Kriterien der **Gemeinwohl-Ökonomie (GWÖ)**:

- **GWÖ-Score (0–10)** — Wie gut entspricht der Antrag den GWÖ-Werten?
- **Matrix-Zuordnung** — Welche der 25 Felder der GWÖ-Matrix für Gemeinden werden adressiert?
- **Programm-Treue** — Passt der Antrag zum Wahl- und Grundsatzprogramm jeder Fraktion?
- **Verbesserungsvorschläge** — Konkrete Textänderungen mit GWÖ-Begründung im Redline-Format
- **Zitate mit Verifikation** — Belege aus den Wahl-/Grundsatzprogrammen, server-seitig gegen Original-Chunks geprüft (siehe ADR 0001)

## Aktive Datenquellen (Stand Release 1.0)

**16 Bundesländer + Bundestag** — alle aktiven Adapter:

| BL | Wahlperiode | Quelle |
|---|---|---|
| BUND | 21 (2025–2029) | bundestag.de DIP |
| BW | 17 (2021–2026) | PARLIS |
| BY | 19 (2023–2028) | Bayern Landtag |
| BE | 19 (2023–2026) | Berlin AGH |
| BB | 8 (2024–2029) | StarWeb |
| HB | 21 (2023–2027) | ParlDok |
| HH | 23 (2025–2029) | ParlDok |
| HE | 21 (2024–2029) | Hessen Landtag |
| MV | 8 (2021–2026) | ParlDok |
| NI | — | NILAS (login-protected, deferred) |
| NRW | 18 (2022–2027) | OPAL |
| RP | 18 (2021–2026) | StarWeb |
| LSA | 8 (2021–2026) | StarWeb |
| SL | 17 (2022–2027) | Umbraco |
| SN | 8 (2024–2029) | XML-Export |
| SH | 20 (2022–2027) | Schleswig-Holstein |
| TH | 8 (2024–2029) | StarWeb |

Plus **abgeordnetenwatch.de**-Integration für strukturierte namentliche Abstimmungen (alle 16 BL + BT).

## Features

### Frontend (v2, ECOnGOOD-CD)

- **Listenansicht** mit Score-Band-Filter, BL-Chip-Filter, Sort-Dropdown (8 Optionen), Live-Suche
- **Antragsdetail** mit ScoreHero, Matrix 5×5, Zitaten, Redline-Diff, Programm-Treue pro Fraktion, Versionshistorie, namentlichem Abstimmungsverhalten (wenn vorhanden)
- **Bookmark-Liste** (server-seitig pro User), **Kommentare**, **Voting**, **Share-Buttons** (Threads/X/Mastodon mit LLM-Texten), **Re-Analyze**
- **Auswertungen** mit BL×Partei-Matrix, Themen×Fraktion-Heatmap, Cluster-Bubble-Chart
- **Tag-Cloud**, **Cluster-Liste**, **Landtag-Live-Suche**, **Methodik**, **Quellen**
- **Admin-Panel** Freischaltungen / Queue / Abos / Wahlprogramme
- **Dark-Mode**, **Phosphor-Icons**, Avenir/Nunito-Sans, **Keyboard-Shortcuts** (j/k/Enter/Esc/?/⏎)

### Backend

- **FastAPI** + Jinja2 + Vanilla JS (kein Build-Tool)
- **SQLite** mit aiosqlite (Source of Truth)
- **Qwen-Plus** (DashScope) für die LLM-Bewertung — austauschbar via `LlmBewerter`-Port (ADR 0008)
- **Embeddings v4** für die Zitat-Verifikation (ADR 0006)
- **Keycloak SSO** mit Direct-Access-Grant (Login-Modal in der App, kein Redirect)
- **Background-Queue** mit 3 parallelen Workern + Graceful Shutdown
- **Daily-Digest-Mail** für Abonnent:innen
- **Monitoring-Scan** aller Adapter mit Kosten-Schätzung — Beobachtung ohne Auto-Fetch
- **OG-Cards** (Open-Graph-Bilder pro Antrag, Playwright-gerendert)
- **WeasyPrint** für PDF-Reports

### Tests

- **574 Tests, 13 skipped** — Unit + Integration + Property + Bug-Regression + DDD
- Live-Adapter-Tests gegen alle 17 Quellen (`pytest -m integration`)
- Citation-Substring-Verification gegen Original-PDFs
- E2E-Browser-Tests via Playwright (`pytest -m e2e`)

## Architektur

Detailliert in [`docs/`](docs/):

- [`docs/adr/`](docs/adr/) — Architecture Decision Records (8 ADRs)
- [`docs/analysen/ddd-bewertung.md`](docs/analysen/ddd-bewertung.md) — DDD-Analyse + Migrations-Roadmap
- [`docs/reference/zugriffsrechte.md`](docs/reference/zugriffsrechte.md) — 63 Routes × User-Status-Matrix
- [`docs/reference/api.md`](docs/reference/api.md) — API-Reference

DDD-Lightweight-Migration ist **Tag 1-4 abgeschlossen** (Ports, Adapter, Repositories, Domain-Verhalten — siehe ADR 0008). Callsite-Migration in `main.py` ist Folge-PR.

## Schnellstart

### Voraussetzungen

- Docker + Docker Compose
- Python 3.12 (für lokale Tests)
- DashScope API-Key (Qwen)
- Keycloak (optional, für Login)

### Installation

```bash
git clone https://repo.toppyr.de/tobias/gwoe-antragspruefer
cd gwoe-antragspruefer/webapp
cp .env.example .env       # API-Keys eintragen
docker compose up -d --build
```

App auf <http://localhost:8000>.

### Tests

```bash
python3 -m pytest tests/ -q                  # Unit-Suite (574 Tests, < 2 s)
python3 -m pytest tests/ -m integration      # Live-Adapter-Tests (langsam)
./scripts/smoke-test.sh                       # Gesamt-Funktionsprüfung gegen Live
```

### Deploy (Server)

```bash
./scripts/deploy.sh                           # mit Uptime-Kuma-Wartungsmodus
./scripts/run-digest.sh                       # Daily-Mail-Digest (Cron 07:00)
./scripts/run-monitoring-scan.sh              # Monitoring-Scan (manuell oder Cron)
```

## Lizenz

Zwei getrennte Lizenzen:

- **Quellcode** — [MIT](LICENSE)
- **Bewertungs-Daten und -Berichte** (Assessments, Matrix-Zuordnungen, Verbesserungsvorschläge, Themen-Tags etc.) — [CC BY 4.0](DATA-LICENSE)

Wahlprogramme und Antrags-PDFs der Parlamente unterliegen der jeweiligen Urheber-Lizenz der Quelle und werden hier nur zur Verifikation referenziert.

## Mitwirken

Issues unter <https://repo.toppyr.de/tobias/gwoe-antragspruefer>. Pull Requests willkommen — beachte ADR 0004 (Deployment-Workflow) und die Test-Konventionen in `pytest.ini`.

## Statistiken (Stand Release 1.0)

- 16 BL + Bundestag aktiv
- 85 Wahlprogramme indexiert (Embeddings v4)
- 71 produktive Bewertungen in der Live-DB
- 28 977 abgeordnetenwatch-Votes (BUND)
- 11 789 LOC Python in `app/`