breakpilot-compliance/docs-src/services/sdk-modules/rechtliche-texte.md

# 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% |
| [User-Consents & Audit](#user-consents--audit) | `/sdk/consent` | — | ✅ Migration 028 | 100% |
| [Cookie-Kategorien](#cookie-kategorien) | `/sdk/cookie-banner` | — | ✅ Migration 028 | 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 |
| `GET` | `/api/compliance/einwilligungen/consents/{id}/history` | Aenderungshistorie einer Einwilligung |

### Pagination

`GET /einwilligungen/consents` unterstuetzt Offset-basierte Pagination:

| Parameter | Typ | Default | Max | Beschreibung |
|-----------|-----|---------|-----|--------------|
| `limit` | integer | 50 | 500 | Eintraege pro Seite |
| `offset` | integer | 0 | — | Startposition |

Response: `{ "total": 1234, "offset": 0, "limit": 50, "consents": [...] }`

### History-Tracking (Migration 009)

Alle Aenderungen an Einwilligungen werden automatisch in der Tabelle
`compliance_einwilligungen_consent_history` protokolliert:

| Aktion | Ausgeloest bei |
|--------|---------------|
| `granted` | POST /consents — neue Einwilligung erteilt |
| `revoked` | PUT /consents/{id}/revoke — Einwilligung widerrufen |
| `version_update` | Manuell bei Versions-Upgrade (kuenftig) |
| `renewed` | Manuell bei Erneuerung (kuenftig) |

**DB-Tabelle:** `compliance_einwilligungen_consent_history`

| Feld | Typ | Beschreibung |
|------|-----|--------------|
| `id` | UUID | Primaerschluessel |
| `consent_id` | UUID | Referenz auf die Einwilligung |
| `tenant_id` | VARCHAR(100) | Tenant-ID |
| `action` | VARCHAR(50) | granted \| revoked \| version_update \| renewed |
| `consent_version` | VARCHAR(20) | Version zum Zeitpunkt der Aktion |
| `ip_address` | VARCHAR(45) | IP-Adresse (IPv4/IPv6) |
| `user_agent` | TEXT | Browser-/Client-User-Agent |
| `source` | VARCHAR(100) | Quelle der Aktion |
| `created_at` | TIMESTAMP | Zeitstempel der Aktion |

**Datenmodell (History-Eintrag):**

```json
{
  "id": "uuid",
  "consent_id": "uuid",
  "action": "granted",
  "consent_version": "v1.2",
  "ip_address": "192.168.1.1",
  "user_agent": "Mozilla/5.0...",
  "source": "web_banner",
  "created_at": "2024-01-15T10:30:00Z"
}
```

**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 |
| `compliance_einwilligungen_consent_history` | write | Aenderungshistorie (Migration 009) |

### 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"
}
```

---

## User-Consents & Audit

**Erweiterung der Legal Documents** (Migration 028) | **Rechtsgrundlage:** Art. 7 DSGVO

Diese Endpoints erweitern die bestehende Dokumentenverwaltung um **End-User-Consent-Tracking**:
Benutzer koennen ihre Zustimmung zu rechtlichen Dokumenten erteilen und widerrufen.

### API-Endpoints

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/api/compliance/legal-documents/public` | Aktive Dokumente (fuer Endbenutzer) |
| `GET` | `/api/compliance/legal-documents/public/{type}/latest` | Neueste publizierte Version |
| `POST` | `/api/compliance/legal-documents/consents` | Consent erfassen (user_id, document_version_id) |
| `GET` | `/api/compliance/legal-documents/consents/my` | Eigene Consents (Filter: X-User-ID) |
| `GET` | `/api/compliance/legal-documents/consents/check/{type}` | Consent-Status pruefen |
| `DELETE` | `/api/compliance/legal-documents/consents/{id}` | Consent widerrufen (Art. 7 Abs. 3) |
| `GET` | `/api/compliance/legal-documents/stats/consents` | Consent-Statistiken |
| `GET` | `/api/compliance/legal-documents/audit-log` | Audit-Trail (paginiert) |

### DB-Tabellen (Migration 028)

| Tabelle | Beschreibung |
|---------|--------------|
| `compliance_user_consents` | End-User Consent-Records (user_id, document_version_id, ip, user_agent) |
| `compliance_consent_audit_log` | Audit-Trail (consent_given, consent_withdrawn, etc.) |

### Datenmodell (User-Consent)

```json
{
  "id": "uuid",
  "tenant_id": "uuid",
  "user_id": "nutzer@beispiel.de",
  "document_version_id": "uuid",
  "consented": true,
  "ip_address": "192.168.1.1",
  "user_agent": "Mozilla/5.0...",
  "consented_at": "2026-03-05T10:00:00Z",
  "withdrawn_at": null
}
```

---

## Cookie-Kategorien

**Erweiterung der Legal Documents** (Migration 028) | **Rechtsgrundlage:** TTDSG § 25

Verwaltung zweisprachiger Cookie-Kategorien (de/en) mit Pflicht-Flag und Sortierung.

### API-Endpoints

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/api/compliance/legal-documents/cookie-categories` | Alle Kategorien |
| `POST` | `/api/compliance/legal-documents/cookie-categories` | Kategorie erstellen |
| `PUT` | `/api/compliance/legal-documents/cookie-categories/{id}` | Kategorie aktualisieren |
| `DELETE` | `/api/compliance/legal-documents/cookie-categories/{id}` | Kategorie loeschen |

### DB-Tabelle (Migration 028)

| Tabelle | Beschreibung |
|---------|--------------|
| `compliance_cookie_categories` | Cookie-Kategorien (name_de, name_en, is_required, sort_order) |

### Default-Kategorien

| Key | Deutsch | Englisch | Pflicht |
|-----|---------|----------|---------|
| `necessary` | Notwendig | Necessary | ✅ |
| `functional` | Funktional | Functional | — |
| `analytics` | Analyse | Analytics | — |
| `marketing` | Marketing | Marketing | — |

---

## 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.