docs: MkDocs, SDK-Flow und Tests fuer 6 Dokumentations-Module aktualisieren
MkDocs: - Neue Dokumentationsseite: docs-src/services/sdk-modules/dokumentations-module.md Beschreibt alle 6 Module (VVT, Source Policy, Document Generator, Audit Checklist, Audit Report, Training Engine) mit API-Endpoints, DB-Tabellen, Datenmodell und Besonderheiten - mkdocs.yml: Neuen Eintrag "Dokumentations-Module (Paket 3+)" ergaenzt SDK Flow (flow-data.ts): - VVT: dbTables korrigiert ([] → compliance_vvt_organization/activities/audit_log), dbMode: none → read/write, descriptionLong auf Backend-Persistenz aktualisiert - Training: dbTables ergaenzt (training_modules/assignments/quiz_*/matrix_entries/ audit_log), dbMode: none → read/write, Beschreibung auf 28 Module aktualisiert - Source Policy: Tabellennamen korrigiert (compliance_pii_field_rules → compliance_pii_rules, compliance_source_policies entfernt, compliance_source_operations ergaenzt) - Document Generator: Beschreibung um PDF-Export (window.print) und Fallback-Banner ergaenzt Tests: - Neue Datei: tests/test_source_policy_routes.py (35 Tests, alle gruen) - Schema-Tests: SourceCreate, SourceUpdate, PIIRuleCreate, PIIRuleUpdate - DB-Model-Tests: AllowedSourceDB, PIIRuleDB - Filter-Logik: source_type-Filter und category-Filter Unit-Tests - Audit-Log-Helper: _log_audit Verhalten verifiziert Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
318
docs-src/services/sdk-modules/dokumentations-module.md
Normal file
318
docs-src/services/sdk-modules/dokumentations-module.md
Normal file
@@ -0,0 +1,318 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user