Benjamin_Boenisch/breakpilot-compliance
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
db7c207464bc8222874f86e68fb0eb35de77cdc7
breakpilot-compliance/docs-src/services/sdk-modules/obligations.md
Benjamin Admin c3afa628ed feat(sdk): vendor-compliance cross-module integration — VVT, obligations, TOM, loeschfristen 
Integrate the vendor-compliance module with four DSGVO modules to eliminate
data silos and resolve the VVT processor tab's ephemeral state problem.

- Reposition vendor-compliance sidebar from seq 4200 to 2500 (after VVT)
- VVT: replace ephemeral ProcessorRecord state with Vendor-API fetch (read-only)
- Obligations: add linked_vendor_ids (JSONB) + compliance check #12 MISSING_VENDOR_LINK
- TOM: add vendor TOM-controls cross-reference table in overview tab
- Loeschfristen: add linked_vendor_ids (JSONB) + vendor picker + document section
- Migrations: 069_obligations_vendor_link.sql, 070_loeschfristen_vendor_link.sql
- Tests: 12 new backend tests (125 total pass)
- Docs: update obligations.md + vendors.md with cross-module integration

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-19 13:59:43 +01:00

421 lines
14 KiB
Markdown
Raw Blame History

# 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 & Scope-Assessment
| 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"]
}
]
}
```
---
## Automatische Regulierungs-Ableitung
Seit v2 kann das Obligations-Framework anwendbare Regulierungen und Aufsichtsbehörden direkt aus dem Scope-Profiling ableiten.
### Datenfluss
```
CompanyProfile + ScopeProfilingAnswers
│
▼
scope-to-facts.ts ← Konvertiert Profil + Scope-Antworten in ScopeDecisionPayload
│
▼
POST /assess-from-scope ← Go AI SDK bewertet Payload gegen Condition Engine
│
▼
ApplicableRegulations ← Liste anwendbarer Gesetze (DSGVO, AI Act, NIS2, etc.)
+
supervisory-authority- ← Zuständige Aufsichtsbehörden (LfDI, BSI, BaFin, BNetzA)
resolver.ts
```
### Neue Dateien
| Datei | Beschreibung |
|-------|--------------|
| `admin-compliance/lib/sdk/scope-to-facts.ts` | Mapper: CompanyProfile + ScopeAnswers → `ScopeDecisionPayload` für Go SDK |
| `admin-compliance/lib/sdk/supervisory-authority-resolver.ts` | Ermittelt Aufsichtsbehörden aus Bundesland/Land + Regulierungen |
### scope-to-facts.ts
Exportierte Funktionen:
- `buildAssessmentPayload(profile, scopeAnswers, decision)` → `ScopeDecisionPayload`
- `parseEmployeeRange(range)` → Mittelwert als Zahl (z.B. "50-249" → 150)
- `parseRevenueRange(range)` → Umsatz als Zahl (z.B. "10-50 Mio" → 30.000.000)
### supervisory-authority-resolver.ts
Exportierte Funktion:
- `resolveAuthorities(state, country, regulationIds)` → `SupervisoryAuthorityResult[]`
Abgedeckte Regulierungen → Behörden:
| Regulierung | Behörde (DE) | Behörde (Andere) |
|-------------|-------------|-----------------|
| `dsgvo` | Landes-Datenschutzbehörde (16 Bundesländer) | Nationale DSB (AT, CH, FR, NL, etc.) |
| `nis2` | BSI | NCSA |
| `financial_policy` | BaFin | — |
| `ai_act` | BNetzA | — |
---
## 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 — 5-Tab-Aufbau
**URL:** `https://macmini:3007/sdk/obligations`
Die Obligations-Seite ist in 5 Tabs gegliedert:
| Tab | Inhalt |
|-----|--------|
| **Uebersicht** | Statistik-Kacheln, Compliance-Score, Regulierungs-Filter, Pflichten-Liste (Cards), Compliance-Befunde |
| **Detail-Editor** | Pflichtenliste mit Bearbeitungsfunktion, Status-/Prioritaets-Badges |
| **Profiling** | Auto-Profiling aus CompanyProfile + Compliance-Scope, anwendbare Regulierungen |
| **Gap-Analyse** | GapAnalysisView + TOMControlPanel (UCCA-Integration) |
| **Pflichtenregister** | Druckbares HTML-Dokument (12 Sektionen), Org-Header, Revisionen |
### 12 Compliance-Checks
Der Compliance-Checker (`obligations-compliance.ts`) prueft automatisch:
| # | Check | Severity | Ausloeser |
|---|-------|----------|-----------|
| 1 | `MISSING_RESPONSIBLE` | MEDIUM | Pflicht ohne Verantwortlichen |
| 2 | `OVERDUE_DEADLINE` | HIGH | Frist ueberschritten, Status != completed |
| 3 | `MISSING_EVIDENCE` | HIGH | Abgeschlossene Pflicht ohne Nachweis |
| 4 | `MISSING_DESCRIPTION` | MEDIUM | Pflicht ohne Beschreibung |
| 5 | `NO_LEGAL_REFERENCE` | HIGH | Pflicht ohne Artikel-Referenz |
| 6 | `INCOMPLETE_REGULATION` | HIGH | Regulierung mit allen Pflichten pending/overdue |
| 7 | `HIGH_PRIORITY_NOT_STARTED` | CRITICAL | Critical/High-Pflicht seit >30d pending |
| 8 | `STALE_PENDING` | LOW | Pflicht seit >90d pending |
| 9 | `MISSING_LINKED_SYSTEMS` | MEDIUM | Pflicht ohne Systemzuordnung |
| 10 | `NO_REVIEW_PROCESS` | MEDIUM | Keine Pflicht hat review_date |
| 11 | `CRITICAL_WITHOUT_EVIDENCE` | CRITICAL | Kritische Pflicht ohne Nachweis |
| 12 | `MISSING_VENDOR_LINK` | MEDIUM | Art.-28-Pflicht ohne verknuepften Auftragsverarbeiter |
**Score:** `100 - (CRITICAL*15 + HIGH*10 + MEDIUM*5 + LOW*2)`, min 0.
### Pflichtenregister-Dokument (12 Sektionen)
Das druckbare HTML-Dokument (`obligations-document.ts`) umfasst:
| # | Sektion | Datenquelle |
|---|---------|-------------|
| 0 | Deckblatt | orgHeader |
| — | Inhaltsverzeichnis | statisch |
| 1 | Ziel und Zweck | statisch |
| 2 | Geltungsbereich | orgHeader, obligations (distinct sources) |
| 3 | Methodik | statisch |
| 4 | Regulatorische Grundlagen | obligations gruppiert nach source |
| 5 | Pflichtenuebersicht | obligations nach Status |
| 6 | Detaillierte Pflichten | Pro Regulierung: Detail-Karten |
| 7 | Verantwortlichkeiten | Rollenmatrix |
| 8 | Fristen und Termine | Ueberfaellige + anstehende Deadlines |
| 9 | Nachweisverzeichnis | Evidence pro Pflicht |
| 10 | Compliance-Status | Score + Issues |
| 11 | Aenderungshistorie | Revisionstabelle |
---
## 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
- `backend-compliance/tests/test_obligation_routes.py` — 39 Backend-API-Tests
---
## Cross-Modul-Integration
| Modul | Integration |
|-------|------------|
| **VVT** | Pflichten referenzieren Verarbeitungstaetigkeiten ueber `linked_systems` |
| **TOM** | TOM-Control-Mapping (UCCA) zeigt erforderliche Massnahmen pro Pflicht |
| **Loeschfristen** | Loeschpflichten (Art. 17 DSGVO) im Pflichtenregister referenziert |
| **Vendor Compliance** | Art.-28-Pflichten verknuepfbar mit Auftragsverarbeitern ueber `linked_vendor_ids` (DB: JSONB). Compliance-Check #12 (`MISSING_VENDOR_LINK`) prueft fehlende Verknuepfung. |
| **UCCA** | Condition Engine bewertet Pflichten gegen UnifiedFacts |
| **Compliance-Scope** | Auto-Profiling nutzt Scope-Antworten fuer Regulierungs-Ableitung |
---
## Audit-Faehigkeit
Das Pflichtenregister ist auditfaehig durch:
1. **Druckbares HTML-Dokument** mit 12 Sektionen, A4-Layout, `@media print`
2. **11 automatische Compliance-Checks** mit Score (0-100) und Befunden nach Schweregrad
3. **Nachweisverzeichnis** (Sektion 9) dokumentiert Evidence pro Pflicht
4. **Aenderungshistorie** (Sektion 11) mit Version, Datum, Autor, Beschreibung
5. **Fristen-Tracking** (Sektion 8) mit ueberfaelligen und anstehenden Terminen
---
## Datei-Uebersicht
| Datei | Beschreibung |
|-------|-------------|
| `admin-compliance/app/sdk/obligations/page.tsx` | Haupt-Seite (5-Tab-Layout) |
| `admin-compliance/lib/sdk/obligations-compliance.ts` | 11 Compliance-Checks + Obligation-Type |
| `admin-compliance/lib/sdk/obligations-document.ts` | HTML-Dokument-Generator (12 Sektionen) |
| `admin-compliance/components/sdk/obligations/ObligationDocumentTab.tsx` | Pflichtenregister-Tab-Komponente |
| `admin-compliance/components/sdk/obligations/GapAnalysisView.tsx` | Gap-Analyse-Komponente |
| `admin-compliance/components/sdk/obligations/TOMControlPanel.tsx` | TOM-Control-Panel |
| `backend-compliance/compliance/api/obligation_routes.py` | 7 Backend-API-Endpoints |
| `backend-compliance/migrations/013_obligations.sql` | DB-Schema |
| `ai-compliance-sdk/policies/obligations/v2/` | 325 Pflichten, 9 Regulierungen |
Reference in New Issue View Git Blame Copy Permalink