From d212208587b769408e442933c449785e8f9b7701 Mon Sep 17 00:00:00 2001 From: Benjamin Admin Date: Thu, 5 Mar 2026 20:33:08 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20MkDocs-Aktualisierung=20=E2=80=94=20Obl?= =?UTF-8?q?igations=20v2,=20Extraction,=20fehlende=20Module?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - obligations.md: NEU — Obligations Framework v2 (325 Pflichten, 9 Regulierungen, Condition Engine, TOM-Mapping, Gap-Analyse, alle 13 API-Endpoints) - requirements.md: POST /compliance/extract-requirements-from-rag dokumentiert (RAG-Collections, dry_run, Deduplication, Auto-Regulation-Stubs) - vorbereitung-module.md: UCCA Obligations v2 Abschnitt + neue Endpoints + Hinweis: Go-Tests lokal statt im Container - index.md: Obligations, IACE, Import, Screening, RAG zur Modulliste + URLs - mkdocs.yml: obligations.md als nav-Eintrag Co-Authored-By: Claude Sonnet 4.6 --- docs-src/index.md | 10 + docs-src/services/sdk-modules/obligations.md | 281 ++++++++++++++++++ docs-src/services/sdk-modules/requirements.md | 60 ++++ .../sdk-modules/vorbereitung-module.md | 45 ++- mkdocs.yml | 1 + 5 files changed, 382 insertions(+), 15 deletions(-) create mode 100644 docs-src/services/sdk-modules/obligations.md diff --git a/docs-src/index.md b/docs-src/index.md index 2b19c86..081fa1b 100644 --- a/docs-src/index.md +++ b/docs-src/index.md @@ -44,6 +44,8 @@ Module die Compliance-Kunden im SDK sehen und nutzen: | **Evidence** | Compliance-Nachweise mit Gueltigkeit | /sdk/evidence | | **Risk Matrix** | 5x5 Risikomatrix (Inherent/Residual) | /sdk/risks | | **AI Act Compliance** | KI-Verordnung Konformitaet | /sdk/ai-act | +| **Obligations v2** | 325 Pflichten aus 9 Regulierungen, TOM-Mapping, Gap-Analyse | /sdk/obligations | +| **IACE** | CE-Risikobeurteilung (Maschinenverordnung, AI Act, CRA) | /sdk/iace | | **Audit Checklist** | Audit-Checkliste mit Sign-Off | /sdk/audit-checklist | | **Audit Report** | Audit-Berichte mit PDF-Export | /sdk/audit-report | | **Consent Management** | Einwilligungs-Verwaltung | /sdk/einwilligungen | @@ -53,6 +55,9 @@ Module die Compliance-Kunden im SDK sehen und nutzen: | **Incidents** | Datenschutz-Vorfaelle (Art. 33/34 DSGVO) | /sdk/incidents | | **Vendors** | Auftragsverarbeiter-Management | /sdk/vendor-compliance | | **Reporting** | Compliance-Berichte fuer Top Management | /sdk/reporting | +| **Import** | Dokument-Import + Gap-Analyse | /sdk/import | +| **Screening** | SBOM + CVE-Scan via OSV.dev | /sdk/screening | +| **RAG/Quellen** | Semantische Suche in Regulierungstexten | /sdk/rag | | **Industry Templates** | Branchenvorlagen (E-Commerce, Gesundheit, etc.) | /sdk/industry-templates | | **Document Crawler** | Automatisches Crawling von Rechtstexten | /sdk/document-crawler | | **Advisory Board** | KI-Compliance-Beirat | /sdk/advisory-board | @@ -91,6 +96,11 @@ Interne Tools fuer die BreakPilot-Plattformverwaltung: | https://macmini:3007/sdk/ai-act | AI Act | | https://macmini:3007/sdk/audit-checklist | Audit Checklist | | https://macmini:3007/sdk/audit-report | Audit Report | +| https://macmini:3007/sdk/obligations | Obligations v2 | +| https://macmini:3007/sdk/iace | IACE (CE-Risikobeurteilung) | +| https://macmini:3007/sdk/import | Document Import | +| https://macmini:3007/sdk/screening | System Screening | +| https://macmini:3007/sdk/rag | RAG/Quellen | | https://macmini:3007/sdk/tom | TOM | | https://macmini:3007/sdk/dsfa | DSFA | | https://macmini:3007/sdk/vvt | VVT | diff --git a/docs-src/services/sdk-modules/obligations.md b/docs-src/services/sdk-modules/obligations.md new file mode 100644 index 0000000..88c58a6 --- /dev/null +++ b/docs-src/services/sdk-modules/obligations.md @@ -0,0 +1,281 @@ +# Obligations Framework v2 (CP-OBL) + +Regulierungsübergreifende Pflichten-Datenbank mit Condition Engine, TOM-Control-Mapping und Gap-Analyse. + +**Prefix:** `CP-OBL` · **Frontend:** `https://macmini:3007/sdk/obligations` +**Service:** `ai-compliance-sdk` (Go/Gin, Port 8093) +**Proxy:** `/api/sdk/v1/ucca/obligations/[[...path]]` → `ai-compliance-sdk:8090/sdk/v1/ucca/obligations/...` + +--- + +## Überblick + +Das Obligations Framework v2 ersetzt die ursprüngliche, hardcoded Pflichten-Liste durch eine **JSON-basierte, regulierungsübergreifende Pflichten-Datenbank**. + +| Kenngröße | Wert | +|-----------|------| +| **Regulierungen** | 9 (DSGVO, BDSG, AI Act, NIS2, TTDSG, DSA, Data Act, DORA, EU Machinery) | +| **Pflichten (Obligations)** | 325 | +| **TOM-Controls** | 180 | +| **Condition Engine** | `all_of` / `any_of` Logikaum mit 40+ Feldern aus UnifiedFacts | + +--- + +## Architektur + +``` +policies/obligations/v2/ +├── _manifest.json ← Alle Regulierungen + Metadaten +├── _schema.json ← JSON-Schema zur Validierung +├── _tom_mapping.json ← Obligations → TOM-Controls Mapping +├── dsgvo_v2.json ← DSGVO-Pflichten (~120) +├── ai_act_v2.json ← AI Act Pflichten (~40) +├── nis2_v2.json ← NIS2-Pflichten (~30) +├── bdsg_v2.json +├── ttdsg_v2.json +├── dsa_v2.json +├── data_act_v2.json +├── dora_v2.json +└── eu_machinery_v2.json +``` + +### Condition Engine + +Jede Pflicht enthält ein `condition`-Feld, das gegen `UnifiedFacts` ausgewertet wird: + +```json +{ + "id": "DSGVO-ART-37-1", + "article": "Art. 37 Abs. 1", + "title": "DSB-Benennung Pflicht", + "condition": { + "any_of": [ + { "field": "employeeCount", "op": "gte", "value": 20 }, + { "field": "processesHealthData", "op": "eq", "value": true }, + { "field": "isPublicAuthority", "op": "eq", "value": true } + ] + }, + "priority": "high", + "category": "Governance", + "responsible_role": "Geschäftsführung", + "deadline_days": 30 +} +``` + +**Operatoren:** `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `contains` + +### UnifiedFacts (40+ Felder) + +Werden aus Company-Profil, Compliance-Scope und Use-Case-Assessments zusammengeführt: + +```go +type UnifiedFacts struct { + EmployeeCount int + ProcessesHealthData bool + IsPublicAuthority bool + UsesAI bool + AIRiskClass string // minimal/limited/high/unacceptable + SellsToEU bool + IsFinancialEntity bool // DORA + IsMachineBuilder bool // EU Machinery + // ... 35+ weitere Felder +} +``` + +### TOM-Control-Mapping + +Jede Pflicht ist einem oder mehreren der 180 TOM-Controls (`policies/tom_controls_v1.json`) zugeordnet: + +``` +Obligation DSGVO-ART-32 → Controls [TOM-001, TOM-042, TOM-097] +``` + +--- + +## Obligations-Kategorien + +| Kategorie | Bedeutung | +|-----------|-----------| +| `Meldepflicht` | Melde- und Benachrichtigungspflichten | +| `Governance` | Verantwortlichkeitsstrukturen | +| `Technisch` | Technische Maßnahmen | +| `Organisatorisch` | Organisatorische Maßnahmen | +| `Dokumentation` | Dokumentations- und Nachweispflichten | +| `Schulung` | Mitarbeiterschulungen | +| `Audit` | Prüfungs- und Auditpflichten | +| `Compliance` | Allgemeine Compliance-Pflichten | + +--- + +## Prioritäten + +| Wert | Deadline | Bedeutung | +|------|---------|-----------| +| `critical` | Sofort | Rechtlicher Verstoß wenn nicht erfüllt | +| `high` | ≤ 30 Tage | Hohes Bußgeldrisiko | +| `medium` | ≤ 90 Tage | Mittleres Risiko | +| `low` | ≤ 365 Tage | Empfehlung | + +--- + +## API Endpoints + +### Assessment + +| Methode | Pfad | Beschreibung | +|---------|------|--------------| +| `POST` | `/sdk/v1/ucca/obligations/assess` | Pflichten bewerten basierend auf UnifiedFacts | +| `GET` | `/sdk/v1/ucca/obligations/:assessmentId` | Assessment abrufen | +| `GET` | `/sdk/v1/ucca/obligations/:assessmentId/by-regulation` | Pflichten nach Regulierung gruppiert | +| `GET` | `/sdk/v1/ucca/obligations/:assessmentId/by-deadline` | Pflichten nach Deadline gruppiert | +| `GET` | `/sdk/v1/ucca/obligations/:assessmentId/by-responsible` | Pflichten nach Verantwortlichem | + +### Export + +| Methode | Pfad | Beschreibung | +|---------|------|--------------| +| `POST` | `/sdk/v1/ucca/obligations/export/memo` | C-Level-Memo aus Assessment exportieren | +| `POST` | `/sdk/v1/ucca/obligations/export/direct` | Direkt aus Overview exportieren (ohne Assessment-ID) | + +### Regulierungen + +| Methode | Pfad | Beschreibung | +|---------|------|--------------| +| `GET` | `/sdk/v1/ucca/obligations/regulations` | Alle verfügbaren Regulierungen auflisten | +| `GET` | `/sdk/v1/ucca/obligations/regulations/:id/decision-tree` | Entscheidungsbaum für eine Regulierung | + +### Schnellprüfung + +| Methode | Pfad | Beschreibung | +|---------|------|--------------| +| `POST` | `/sdk/v1/ucca/obligations/quick-check` | Schnellprüfung ohne Persistenz | +| `POST` | `/sdk/v1/ucca/obligations/assess-from-scope` | Assessment aus Compliance-Scope-Daten | + +### TOM-Controls & Gap-Analyse + +| Methode | Pfad | Beschreibung | +|---------|------|--------------| +| `GET` | `/sdk/v1/ucca/obligations/tom-controls/for-obligation/:obligationId` | TOMs für eine Pflicht | +| `POST` | `/sdk/v1/ucca/obligations/gap-analysis` | Gap-Analyse: fehlende TOMs identifizieren | +| `GET` | `/sdk/v1/ucca/obligations/tom-controls/:controlId/obligations` | Alle Pflichten für einen TOM-Control | + +### Request-Beispiel (POST /assess) + +```json +{ + "tenant_id": "uuid", + "facts": { + "employeeCount": 45, + "processesHealthData": false, + "usesAI": true, + "aiRiskClass": "limited", + "sellsToEU": true, + "isFinancialEntity": false, + "isMachineBuilder": false + }, + "regulations": ["DSGVO", "AI_ACT", "NIS2"] +} +``` + +### Response-Ausschnitt + +```json +{ + "assessment_id": "uuid", + "tenant_id": "uuid", + "total_obligations": 87, + "critical": 3, + "high": 24, + "medium": 41, + "low": 19, + "obligations": [ + { + "id": "DSGVO-ART-13", + "title": "Informationspflicht bei Erhebung", + "article": "Art. 13 DSGVO", + "category": "Dokumentation", + "priority": "high", + "responsible_role": "Datenschutzbeauftragter", + "deadline_days": 0, + "tom_controls": ["TOM-001", "TOM-042"] + } + ] +} +``` + +--- + +## Gap-Analyse + +Die Gap-Analyse vergleicht die **geforderten TOM-Controls** (aus Obligations) mit den **implementierten Controls** (aus `compliance_controls`): + +```http +POST /sdk/v1/ucca/obligations/gap-analysis +{ + "assessment_id": "uuid", + "implemented_control_ids": ["TOM-001", "TOM-042"] +} +``` + +**Response:** + +```json +{ + "gaps": [ + { + "obligation_id": "DSGVO-ART-32", + "missing_controls": ["TOM-097", "TOM-133"], + "risk_level": "high" + } + ], + "gap_score": 0.73, + "fully_covered": 41, + "partially_covered": 23, + "not_covered": 23 +} +``` + +--- + +## Frontend + +**URL:** `https://macmini:3007/sdk/obligations` + +Die Obligations-Seite zeigt: + +- **Überblick-Kacheln:** Gesamtanzahl, nach Priorität, nach Regulierung +- **Regulierungs-Tabs:** Pflichten gefiltert nach DSGVO, AI Act, NIS2, etc. +- **Gap-Analyse-View:** Fehlende TOM-Controls visualisiert als Heatmap +- **TOM-Control-Panel:** Mapping von Pflichten → Controls mit Status +- **Export:** C-Level-Memo (Markdown) direkt aus dem Frontend + +--- + +## Regulierungen im Detail + +| Kürzel | Regulierung | Pflichten (ca.) | +|--------|-------------|-----------------| +| `DSGVO` | DSGVO (EU) 2016/679 | ~120 | +| `BDSG` | Bundesdatenschutzgesetz | ~25 | +| `AI_ACT` | AI Act (EU) 2024/1689 | ~40 | +| `NIS2` | NIS2-Richtlinie 2022/2555 | ~30 | +| `TTDSG` | Telekommunikation-Telemedien-Datenschutz-Gesetz | ~20 | +| `DSA` | Digital Services Act 2022/2065 | ~20 | +| `DATA_ACT` | Data Act (EU) 2023/2854 | ~25 | +| `DORA` | Digital Operational Resilience Act | ~25 | +| `EU_MACHINERY` | Maschinenverordnung (EU) 2023/1230 | ~20 | + +--- + +## Tests + +**Testdatei:** `ai-compliance-sdk/internal/ucca/obligation_condition_engine_test.go` + +```bash +# Lokale Tests (MacBook): +cd ai-compliance-sdk && go test ./internal/ucca/... -v -run TestObligationCondition +``` + +**Weitere Tests:** +- `tom_mapper_test.go` — TOM-Mapping Tests +- `v2_loader_test.go` — JSON-Loader für Regulierungs-Dateien diff --git a/docs-src/services/sdk-modules/requirements.md b/docs-src/services/sdk-modules/requirements.md index 345824f..f0821a9 100644 --- a/docs-src/services/sdk-modules/requirements.md +++ b/docs-src/services/sdk-modules/requirements.md @@ -60,6 +60,66 @@ Gibt zusätzlich `legal_context[]` mit RAG-Ergebnissen zurück: } ``` +### RAG-Extraktion: Anforderungen automatisch aus Corpus erstellen + +```http +POST /compliance/extract-requirements-from-rag +``` + +Durchsucht **alle RAG-Collections** parallel nach Prüfaspekten / Audit-Kriterien und legt automatisch Requirement-Einträge in der DB an. + +**Request:** + +```json +{ + "collections": null, + "search_queries": null, + "regulation_codes": ["BSI-TR-03161-1", "GDPR"], + "max_per_query": 20, + "dry_run": true +} +``` + +| Feld | Typ | Standard | Beschreibung | +|------|-----|---------|--------------| +| `collections` | string[]? | alle | RAG-Collections durchsuchen (`bp_compliance_ce`, `bp_compliance_recht`, ...) | +| `search_queries` | string[]? | 5 Standard-Queries | Suchbegriffe (MUSS/SOLL-Prüfaspekte etc.) | +| `regulation_codes` | string[]? | alle | Nur bestimmte Regulierungen einschließen | +| `max_per_query` | int | 20 | `top_k` pro Suchquery | +| `dry_run` | bool | false | `true` = Vorschau ohne DB-Schreibzugriff | + +**Response:** + +```json +{ + "created": 47, + "skipped_duplicates": 12, + "skipped_no_article": 3, + "failed": 0, + "collections_searched": ["bp_compliance_ce", "bp_compliance_recht"], + "queries_used": ["Prüfaspekt Anforderung MUSS SOLL", "..."], + "dry_run": false, + "message": "Erstellt: 47, Duplikate übersprungen: 12, ...", + "requirements": [ + { + "regulation_code": "BSI-TR-03161-1", + "article": "M.Zugriffsschutz_01", + "title": "Implementierung einer Zugangskontrolle", + "requirement_text": "...", + "source_url": "...", + "score": 0.91, + "action": "created" + } + ] +} +``` + +**Deduplication:** Bereits vorhandene `(regulation_code, article)` Kombinationen werden übersprungen — sicheres Mehrfachaufrufen. + +**Auto-Regulation-Stubs:** Für unbekannte Regulierungscodes werden automatisch Regulation-Stubs angelegt. + +--- + ### Request-Beispiel (POST) ```json diff --git a/docs-src/services/sdk-modules/vorbereitung-module.md b/docs-src/services/sdk-modules/vorbereitung-module.md index 3f4dd1d..2996fc8 100644 --- a/docs-src/services/sdk-modules/vorbereitung-module.md +++ b/docs-src/services/sdk-modules/vorbereitung-module.md @@ -246,23 +246,38 @@ Frontend /api/sdk/v1/ucca/** Proxy-Datei: `admin-compliance/app/api/sdk/v1/ucca/[[...path]]/route.ts` +--- + +## Obligations v2 — Regulierungsübergreifende Pflichten-Datenbank + +> **Detailseite:** [Obligations Framework v2 (CP-OBL)](obligations.md) + +Das Obligations Framework v2 erweitert UCCA um eine **JSON-basierte Pflichten-Datenbank** mit Condition Engine. + +| Kenngröße | Wert | +|-----------|------| +| Regulierungen | 9 (DSGVO, BDSG, AI Act, NIS2, TTDSG, DSA, Data Act, DORA, EU Machinery) | +| Pflichten | 325 | +| TOM-Controls | 180 | + +### Neue Endpoints (v2) + +| Methode | Pfad | Beschreibung | +|---------|------|--------------| +| `POST` | `/sdk/v1/ucca/obligations/assess` | Pflichten aus UnifiedFacts ableiten | +| `POST` | `/sdk/v1/ucca/obligations/quick-check` | Schnellprüfung ohne Persistenz | +| `POST` | `/sdk/v1/ucca/obligations/assess-from-scope` | Assessment aus Scope-Daten | +| `POST` | `/sdk/v1/ucca/obligations/gap-analysis` | TOM-Gap-Analyse | +| `GET` | `/sdk/v1/ucca/obligations/tom-controls/for-obligation/:id` | TOMs für eine Pflicht | +| `GET` | `/sdk/v1/ucca/obligations/regulations` | Alle Regulierungen | + +--- + ### Tests -8 Go-Test-Dateien in `ai-compliance-sdk/internal/ucca/`: - -``` -handlers_test.go -policy_engine_test.go -dsgvo_module_test.go -ai_act_module_test.go -nis2_module_test.go -escalation_test.go -assessment_test.go -feasibility_test.go -``` - -Ausführen auf Mac Mini: +Go-Tests (lokal auf MacBook, **nicht** im laufenden Container): ```bash -ssh macmini "/usr/local/bin/docker exec bp-compliance-ai-sdk go test ./internal/ucca/... -v" +cd ai-compliance-sdk && go test ./internal/ucca/... -v +cd ai-compliance-sdk && go test ./internal/api/handlers/... -v -run TestReporting ``` diff --git a/mkdocs.yml b/mkdocs.yml index 93ef53f..d04dfd4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -90,6 +90,7 @@ nav: - DSB Portal: services/sdk-modules/dsb-portal.md - Industry Compliance Ingestion: services/sdk-modules/industry-compliance-ingestion.md - IACE (CE-Risikobeurteilung): services/sdk-modules/iace.md + - Obligations v2 (CP-OBL): services/sdk-modules/obligations.md - Entwicklung: - Testing: development/testing.md - Dokumentation: development/documentation.md