# 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 |