breakpilot-compliance/docs-src/services/sdk-modules/vorbereitung-module.md

# Vorbereitung-Module (Paket 1)

Die drei Vorbereitung-Module bilden die Grundlage des SDK-Workflows. Sie erfassen das Unternehmensprofil, bestimmen den passenden Compliance-Umfang und bewerten konkrete KI/Daten-Anwendungsfälle.

| Modul | Code | Route | Backend |
|-------|------|-------|---------|
| **Company Profile** | CP-PROF | `/sdk/company-profile` | FastAPI `backend-compliance` |
| **Compliance Scope** | CP-SCOPE | `/sdk/compliance-scope` | FastAPI `backend-compliance` |
| **Use-Case Assessment** | CP-UC | `/sdk/use-cases` | Go `ai-compliance-sdk` |

---

## Profil — company-profile (CP-PROF)

### Übersicht

8-Schritt-Wizard (+ Summary-Step 99) zur Erfassung des vollständigen Unternehmensprofils. Speichert hybrid in `localStorage` (Draft) und der DB (Endstand). Nach Abschluss zeigt Step 99 eine Summary-Seite mit Vollstaendigkeitspruefung und "Weiter zu Scope"-Button.

### API-Endpunkte

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/v1/company-profile` | Profil für Tenant laden |
| `POST` | `/v1/company-profile` | Profil erstellen oder aktualisieren (Upsert) |
| `PATCH` | `/v1/company-profile` | Einzelne Felder aktualisieren |
| `DELETE` | `/v1/company-profile` | Profil löschen (Art. 17 DSGVO) |
| `GET` | `/v1/company-profile/audit` | Audit-Log der Profiländerungen |

### Datenbankstruktur

**Tabelle:** `compliance_company_profiles` (Migration 005)

28 Felder, u.a.:

```sql
id              UUID PRIMARY KEY
tenant_id       TEXT UNIQUE NOT NULL
company_name    TEXT
legal_form      TEXT  -- GmbH, AG, GbR, ...
industry        TEXT  -- tech, finance, healthcare, public, retail, education
company_size    TEXT  -- micro, small, medium, large
employee_count  TEXT  -- 1-9, 10-49, 50-249, 250-999, 1000+
uses_ai         BOOLEAN
ai_use_cases    JSONB
dpo_name        TEXT
machine_builder JSONB  -- IACE-Profil für Maschinenbauer
is_complete     BOOLEAN
completed_at    TIMESTAMPTZ
```

**Audit-Tabelle:** `compliance_company_profile_audit`

```sql
id              UUID PRIMARY KEY
tenant_id       TEXT
action          TEXT  -- create | update | delete
changed_fields  JSONB
changed_by      TEXT
created_at      TIMESTAMPTZ
```

### Request-Modell (CompanyProfileRequest)

```json
{
  "company_name": "Beispiel GmbH",
  "legal_form": "GmbH",
  "industry": "tech",
  "founded_year": 2018,
  "business_model": "B2B",
  "company_size": "small",
  "employee_count": "10-49",
  "annual_revenue": "2-10 Mio",
  "headquarters_country": "DE",
  "uses_ai": true,
  "ai_use_cases": ["Chatbot", "Dokumentenklassifikation"],
  "is_complete": true
}
```

### Tests

**Datei:** `backend-compliance/tests/test_company_profile_routes.py`

9 Tests — alle grün:

- `test_get_profile_not_found` — 404 wenn kein Profil
- `test_create_profile` — POST legt Profil an
- `test_upsert_profile_update` — POST auf bestehendem Profil → UPDATE
- `test_delete_profile` — DELETE entfernt Profil
- `test_delete_profile_not_found` — 404 bei fehlendem Profil
- `test_get_audit_log_empty` — leeres Audit-Log
- `test_audit_log_after_create` — Audit-Eintrag nach CREATE
- `test_audit_log_after_delete` — Audit-Eintrag nach DELETE
- `test_complete_profile_workflow` — End-to-End Workflow

---

## Scope — compliance-scope (CP-SCOPE)

### Übersicht

4-Tab-Oberfläche zur Bestimmung des optimalen Compliance-Levels (L1–L4):

| Tab | Inhalt |
|-----|--------|
| **Overview** | Aktueller Level, Score-Visualisierung, Dokumenten-Anforderungen |
| **Wizard** | 35 Fragen in 6 Blöcken (ca. 10–15 min) |
| **Entscheidung** | Begründung, Hard Triggers, Gap-Analyse |
| **Export** | JSON/PDF-Export der Scope-Entscheidung |

### ComplianceScopeEngine

Die Engine (`lib/sdk/compliance-scope-engine.ts`) implementiert eine 8-Schritt-Pipeline:

```
1. calculateScores(answers)        → ComplianceScores
2. evaluateHardTriggers(answers)   → TriggeredHardTrigger[]
3. determineLevel(scores, triggers) → ComplianceDepthLevel
4. buildDocumentScope(level, ...)  → RequiredDocument[]
5. evaluateRiskFlags(answers, level) → RiskFlag[]
6. calculateGaps(answers, level)   → ScopeGap[]
7. buildNextActions(docs, gaps)    → NextAction[]
8. buildReasoning(...)             → ScopeReasoning[]
```

### Level-Modell

| Level | Composite-Score | Bezeichnung |
|-------|----------------|-------------|
| **L1** | ≤ 25 | Lean Startup — Minimalansatz |
| **L2** | 26–50 | KMU Standard |
| **L3** | 51–75 | Erweitert |
| **L4** | > 75 | Zertifizierungsbereit |

Finale Stufe = `max(score-basiertes Level, höchstes Hard-Trigger-Level)`

### Score-Gewichte

```
Composite = Risk × 0.4 + Complexity × 0.3 + Assurance × 0.3
```

Scores werden aus 35 gewichteten Fragen berechnet. Jede Frage hat individuelle Gewichte für `risk`, `complexity`, `assurance` (definiert in `QUESTION_SCORE_WEIGHTS`).

### Hard Trigger Kategorien (50 Regeln)

| Kategorie | Regeln | Beispiel-Trigger |
|-----------|--------|-----------------|
| `art9` | 9 | Gesundheits-, Biometrie-, Genetikdaten → mind. L3 |
| `vulnerable` | 3 | Minderjährige → L3/L4 + DSFA |
| `adm` | 6 | Autonome KI, Profiling, Scoring → L2/L3 |
| `surveillance` | 5 | Videoüberwachung, Mitarbeitermonitoring → L2/L3 |
| `third_country` | 5 | Drittland-Transfer → L2/L3 |
| `certification` | 5 | ISO 27001, SOC2, TISAX → L4 |
| `scale` | 5 | >1Mio Datensätze, >250 Mitarbeiter → L3 |
| `product` | 7 | Webshop, Datenmakler, B2C → L2/L3 |
| `process_maturity` | 5 | Fehlende Prozesse (DSAR, Löschung, Incident) |
| `iace_*` | 5+ | Maschinenbauer: AI Act, CRA, NIS2 |

### API-Endpunkte

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/v1/compliance-scope` | Scope-Zustand laden (`sdk_states` JSONB) |
| `POST` | `/v1/compliance-scope` | Scope-Zustand speichern (JSONB UPSERT) |

Scope-Daten werden in `sdk_states.state->'compliance_scope'` als JSONB gespeichert.

### Tests

**Datei:** `backend-compliance/tests/test_compliance_scope_routes.py` — 27 Tests

**Datei:** `admin-compliance/lib/sdk/__tests__/compliance-scope-engine.test.ts` — 40 Vitest-Tests

Engine-Tests decken ab:

- `calculateScores`: Leer-Array, boolean/numeric/array Antworten, Composite-Gewichtung
- `determineLevel`: L1–L4 Schwellenwerte, Hard-Trigger-Override, Level-Maximum
- `evaluateHardTriggers`: Art. 9, Minderjährige, KI-Scoring, mehrere Trigger
- `evaluate` (Integration): Vollständige ScopeDecision, Felder vorhanden, Level-Bestimmung
- `buildDocumentScope`: Array-Rückgabe, Dokumentstruktur, Sortierung
- `evaluateRiskFlags`: Verschlüsselung, Drittland, DPO-Pflicht

---

## Anwendung — use-case-assessment / UCCA (CP-UC)

### Übersicht

Bewertet konkrete Datenanwendungen hinsichtlich DSGVO- und AI-Act-Konformität. Gibt eine **Machbarkeitsentscheidung** (Feasibility) und detaillierte Befunde zurück.

| Ansicht | Inhalt |
|---------|--------|
| **Liste** | Alle Assessments mit Filter, Pagination, RiskScoreGauge |
| **Detail** | Vollständiger Befund-Report mit Kategorien, Controls |
| **Neu** | 8-Schritte-Wizard mit Kachel-Auswahl (Details siehe unten) |

### Wizard-Schritte (Neuer Use Case)

| Schritt | Titel | Auswahl-Typ | Details |
|---------|-------|-------------|---------|
| 1 | Grundlegendes | Titel + Text + Single-Select-Kacheln | 21 KI-Anwendungskategorien, Branche automatisch aus Profil |
| 2 | Datenkategorien | Multi-Select-Kacheln (gruppiert) | ~60 Kategorien in 10 Gruppen, Art. 9 orange hervorgehoben |
| 3 | Verarbeitungszweck | Multi-Select-Kacheln | 16 Zwecke, Rechtsgrundlage wird vom SDK automatisch ermittelt |
| 4 | Automatisierung | Single-Select-Kacheln | assistiv / teilautomatisiert / vollautomatisiert |
| 5 | Hosting & Modell | Single + Multi-Select-Kacheln | 6 Provider, 4 Regionen, 4 Modellnutzungsarten |
| 6 | Datentransfer | Multi + Single-Select-Kacheln | 6 Transferziele, 5 Mechanismen (bedingt sichtbar) |
| 7 | Datenhaltung | Single-Select-Kacheln | 8 Aufbewahrungsfristen, optionaler Zweck |
| 8 | Vertraege | Multi-Select-Kacheln | 8 Compliance-Dokumente |

**Wichtig:** Die Rechtsgrundlage (Art. 6 DSGVO) wird nicht mehr vom Nutzer ausgewaehlt, sondern automatisch vom SDK ermittelt.

### Feasibility-Werte

| Wert | Bedeutung |
|------|-----------|
| `YES` | Umsetzung ohne Einschränkungen empfohlen |
| `CONDITIONAL` | Umsetzung nur mit spezifischen Maßnahmen |
| `NO` | Umsetzung nicht empfohlen (unakzeptables Risiko) |

### Risiko-Level

| Level | Score-Bereich |
|-------|--------------|
| `MINIMAL` | 0–20 |
| `LOW` | 21–40 |
| `MEDIUM` | 41–60 |
| `HIGH` | 61–80 |
| `UNACCEPTABLE` | 81–100 |

### Backend: ai-compliance-sdk (Go)

**Service:** `bp-compliance-ai-sdk` (Port 8090 intern, 8093 extern)

Relevante Module in `internal/ucca/`:

| Datei | Funktion |
|-------|---------|
| `policy_engine.go` | Zentrale Regelauswertung |
| `dsgvo_module.go` | DSGVO-spezifische Prüfungen (Art. 5–9, 22, 35) |
| `ai_act_module.go` | AI-Act Risikokategorisierung |
| `nis2_module.go` | NIS2-Anforderungen |
| `escalation.go` | Eskalationslogik bei Hochrisiko |
| `handlers.go` | HTTP Handler (Gin) |

**Datenbanktabellen:**

```sql
ucca_assessments  -- Assessments (tenant_id, title, description, status, feasibility, risk_level)
ucca_findings     -- Einzelbefunde pro Assessment
ucca_controls     -- Empfohlene Maßnahmen
```

### Proxy

```
Frontend  /api/sdk/v1/ucca/**
    → ai-compliance-sdk:8090/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

Go-Tests (lokal auf MacBook, **nicht** im laufenden Container):

```bash
cd ai-compliance-sdk && go test ./internal/ucca/... -v
cd ai-compliance-sdk && go test ./internal/api/handlers/... -v -run TestReporting
```