feat: Package 4 Phase 3 — Finale Fixes + Dokumentation (MkDocs, SDK Flow, StepHeader)

Finale Fixes (5 Bugs): - workflow/page.tsx: Array-Format-Fix fuer loadVersions — Array.isArray statt data.versions - einwilligungen_routes.py: ip_address + user_agent in GET /consents Response ergaenzt - consent/page.tsx: Bearbeiten/Vorschau/Veroeffentlichen + Quick Actions verdrahtet (useRouter + Preview Modal) - cookie-banner/page.tsx: BannerTexts State + Controlled Inputs + DB-Persistenz (banner_texts) - embed-code/route.ts: In-Memory configStorage → DB-fetch aus Backend, embed_code Key korrigiert Dokumentation: - docs-src/services/sdk-modules/rechtliche-texte.md: Neue MkDocs-Seite fuer Paket 4 (Einwilligungen, Rechtliche Vorlagen, Cookie Banner, Document Workflow) - mkdocs.yml: Nav-Eintrag 'Rechtliche Texte (Paket 4)' ergaenzt - dokumentations-module.md: Datenfluss-Diagramm um Paket-4-Module erweitert - flow-data.ts: Paket-4-Steps mit korrekten dbTables/dbMode und aktualisierten Beschreibungen - StepHeader.tsx: cookie-banner + workflow STEP_EXPLANATIONS auf Persistenz und Funktionsumfang aktualisiert Tests: 24/24 bestanden (test_einwilligungen_routes.py) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-03 10:37:41 +01:00
parent 3570dd10ea
commit c0b179510d
10 changed files with 491 additions and 88 deletions
--- a/docs-src/services/sdk-modules/dokumentations-module.md
+++ b/docs-src/services/sdk-modules/dokumentations-module.md
@@ -309,10 +309,16 @@ graph LR
    F --> G[Löschfristen]
    G --> H[VVT]

-    I[Document Generator] --> J[Workflow]
-    K[Academy] --> L[Training Engine]
+    H --> I[Einwilligungen]
+    I --> J[Rechtliche Vorlagen]
+    J --> K[Cookie Banner]
+    K --> L[Document Workflow]
+
+    M[Document Generator] --> L
+    N[Academy] --> O[Training Engine]
 ```

 Die **Source Policy** bildet die Grundlage für alle nachfolgenden Analyse-Schritte.
-Das **VVT** ist der abschließende Schritt der Dokumentationsphase und baut auf TOMs und Löschfristen auf.
+Das **VVT** ist der abschließende Schritt der Dokumentationsphase und Ausgangspunkt von Paket 4.
 Die **Training Engine** operiert parallel im Betrieb-Paket und liefert Evidence für Audits.
+Paket 4 (Rechtliche Texte) ist vollständig dokumentiert unter [Rechtliche Texte (Paket 4)](rechtliche-texte.md).
--- a/docs-src/services/sdk-modules/rechtliche-texte.md
+++ b/docs-src/services/sdk-modules/rechtliche-texte.md
@@ -0,0 +1,281 @@
+# Rechtliche Texte (Paket 4)
+
+Paket 4 deckt alle Module ab, die rechtlich verbindliche Dokumente und Einwilligungen erzeugen,
+verwalten und veroffentlichen: **Einwilligungen**, **Rechtliche Vorlagen (Consent)**, **Cookie Banner**
+und den **Document Workflow**.
+Alle vier Module sind vollstaendig backend-persistent und bieten CRUD-Operationen ueber die REST-API.
+
+---
+
+## Uebersicht
+
+| Modul | SDK-Route | Checkpoint | DB-Persistenz | Status |
+|-------|-----------|-----------|---------------|--------|
+| [Einwilligungen](#einwilligungen) | `/sdk/einwilligungen` | CP-CONS (REQUIRED) | ✅ Migration 008 | 100% |
+| [Rechtliche Vorlagen](#rechtliche-vorlagen-consent) | `/sdk/consent` | CP-DOC (REQUIRED) | ✅ Migration 007 | 100% |
+| [Cookie Banner](#cookie-banner) | `/sdk/cookie-banner` | CP-COOK (REQUIRED) | ✅ Migration 008 | 100% |
+| [Document Workflow](#document-workflow) | `/sdk/workflow` | CP-WRKF (REQUIRED) | ✅ Migration 007 | 100% |
+
+---
+
+## Einwilligungen
+
+**Route:** `/sdk/einwilligungen` | **Backend:** `backend-compliance:8002` | **Rechtsgrundlage:** Art. 6 Abs. 1a, Art. 7 DSGVO
+
+### Funktionen
+
+- **Datenkatalog:** Definition aller einwilligungspflichtigen Datenpunkte mit Zweck, Kategorie und Pflicht-Flag
+- **Unternehmens-Consent-Konfiguration:** globale Einwilligungseinstellungen pro Tenant
+- **Einwilligungsnachweise:** Erfassung erteilter/widerrufener Einwilligungen mit vollstaendigem Audit-Trail
+  - Gespeichert: `user_id`, `data_point_id`, `granted`, `granted_at`, `revoked_at`, `consent_version`, `source`, `ip_address`, `user_agent`
+- **Statistiken:** Uebersicht ueber aktive Einwilligungen nach Datenpunkt und Nutzer
+- **Widerruf:** Einwilligung per PUT widerrufen (setzt `revoked_at`, behalt urspruenglichen Eintrag)
+- **Cookie Banner Config:** Konfiguration und Kategorienverwaltung des Cookie Banners (s.u.)
+
+### API-Endpoints
+
+| Methode | Pfad | Beschreibung |
+|---------|------|--------------|
+| `GET` | `/api/compliance/einwilligungen/catalog` | Datenpunkt-Katalog laden |
+| `PUT` | `/api/compliance/einwilligungen/catalog` | Datenpunkt-Katalog speichern |
+| `GET` | `/api/compliance/einwilligungen/company` | Unternehmens-Consent-Config laden |
+| `PUT` | `/api/compliance/einwilligungen/company` | Unternehmens-Consent-Config speichern |
+| `GET` | `/api/compliance/einwilligungen/consents/stats` | Einwilligungsstatistiken |
+| `GET` | `/api/compliance/einwilligungen/consents` | Einwilligungen (Filter: user_id, data_point_id, granted) |
+| `POST` | `/api/compliance/einwilligungen/consents` | Neue Einwilligung erfassen |
+| `PUT` | `/api/compliance/einwilligungen/consents/{id}/revoke` | Einwilligung widerrufen |
+
+**Frontend-Proxies:**
+
+| Frontend-Route | Ziel |
+|----------------|------|
+| `GET/PUT /api/sdk/v1/einwilligungen/catalog` | `backend:8002/api/compliance/einwilligungen/catalog` |
+| `GET/POST /api/sdk/v1/einwilligungen/consent` | `backend:8002/api/compliance/einwilligungen/consents` |
+| `GET/POST/PUT /api/sdk/v1/einwilligungen/cookie-banner/config` | `backend:8002/api/compliance/einwilligungen/cookies` |
+| `GET /api/sdk/v1/einwilligungen/cookie-banner/embed-code` | generiert Code aus DB-Config (kein In-Memory) |
+
+### DB-Tabellen (Migration 008)
+
+| Tabelle | Modus | Beschreibung |
+|---------|-------|--------------|
+| `compliance_einwilligungen_catalog` | read/write | Datenpunkte und Einwilligungsdefinitionen |
+| `compliance_einwilligungen_company` | read/write | Unternehmens-Consent-Konfiguration |
+| `compliance_einwilligungen_cookies` | read/write | Cookie Banner Konfiguration (JSON) |
+| `compliance_einwilligungen_consents` | read/write | Erteilte und widerrufene Einwilligungen |
+
+### Datenmodell (Einwilligung)
+
+```json
+{
+  "id": "uuid",
+  "tenant_id": "uuid",
+  "user_id": "nutzer@beispiel.de",
+  "data_point_id": "dp_analytics",
+  "granted": true,
+  "granted_at": "2024-01-15T10:30:00Z",
+  "revoked_at": null,
+  "consent_version": "v1.2",
+  "source": "web_banner",
+  "ip_address": "192.168.1.1",
+  "user_agent": "Mozilla/5.0...",
+  "created_at": "2024-01-15T10:30:00Z"
+}
+```
+
+---
+
+## Rechtliche Vorlagen (Consent)
+
+**Route:** `/sdk/consent` | **Backend:** `backend-compliance:8002` | **Rechtsgrundlage:** Art. 13, 14 DSGVO
+
+### Funktionen
+
+- **Dokumentenverwaltung:** CRUD fuer rechtliche Dokumente (Datenschutzerklaerung, AGB, Cookie-Richtlinie, Impressum, AVV)
+- **Vorschau:** HTML-Vorschau der jeweils veroffentlichten Version direkt im Browser
+- **Bearbeiten:** Weiterleitung zum Document Workflow fuer die Bearbeitung
+- **Schnellaktionen:** Direktnavigation zum Dokumentengenerator fuer neue Dokumente
+- **Filter:** nach Dokumenttyp (`privacy-policy`, `terms`, `cookie-policy`, `imprint`, `dpa`) und Status
+- **Statistiken:** Gesamt, Aktiv, Entwuerfe, Sprachen
+
+**Dokumenttypen:**
+
+| Typ | Rechtsgrundlage |
+|-----|-----------------|
+| `privacy_policy` | Art. 13/14 DSGVO |
+| `terms` | BGB, Fernabsatzgesetz |
+| `cookie_policy` | TTDSG § 25, Art. 5 Abs. 3 ePrivacy-RL |
+| `imprint` | DDG § 5 |
+| `dpa` (AVV) | Art. 28 DSGVO |
+
+### API-Endpoints
+
+| Methode | Pfad | Beschreibung |
+|---------|------|--------------|
+| `GET` | `/api/compliance/legal-documents/documents` | Alle Dokumente (Filter: tenant_id) |
+| `POST` | `/api/compliance/legal-documents/documents` | Neues Dokument anlegen |
+| `GET` | `/api/compliance/legal-documents/documents/{id}` | Einzelnes Dokument |
+| `DELETE` | `/api/compliance/legal-documents/documents/{id}` | Dokument loeschen |
+| `GET` | `/api/compliance/legal-documents/documents/{id}/versions` | Versions-Liste (gibt **Array** zurueck, nicht `{versions:[...]}`) |
+
+**Frontend-Proxy:** `/api/admin/consent/[[...path]]` → `backend:8002/api/compliance/legal-documents/*`
+
+### DB-Tabellen (Migration 007)
+
+| Tabelle | Modus | Beschreibung |
+|---------|-------|--------------|
+| `compliance_legal_documents` | read/write | Dokument-Stammdaten |
+| `compliance_legal_document_versions` | read/write | Versionierte Inhalte (HTML) |
+| `compliance_legal_document_approvals` | write | Freigabe-Verlauf |
+
+---
+
+## Cookie Banner
+
+**Route:** `/sdk/cookie-banner` | **Backend:** `backend-compliance:8002` | **Rechtsgrundlage:** TTDSG § 25, Art. 5 Abs. 3 ePrivacy-RL
+
+### Funktionen
+
+- **Banner-Konfiguration:** Position (oben/unten/zentriert), Stil (Balken/Popup/Modal), Farbe, Optionen
+- **Banner-Texte:** Ueberschrift, Beschreibung und Datenschutz-Link — alle Felder sind **Controlled Inputs**
+  und werden beim Speichern in der DB persistiert (`banner_texts`-Schluessel im `config`-JSON)
+- **Kategorieverwaltung:** Notwendig (immer aktiv), Analyse, Marketing, Praeferenzen
+- **Cookie-Details:** Anbieter, Zweck, Laufzeit, First-Party vs. Third-Party
+- **Live-Vorschau:** Banner-Preview aktualisiert sich beim Aendern von Texten und Einstellungen in Echtzeit
+- **Embed-Code Export:** Generiert HTML+CSS+JS-Block aus der gespeicherten DB-Konfiguration
+  (kein In-Memory-Speicher — Neustart des Containers verliert keine Konfiguration)
+- **Privacy by Default:** Nur notwendige Cookies sind vorausgewaehlt
+
+### API-Endpoints
+
+| Methode | Pfad | Beschreibung |
+|---------|------|--------------|
+| `GET` | `/api/compliance/einwilligungen/cookies` | Cookie-Banner-Konfiguration laden |
+| `PUT` | `/api/compliance/einwilligungen/cookies` | Cookie-Banner-Konfiguration speichern |
+
+**Frontend-Proxies:**
+
+| Frontend-Route | Methoden | Beschreibung |
+|----------------|----------|--------------|
+| `/api/sdk/v1/einwilligungen/cookie-banner/config` | GET, POST, PUT | Config laden/speichern/Kategorie togglen |
+| `/api/sdk/v1/einwilligungen/cookie-banner/embed-code` | GET | Embed-Code aus DB-Config generieren |
+
+### DB-Tabellen (Migration 008)
+
+| Tabelle | Modus | Beschreibung |
+|---------|-------|--------------|
+| `compliance_einwilligungen_cookies` | read/write | Gesamte Banner-Konfiguration als JSON (inkl. `banner_texts`) |
+
+### Konfigurationsformat
+
+```json
+{
+  "config": {
+    "position": "bottom",
+    "style": "bar",
+    "primaryColor": "#6366f1",
+    "showDeclineAll": true,
+    "showSettings": true,
+    "blockScripts": true,
+    "banner_texts": {
+      "title": "Wir verwenden Cookies",
+      "description": "Wir nutzen Cookies...",
+      "privacyLink": "/datenschutz"
+    }
+  },
+  "categories": [
+    { "id": "necessary", "name": "Notwendig", "isRequired": true, "defaultEnabled": true }
+  ]
+}
+```
+
+---
+
+## Document Workflow
+
+**Route:** `/sdk/workflow` | **Backend:** `backend-compliance:8002` | **Rechtsgrundlage:** Art. 5 Abs. 2 DSGVO (Rechenschaftspflicht)
+
+### Funktionen
+
+- **Split-View-Editor:** Linkes Panel zeigt die veroffentlichte Version, rechtes Panel zeigt den Entwurf
+- **Status-Workflow:** `draft` → `review` → `approved` → `published` (oder `rejected`)
+- **Versions-Loading:** Ladet alle Versionen eines Dokuments via
+  `GET /documents/{id}/versions` — Endpunkt gibt ein **direktes JSON-Array** zurueck
+- **DOCX-Upload:** Word-Dokumente als Basis fuer neue Versionen importieren
+  (multipart/form-data via `/versions/upload-word`)
+- **Freigabe-Aktionen:**
+  - Entwurf einreichen → Review
+  - Review freigeben → Approved
+  - Freigabe veroeffentlichen → Published
+  - Ablehnen (mit Begruendung) → Rejected → neuer Entwurf erforderlich
+- **Freigabe-Historie:** Vollstaendige Protokollierung aller Freigabe-Schritte mit Zeitstempel und Kommentar
+- **Versionierte Inhalte:** Jede Aenderung erzeugt eine neue Version; Published-Versionen sind unveraenderlich
+
+### API-Endpoints
+
+| Methode | Pfad | Beschreibung |
+|---------|------|--------------|
+| `GET` | `/api/compliance/legal-documents/documents/{id}/versions` | Alle Versionen (**Array-Response**) |
+| `POST` | `/api/compliance/legal-documents/versions` | Neue Version anlegen |
+| `PUT` | `/api/compliance/legal-documents/versions/{id}` | Version-Inhalt aktualisieren |
+| `GET` | `/api/compliance/legal-documents/versions/{id}` | Einzelne Version laden |
+| `POST` | `/api/compliance/legal-documents/versions/upload-word` | DOCX-Datei importieren |
+| `POST` | `/api/compliance/legal-documents/versions/{id}/submit-review` | Zur Pruefung einreichen |
+| `POST` | `/api/compliance/legal-documents/versions/{id}/approve` | Freigeben |
+| `POST` | `/api/compliance/legal-documents/versions/{id}/reject` | Ablehnen |
+| `POST` | `/api/compliance/legal-documents/versions/{id}/publish` | Veroeffentlichen |
+| `GET` | `/api/compliance/legal-documents/versions/{id}/approval-history` | Freigabe-Historie |
+
+**Frontend-Proxy:** `/api/admin/consent/[[...path]]` → `backend:8002/api/compliance/legal-documents/*`
+
+!!! warning "Array-Response bei Versions-Endpoint"
+    `GET /documents/{id}/versions` gibt ein **direktes JSON-Array** `[{...}]` zurueck,
+    **nicht** `{"versions": [...]}`. Frontend muss `Array.isArray(data) ? data : (data.versions || [])` pruefen.
+
+### DB-Tabellen (Migration 007)
+
+| Tabelle | Modus | Beschreibung |
+|---------|-------|--------------|
+| `compliance_legal_documents` | read | Dokument-Metadaten und aktueller Status |
+| `compliance_legal_document_versions` | read/write | Versionierte HTML-Inhalte |
+| `compliance_legal_document_approvals` | write | Freigabe-Verlauf mit Kommentaren |
+
+### Datenmodell (Version)
+
+```json
+{
+  "id": "uuid",
+  "document_id": "uuid",
+  "version_number": 3,
+  "title": "Datenschutzerklärung v3",
+  "summary": "DSGVO Art. 13 aktualisiert",
+  "content": "<h1>Datenschutzerklärung</h1>...",
+  "status": "published",
+  "created_by": "admin",
+  "created_at": "2024-01-20T14:00:00Z",
+  "published_at": "2024-01-21T09:00:00Z"
+}
+```
+
+---
+
+## Datenfluss Paket 4
+
+```mermaid
+graph LR
+    A[VVT] --> B[Einwilligungen]
+    B --> C[Rechtliche Vorlagen]
+    C --> D[Cookie Banner]
+    D --> E[Document Workflow]
+    D --> F[Dokumentengenerator]
+    E --> G[DSR Portal]
+
+    B -.->|Catalog + Consents| DB1[(compliance_einwilligungen_*)]
+    C -.->|Documents| DB2[(compliance_legal_documents)]
+    E -.->|Versions + Approvals| DB2
+    D -.->|Cookie Config| DB1
+```
+
+Die **Einwilligungen** legen fest, welche Datenpunkte einer Einwilligung beduerften.
+Die **Rechtlichen Vorlagen** erstellen die zugehoerigen Dokumente (DSE, AGB, etc.).
+Der **Cookie Banner** konfiguriert das Frontend-Consent-Widget.
+Der **Document Workflow** fuhrt alle Dokumente durch den Freigabeprozess vor der Veroeffentlichung.