breakpilot-compliance/docs-src/services/sdk-modules/dokumentations-module.md

# Dokumentations-Module (Paket 3 + ergänzende Module)

Diese Seite beschreibt die sechs Module, die die Compliance-Dokumentation vervollständigen:
**VVT**, **Training**, **Source Policy**, **Document Generator**, **Audit Checklist** und **Audit Report**.
Alle Module sind vollständig backend-persistent und bieten CRUD-Operationen über die REST-API.

---

## Übersicht

| Modul | SDK-Route | Paket | Checkpoint | Status |
|-------|-----------|-------|-----------|--------|
| [VVT](#vvt) | `/sdk/vvt` | Dokumentation | CP-VVT (REQUIRED / DSB) | 100% |
| [Source Policy](#source-policy) | `/sdk/source-policy` | Vorbereitung | CP-SPOL (REQUIRED) | 100% |
| [Document Generator](#document-generator) | `/sdk/document-generator` | Rechtliche Texte | CP-DOCGEN (RECOMMENDED) | 100% |
| [Audit Checklist](#audit-checklist) | `/sdk/audit-checklist` | Analyse | CP-CHK (RECOMMENDED) | 100% |
| [Audit Report](#audit-report) | `/sdk/audit-report` | Analyse | CP-AREP (REQUIRED) | 100% |
| [Training Engine](#training) | `/sdk/training` | Betrieb | CP-TRAIN (REQUIRED) | 100% |

---

## VVT

**Route:** `/sdk/vvt` | **Backend:** `backend-compliance:8002` | **Rechtsgrundlage:** Art. 30 DSGVO

### Funktionen

- Anlegen, Bearbeiten und Löschen von Verarbeitungstätigkeiten (CRUD)
- Eindeutiger VVT-ID pro Tätigkeit (z.B. `VVT-001`)
- Vollständige Dokumentation je Tätigkeit: Zweck, Rechtsgrundlage, Datenkategorien, Empfänger, Drittlandtransfers, Löschfristen, TOMs
- Organisationsweite Metadaten: DSB-Kontakt, Branche, Standorte, Mitarbeiterzahl
- Audit-Log für alle Änderungen (CREATE / UPDATE / DELETE)
- Statistik-Endpoint: Gesamt, nach Status, nach Geschäftsfunktion, DSFA-pflichtige Tätigkeiten
- JSON-Export aller Aktivitäten
- Status-Workflow: `DRAFT` → `REVIEW` → `APPROVED` → `ARCHIVED`
- Schutzstufenklassifizierung: `LOW` / `MEDIUM` / `HIGH` / `CRITICAL`
- Profiling-Assistent (UI-seitig) zur Vorbefüllung

### API-Endpoints

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/api/compliance/vvt/organization` | Organisationsheader laden |
| `PUT` | `/api/compliance/vvt/organization` | Organisationsheader speichern |
| `GET` | `/api/compliance/vvt/activities` | Alle Tätigkeiten (Filter: status, business_function) |
| `POST` | `/api/compliance/vvt/activities` | Neue Tätigkeit anlegen |
| `GET` | `/api/compliance/vvt/activities/{id}` | Einzelne Tätigkeit |
| `PUT` | `/api/compliance/vvt/activities/{id}` | Tätigkeit aktualisieren |
| `DELETE` | `/api/compliance/vvt/activities/{id}` | Tätigkeit löschen |
| `GET` | `/api/compliance/vvt/audit-log` | Änderungshistorie |
| `GET` | `/api/compliance/vvt/export` | JSON-Export aller Tätigkeiten |
| `GET` | `/api/compliance/vvt/stats` | Statistiken |

### DB-Tabellen

| Tabelle | Modus | Beschreibung |
|---------|-------|--------------|
| `compliance_vvt_organization` | read/write | Organisationsweite Metadaten |
| `compliance_vvt_activities` | read/write | Verarbeitungstätigkeiten |
| `compliance_vvt_audit_log` | write | Änderungsprotokoll |

### Datenmodell (Aktivität)

```json
{
  "vvt_id": "VVT-001",
  "name": "Gehaltsabrechnung",
  "purposes": ["Vertragserfüllung"],
  "legal_bases": ["Art. 6 Abs. 1b DSGVO"],
  "data_subject_categories": ["Mitarbeiter"],
  "personal_data_categories": ["Bankdaten", "Steuer-ID"],
  "recipient_categories": ["Steuerberater"],
  "third_country_transfers": [],
  "retention_period": {"years": 10, "basis": "§ 257 HGB"},
  "protection_level": "HIGH",
  "dpia_required": false,
  "status": "APPROVED"
}
```

---

## Source Policy

**Route:** `/sdk/source-policy` | **Backend:** `backend-compliance:8002` | **Rechtsgrundlage:** Art. 5 DSGVO

### Funktionen

- Verwaltung erlaubter Compliance-Rechtsquellen (Gesetze, Leitlinien, Standards)
- Filter nach Quelltyp (`legal`, `guidance`, `template`, `technical`, `other`) und Lizenz
- PII-Regelwerk: Definition sensibler Datenkategorien (E-Mail, IBAN, Personalausweis, etc.)
- Filter nach PII-Kategorie (pii, financial, health, id, location, other)
- Quell-Operations-Matrix: Welche Operationen auf welchen Quellen sind erlaubt
- Policy-Audit-Log: Nachvollziehbare Protokollierung aller Policy-Änderungen
- Policy-Statistiken: Zusammenfassung des Compliance-Status
- Compliance-Report: Gesamtübersicht aller aktiven Quellen und Regeln

### API-Endpoints

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/api/source-policy/sources` | Quellen (Filter: source_type, license, active_only) |
| `POST` | `/api/source-policy/sources` | Neue Quelle anlegen |
| `PUT` | `/api/source-policy/sources/{id}` | Quelle aktualisieren |
| `DELETE` | `/api/source-policy/sources/{id}` | Quelle löschen |
| `GET` | `/api/source-policy/pii-rules` | PII-Regeln (Filter: category) |
| `POST` | `/api/source-policy/pii-rules` | Neue PII-Regel |
| `PUT` | `/api/source-policy/pii-rules/{id}` | PII-Regel aktualisieren |
| `DELETE` | `/api/source-policy/pii-rules/{id}` | PII-Regel löschen |
| `GET` | `/api/source-policy/operations-matrix` | Operations-Matrix |
| `GET` | `/api/source-policy/policy-stats` | Statistiken |
| `GET` | `/api/source-policy/compliance-report` | Compliance-Report |

### DB-Tabellen

| Tabelle | Modus | Beschreibung |
|---------|-------|--------------|
| `compliance_allowed_sources` | read/write | Erlaubte Rechtsquellen |
| `compliance_pii_rules` | read/write | PII-Erkennungsregeln |
| `compliance_source_operations` | read/write | Operations-Matrix |
| `compliance_source_policy_audit` | write | Audit-Trail |

---

## Document Generator

**Route:** `/sdk/document-generator` | **Backend:** breakpilot-core (Template-Service) | **Rechtsgrundlage:** Art. 28 DSGVO, DDG § 5

### Funktionen

- Generierung rechtlicher Dokumente aus Templates: Impressum, AVV, Datenschutzrichtlinie, NDA
- Templates werden aus `bp_legal_templates` (RAG-Collection) geladen
- Unternehmensspezifische Befüllung aus Company Profile
- **PDF-Export** direkt im Browser via `window.print()` — kein Server-seitiger Service erforderlich
- Fallback-Banner: Wenn der Template-Service (breakpilot-core) nicht erreichbar ist, erscheint ein informativer Hinweis
- Attributionsnachweis: Verwendete Rechtsquellen werden im Dokument aufgeführt

### Generierte Dokumente

| Dokument | Rechtsgrundlage | Format |
|----------|-----------------|--------|
| Impressum | DDG § 5 (ehemals TMG) | HTML / PDF |
| Auftragsverarbeitungsvertrag (AVV) | Art. 28 DSGVO | HTML / PDF |
| Datenschutzerklärung | Art. 13, 14 DSGVO | HTML / PDF |
| NDA / Vertraulichkeitsvereinbarung | GeschGehG | HTML / PDF |

### PDF-Export

Der PDF-Export öffnet ein neues Browser-Fenster mit dem vollständig formatierten Dokument
und löst automatisch den Browser-Druckdialog aus (`window.print()`). Keine zusätzliche
Server-Dependency erforderlich.

```
[Als PDF exportieren] → window.open() → Dokument-HTML → window.print() → Browser-PDF-Dialog
```

---

## Audit Checklist

**Route:** `/sdk/audit-checklist` | **Backend:** `backend-compliance:8002` | **Rechtsgrundlage:** Art. 5 Abs. 2 DSGVO (Rechenschaftspflicht)

### Funktionen

- Session-Management: Neue Audit-Sitzung erstellen (Name, Auditor, Scope)
- Status-Workflow: `draft` → `in_progress` → `completed` → `archived`
- Automatische Befüllung der Checkliste aus Requirements und Controls
- Interaktiver Sign-Off-Workflow: Konform / Teilweise / Nicht konform / Nicht geprüft
- Digitale Signatur-Hash (SHA-256) pro Prüfpunkt für Unveränderlichkeitsnachweis
- Notizen-Bearbeitung je Prüfpunkt
- **PDF-Download** in Deutsch oder Englisch (`GET /sessions/{id}/report/pdf`)
- JSON-Export der gesamten Checkliste
- Session-History: Übersicht vergangener Audit-Sitzungen

### API-Endpoints

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/api/compliance/audit/sessions` | Alle Sitzungen |
| `POST` | `/api/compliance/audit/sessions` | Neue Sitzung |
| `PUT` | `/api/compliance/audit/sessions/{id}` | Sitzung aktualisieren (Status) |
| `GET` | `/api/compliance/audit/checklist/{sessionId}` | Checkliste laden |
| `PUT` | `/api/compliance/audit/checklist/{sessionId}/items/{reqId}/sign-off` | Prüfpunkt abzeichnen |
| `GET` | `/api/compliance/audit/sessions/{sessionId}/report/pdf` | PDF-Report (lang=de/en) |

!!! warning "Korrekter PDF-Endpunkt"
    Der PDF-Download-Endpunkt lautet `/sessions/{id}/**report**/pdf`, nicht `/sessions/{id}/pdf`.
    Dieser Fehler war in früheren Versionen vorhanden und wurde behoben.

### DB-Tabellen

| Tabelle | Modus | Beschreibung |
|---------|-------|--------------|
| `compliance_audit_sessions` | read/write | Audit-Sitzungen |
| `compliance_audit_signoffs` | write | Prüfpunkt-Abzeichnungen mit Signatur-Hash |
| `compliance_requirements` | read | Prüfpunkte aus Requirements |

### PDF-Generierung

Die PDF-Reports werden serverseitig mit **ReportLab 4.2.5** generiert und enthalten:
- Deckblatt mit Audit-Metadaten
- Zusammenfassung mit Ampelstatus
- Statistik-Kreisdiagramm (konform / nicht konform / ausstehend)
- Prüfpunkt-Details mit Notizen und digitalem Signatur-Hash
- Anhang: Nicht-konforme Punkte mit Handlungsempfehlungen

---

## Audit Report

**Route:** `/sdk/audit-report` und `/sdk/audit-report/{sessionId}` | **Backend:** `backend-compliance:8002` | **Rechtsgrundlage:** Art. 5 Abs. 2 DSGVO

### Funktionen

- Übersicht aller Audit-Sitzungen mit Status-Badges (Entwurf / In Bearbeitung / Abgeschlossen / Archiviert)
- Detail-Seite pro Sitzung:
  - Sitzungs-Metadaten (Auditor, Organisation, Zeitraum)
  - Fortschrittsbalken mit Farbkodierung (grün ≥ 80%, gelb ≥ 50%, rot < 50%)
  - Statistik-Kacheln (konform / nicht konform / ausstehend)
  - Interaktive Prüfpunkte mit nachträglichem Sign-Off
  - Notizen-Bearbeitung per Prüfpunkt
  - PDF-Download mit Sprachauswahl (DE / EN)
- Navigation: Klick auf eine Sitzung in der Übersicht öffnet die Detail-Seite

### API-Endpoints

Nutzt dieselben Backend-Endpoints wie Audit Checklist (s.o.).

### DB-Tabellen

| Tabelle | Modus | Beschreibung |
|---------|-------|--------------|
| `compliance_audit_sessions` | read/write | Sitzungsdaten inkl. Fortschritt |
| `compliance_audit_signoffs` | read/write | Nachträgliche Prüfpunkt-Aktualisierungen |

---

## Training Engine

**Route:** `/sdk/training` | **Backend:** `ai-compliance-sdk:8093` (Go) | **Rechtsgrundlage:** Art. 39 Abs. 1b DSGVO, EU AI Act Art. 4

### Funktionen

- **28 vordefinierte Schulungsmodule** für DSGVO, ISO 27001, AI Act, Hinweisgeberschutz u.a.
- Modul-Typen: Jährlich (`annual`), Ereignisbasiert (`event_trigger`), Mikro-Schulung (`micro`)
- Quiz-System: Automatisch generierte Fragen mit konfigurierbarer Bestehensgrenze
- Zertifikate bei erfolgreichem Abschluss
- Schulungsmatrix: Rollen-basierte Pflichtmodulzuordnung (CISO, DSB, Entwickler, etc.)
- Aufgabenzuweisung: Schulungen können Mitarbeitern zugewiesen werden
- Eskalation: Automatische Erinnerungen bei überfälligen Pflichtschulungen
- KI-generierter Content: Schulungsinhalte können via Ollama-LLM automatisch generiert werden
- Audit-Log: Vollständige Nachverfolgung aller Schulungsaktivitäten

### API-Endpoints

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/sdk/v1/training/modules` | Alle Module (Filter: regulation_area, frequency_type, search) |
| `POST` | `/sdk/v1/training/modules` | Neues Modul anlegen |
| `GET` | `/sdk/v1/training/modules/{id}` | Modul mit Content und Quiz-Fragen |
| `PUT` | `/sdk/v1/training/modules/{id}` | Modul aktualisieren |
| `GET` | `/sdk/v1/training/matrix` | Schulungsmatrix |
| `POST` | `/sdk/v1/training/matrix` | Matrix-Eintrag setzen |
| `GET` | `/sdk/v1/training/assignments` | Schulungszuweisungen |
| `POST` | `/sdk/v1/training/assignments/compute` | Zuweisungen für Nutzer berechnen |
| `POST` | `/sdk/v1/training/assignments/{id}/complete` | Schulung abschließen |
| `GET` | `/sdk/v1/training/quiz/{moduleId}` | Quiz-Fragen laden |
| `POST` | `/sdk/v1/training/quiz/{moduleId}/submit` | Quiz-Antworten einreichen |
| `GET` | `/sdk/v1/training/stats` | Schulungsstatistiken |
| `GET` | `/sdk/v1/training/deadlines` | Fällige Schulungen |
| `POST` | `/sdk/v1/training/escalation/check` | Eskalationen prüfen |
| `POST` | `/sdk/v1/training/content/generate` | KI-Content generieren (Ollama) |

### DB-Tabellen (ai-compliance-sdk PostgreSQL)

| Tabelle | Modus | Beschreibung |
|---------|-------|--------------|
| `training_modules` | read/write | Schulungsmodule mit Metadaten |
| `training_assignments` | read/write | Mitarbeiterzuweisungen |
| `training_quiz_questions` | read/write | Quiz-Fragen je Modul |
| `training_quiz_attempts` | read/write | Quiz-Versuche und Ergebnisse |
| `training_matrix_entries` | read/write | Rollen-Modul-Zuordnung |
| `training_audit_log` | write | Aktivitätsprotokoll |

### Vordefinierte Module (Auswahl)

| Code | Titel | Bereich | Typ |
|------|-------|---------|-----|
| `DSGVO-BASIC` | DSGVO Grundlagen | dsgvo | annual |
| `DSGVO-BREACH` | Datenpannen und Meldepflichten | dsgvo | event_trigger |
| `DSGVO-DSR` | Betroffenenrechte | dsgvo | annual |
| `AI-BAS` | KI-Kompetenz Grundlagen | ai_act | annual |
| `AI-RISK` | Hochrisiko-KI-Systeme | ai_act | event_trigger |
| `ISMS-AUD` | ISMS Audit-Vorbereitung | iso27001 | event_trigger |
| `HIN-BAS` | Hinweisgeberschutz | hinschg | annual |
| `PHISH` | Phishing-Erkennung | iso27001 | micro |

---

## Datenfluss

```mermaid
graph LR
    A[Source Policy] --> B[Requirements]
    B --> C[Audit Checklist]
    C --> D[Audit Report]
    D --> E[Obligations]
    E --> F[TOMs]
    F --> G[Löschfristen]
    G --> H[VVT]

    I[Document Generator] --> J[Workflow]
    K[Academy] --> L[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.
Die **Training Engine** operiert parallel im Betrieb-Paket und liefert Evidence für Audits.