breakpilot-compliance/docs-src/services/sdk-modules/obligations.md

# 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

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