From 0e9970ff32f59762c7ca5a70a1d6f65f8b7946d6 Mon Sep 17 00:00:00 2001 From: Benjamin Boenisch Date: Fri, 13 Feb 2026 22:05:30 +0100 Subject: [PATCH] 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 --- docs-src/services/document-crawler/index.md | 147 ++++++++++++++++++ docs-src/services/sdk-modules/academy.md | 35 +++++ docs-src/services/sdk-modules/incidents.md | 37 +++++ .../services/sdk-modules/whistleblower.md | 33 ++++ mkdocs.yml | 6 + 5 files changed, 258 insertions(+) create mode 100644 docs-src/services/document-crawler/index.md create mode 100644 docs-src/services/sdk-modules/academy.md create mode 100644 docs-src/services/sdk-modules/incidents.md create mode 100644 docs-src/services/sdk-modules/whistleblower.md diff --git a/docs-src/services/document-crawler/index.md b/docs-src/services/document-crawler/index.md new file mode 100644 index 0000000..b034d59 --- /dev/null +++ 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} +``` diff --git a/docs-src/services/sdk-modules/academy.md b/docs-src/services/sdk-modules/academy.md new file mode 100644 index 0000000..b570cf1 --- /dev/null +++ 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. diff --git a/docs-src/services/sdk-modules/incidents.md b/docs-src/services/sdk-modules/incidents.md new file mode 100644 index 0000000..34c8be5 --- /dev/null +++ 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. diff --git a/docs-src/services/sdk-modules/whistleblower.md b/docs-src/services/sdk-modules/whistleblower.md new file mode 100644 index 0000000..c4b5827 --- /dev/null +++ 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. diff --git a/mkdocs.yml b/mkdocs.yml index e2bdd59..97ec9b3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -62,6 +62,12 @@ nav: - Developer Guide: services/ai-compliance-sdk/DEVELOPER.md - Auditor Dokumentation: services/ai-compliance-sdk/AUDITOR_DOCUMENTATION.md - SBOM: services/ai-compliance-sdk/SBOM.md + - Document Crawler: + - Uebersicht: services/document-crawler/index.md + - SDK Module: + - Academy: services/sdk-modules/academy.md + - Whistleblower: services/sdk-modules/whistleblower.md + - Incidents: services/sdk-modules/incidents.md - Entwicklung: - Testing: development/testing.md - Dokumentation: development/documentation.md