docs: Add MkDocs documentation for Document Crawler and SDK modules

Adds documentation pages for: - Document Crawler (architecture, API endpoints, gap analysis) - Academy/Schulungsmodul - Whistleblower/Hinweisgebersystem (HinSchG) - Incidents/Datenschutzvorfaelle (Art. 33/34 DSGVO) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-13 22:05:30 +01:00
parent 504dd3591b
commit 0e9970ff32
5 changed files with 258 additions and 0 deletions
--- a/docs-src/services/document-crawler/index.md
+++ b/docs-src/services/document-crawler/index.md
@@ -0,0 +1,147 @@
+# Document Crawler & Auto-Onboarding
+
+Der Document Crawler ist ein eigenstaendiger Python/FastAPI-Microservice, der automatisch lokale Dateisysteme nach bestehenden Compliance-Dokumenten durchsucht, diese mittels LLM klassifiziert, in IPFS archiviert und eine Compliance-Lueckenanalyse durchfuehrt.
+
+## Architektur
+
+```mermaid
+graph LR
+    FE[Frontend Admin-v2] -->|API Proxy| DC[Document Crawler :8098]
+    DC -->|LLM Klassifizierung| SDK[AI Compliance SDK :8090]
+    DC -->|IPFS Archivierung| DSMS[DSMS Gateway :8082]
+    DC -->|Daten| PG[(PostgreSQL)]
+```
+
+| Eigenschaft | Wert |
+|------------|-------|
+| **Service** | `document-crawler` |
+| **Port** | 8098 |
+| **Container** | `bp-compliance-document-crawler` |
+| **Sprache** | Python 3.11 / FastAPI |
+| **Datenbank** | PostgreSQL (`breakpilot_db`) |
+
+## Features
+
+- **Filesystem Crawling** — Automatisches Scannen lokaler Verzeichnisse und NAS-Shares
+- **Delta-Erkennung** — SHA-256 Hash-basierte Aenderungserkennung, nur geaenderte Dateien werden erneut verarbeitet
+- **Text-Extraktion** — PDF (PyMuPDF), DOCX (python-docx), XLSX (openpyxl), PPTX (python-pptx)
+- **LLM-Klassifizierung** — Automatische Kategorisierung via AI Compliance SDK
+- **Keyword-Fallback** — Heuristische Klassifizierung wenn LLM nicht verfuegbar (Confidence max 0.3)
+- **IPFS-Archivierung** — Langzeit-Archivierung ueber DSMS Gateway
+- **Gap-Analyse** — Vergleich gefundener Dokumente gegen Compliance-Matrix
+- **Onboarding-Report** — Compliance-Score, fehlende Dokumente, Handlungsempfehlungen
+
+## Dokumentklassifizierungen
+
+| Kategorie | Beschreibung |
+|-----------|-------------|
+| VVT | Verzeichnis von Verarbeitungstaetigkeiten |
+| TOM | Technische und organisatorische Massnahmen |
+| DSE | Datenschutzerklaerung |
+| AVV | Auftragsverarbeitungsvertrag |
+| DSFA | Datenschutz-Folgenabschaetzung |
+| Loeschkonzept | Loeschfristen und -verfahren |
+| Einwilligung | Einwilligungserklaerungen |
+| Vertrag | Vertraege mit Datenschutzbezug |
+| Richtlinie | Interne Datenschutzrichtlinien |
+| Schulungsnachweis | Datenschutz-Schulungszertifikate |
+| Sonstiges | Nicht klassifizierbare Dokumente |
+
+## Datenbank-Schema
+
+4 Tabellen (Migration 014):
+
+### `crawler_sources`
+Konfigurierbare Crawl-Verzeichnisse mit Pfad, Dateityp-Filter, Tiefenbegrenzung und Ausschlussmustern.
+
+### `crawler_jobs`
+Jede Crawl-Ausfuehrung mit Status (pending/running/completed/failed), Typ (full/delta) und Statistiken.
+
+### `crawler_documents`
+Jede entdeckte Datei mit Metadaten, extrahiertem Text, Klassifizierung, Confidence-Score und Archivierungsstatus.
+
+### `crawler_onboarding_reports`
+Zusammenfassungsberichte mit Compliance-Score, Klassifizierungs-Aufschluesselung und Gap-Analyse.
+
+## API Endpoints
+
+Alle unter `/api/v1/crawler/`, benoetigen `X-Tenant-ID` Header.
+
+### Quellen (Sources)
+
+| Method | Endpoint | Beschreibung |
+|--------|----------|-------------|
+| GET | `/sources` | Crawl-Quellen auflisten |
+| POST | `/sources` | Neue Quelle erstellen |
+| PUT | `/sources/{id}` | Quelle aktualisieren |
+| DELETE | `/sources/{id}` | Quelle loeschen |
+| POST | `/sources/{id}/test` | Konnektivitaet testen |
+
+### Jobs
+
+| Method | Endpoint | Beschreibung |
+|--------|----------|-------------|
+| POST | `/jobs` | Crawl starten (full/delta) |
+| GET | `/jobs` | Jobs auflisten |
+| GET | `/jobs/{id}` | Job-Details + Fortschritt |
+| POST | `/jobs/{id}/cancel` | Laufenden Job abbrechen |
+
+### Dokumente
+
+| Method | Endpoint | Beschreibung |
+|--------|----------|-------------|
+| GET | `/documents` | Dokumente auflisten (Filter: classification, status) |
+| GET | `/documents/{id}` | Dokument-Details + Text-Vorschau |
+| PUT | `/documents/{id}/classify` | Manuelle Klassifizierungs-Korrektur |
+| POST | `/documents/{id}/archive` | In IPFS archivieren |
+| POST | `/documents/archive-batch` | Bulk-Archivierung |
+
+### Reports
+
+| Method | Endpoint | Beschreibung |
+|--------|----------|-------------|
+| POST | `/reports/generate` | Onboarding-Report generieren |
+| GET | `/reports` | Reports auflisten |
+| GET | `/reports/{id}` | Report mit Gap-Analyse |
+
+## Gap-Analyse
+
+Die Gap-Analyse vergleicht gefundene Dokumenttypen gegen eine Pflichtdokumenten-Matrix:
+
+| Dokument | Pflicht fuer | Severity |
+|----------|-------------|----------|
+| VVT | Alle Unternehmen | CRITICAL |
+| TOM | Alle Unternehmen | CRITICAL |
+| DSE | Alle Unternehmen | CRITICAL |
+| Loeschkonzept | Alle Unternehmen | HIGH |
+| AVV | Auftragsverarbeiter | HIGH |
+| DSFA | KI-Nutzer, Hochrisiko-Verarbeitung | HIGH |
+| Schulungsnachweis | Alle Unternehmen | MEDIUM |
+| Richtlinie | Alle Unternehmen | MEDIUM |
+
+## Frontend
+
+4-Tab-Seite unter `/sdk/document-crawler`:
+
+1. **Quellen** — Crawl-Verzeichnisse konfigurieren, Konnektivitaet testen
+2. **Crawl-Jobs** — Crawl starten, Fortschrittsbalken mit Auto-Refresh, Job-Historie
+3. **Dokumente** — Tabelle mit Klassifizierungs-Badges, Confidence-Bars, Reklassifizierung, Archivierung
+4. **Onboarding-Report** — SVG Compliance-Score Ring, Gap-Analyse mit Severity-Cards
+
+## Konfiguration
+
+| Umgebungsvariable | Standard | Beschreibung |
+|-------------------|----------|-------------|
+| `PORT` | 8098 | Service-Port |
+| `DATABASE_URL` | - | PostgreSQL Connection String |
+| `LLM_GATEWAY_URL` | `http://ai-compliance-sdk:8090` | LLM Service URL |
+| `DSMS_GATEWAY_URL` | `http://dsms-gateway:8082` | IPFS Service URL |
+| `CRAWL_BASE_PATH` | `/data/crawl` | Basis-Pfad im Container |
+| `MAX_FILE_SIZE_MB` | 50 | Maximale Dateigroesse |
+
+## Health Check
+
+```bash
+curl http://localhost:8098/health
+# {status: healthy, service: document-crawler}
+```
--- a/docs-src/services/sdk-modules/academy.md
+++ b/docs-src/services/sdk-modules/academy.md
@@ -0,0 +1,35 @@
+# Academy — Schulungsmodul
+
+Das Academy-Modul ermoeglicht die Verwaltung von Datenschutz-Schulungen und -Zertifizierungen.
+
+## Features
+
+- **Kursverwaltung** — DSGVO-, KI- und branchenspezifische Schulungskurse erstellen und verwalten
+- **Modulare Struktur** — Kurse bestehen aus Modulen mit Lektionen und Quizzes
+- **Teilnehmer-Tracking** — Fortschritt, Abschlussquoten und Zertifikatsverwaltung
+- **Compliance-Nachweis** — Automatische Generierung von Schulungsnachweisen fuer Audits
+
+## API Endpoints
+
+Alle unter `/api/v1/academy/`, benoetigen `X-Tenant-ID` Header.
+
+| Method | Endpoint | Beschreibung |
+|--------|----------|-------------|
+| GET | `/courses` | Kurse auflisten |
+| POST | `/courses` | Neuen Kurs erstellen |
+| GET | `/courses/{id}` | Kursdetails |
+| PUT | `/courses/{id}` | Kurs aktualisieren |
+| DELETE | `/courses/{id}` | Kurs loeschen |
+| GET | `/courses/{id}/modules` | Module eines Kurses |
+| POST | `/courses/{id}/enroll` | Teilnehmer einschreiben |
+| GET | `/enrollments` | Einschreibungen auflisten |
+| POST | `/enrollments/{id}/complete` | Modul als abgeschlossen markieren |
+| GET | `/certificates` | Zertifikate auflisten |
+
+## Frontend
+
+Seite unter `/sdk/academy` mit Kursuebersicht, Modulverwaltung und Teilnehmer-Tracking.
+
+## Datenbank
+
+Migration `008_academy_schema.sql` erstellt Tabellen fuer Kurse, Module, Einschreibungen und Zertifikate.
--- a/docs-src/services/sdk-modules/incidents.md
+++ b/docs-src/services/sdk-modules/incidents.md
@@ -0,0 +1,37 @@
+# Incidents — Datenschutzvorfaelle
+
+Verwaltung und Dokumentation von Datenschutzvorfaellen gemaess Art. 33/34 DSGVO.
+
+## Features
+
+- **Vorfallerfassung** — Strukturierte Eingabe mit Schweregrad-Bewertung
+- **72-Stunden-Frist** — Automatisches Tracking der Meldefrist an die Aufsichtsbehoerde
+- **Risikobewertung** — Automatische Einschaetzung ob Meldepflicht besteht
+- **Behoerdenmeldung** — Vorausgefuellte Meldeformulare fuer Aufsichtsbehoerden
+- **Betroffenen-Benachrichtigung** — Vorlagen fuer die Benachrichtigung Betroffener (Art. 34 DSGVO)
+- **Massnahmen-Tracking** — Dokumentation von Gegenmassnahmen und Lessons Learned
+
+## API Endpoints
+
+Alle unter `/api/v1/incidents/`, benoetigen `X-Tenant-ID` Header.
+
+| Method | Endpoint | Beschreibung |
+|--------|----------|-------------|
+| GET | `/incidents` | Vorfaelle auflisten |
+| POST | `/incidents` | Neuen Vorfall melden |
+| GET | `/incidents/{id}` | Vorfalldetails |
+| PUT | `/incidents/{id}` | Vorfall aktualisieren |
+| PUT | `/incidents/{id}/severity` | Schweregrad aendern |
+| POST | `/incidents/{id}/notify-authority` | Behoerdenmeldung ausloesen |
+| POST | `/incidents/{id}/notify-affected` | Betroffene benachrichtigen |
+| GET | `/incidents/{id}/timeline` | Ereignis-Timeline |
+| POST | `/incidents/{id}/measures` | Massnahme hinzufuegen |
+| GET | `/statistics` | Vorfall-Statistiken |
+
+## Frontend
+
+Seite unter `/sdk/incidents` mit Vorfallsuebersicht, Detailansicht mit Timeline, Fristen-Ampel und Statistiken.
+
+## Datenbank
+
+Migration `010_incidents_schema.sql` erstellt Tabellen fuer Vorfaelle, Massnahmen, Meldungen und Benachrichtigungen.
--- a/docs-src/services/sdk-modules/whistleblower.md
+++ b/docs-src/services/sdk-modules/whistleblower.md
@@ -0,0 +1,33 @@
+# Whistleblower — Hinweisgebersystem
+
+HinSchG-konformes Hinweisgebersystem fuer anonyme Meldungen und sichere Fallbearbeitung.
+
+## Features
+
+- **Anonyme Meldungen** — Sichere, anonyme Eingabe von Hinweisen
+- **Fallbearbeitung** — Workflow fuer Sichtung, Untersuchung und Abschluss
+- **Fristen-Management** — Automatische Ueberwachung der gesetzlichen Bearbeitungsfristen (7 Tage Eingangsbestaetigung, 3 Monate Rueckmeldung)
+- **Kommunikationskanal** — Anonymer Austausch zwischen Hinweisgeber und Ombudsperson
+- **Audit-Trail** — Lueckenlose Dokumentation aller Bearbeitungsschritte
+
+## API Endpoints
+
+Alle unter `/api/v1/whistleblower/`, benoetigen `X-Tenant-ID` Header.
+
+| Method | Endpoint | Beschreibung |
+|--------|----------|-------------|
+| GET | `/reports` | Meldungen auflisten |
+| POST | `/reports` | Neue Meldung erstellen |
+| GET | `/reports/{id}` | Meldungsdetails |
+| PUT | `/reports/{id}/status` | Status aktualisieren |
+| POST | `/reports/{id}/messages` | Nachricht hinzufuegen |
+| GET | `/reports/{id}/messages` | Nachrichten abrufen |
+| GET | `/statistics` | Statistiken |
+
+## Frontend
+
+Seite unter `/sdk/whistleblower` mit Meldungsuebersicht, Falldetails und Statistik-Dashboard.
+
+## Datenbank
+
+Migration `009_whistleblower_schema.sql` erstellt Tabellen fuer Meldungen, Nachrichten und Bearbeitungsschritte.