# Auftrag: Use-Case Compiler — MCs in interaktive Prüfungen verwandeln

**Priorität:** HOCH — nächster großer Baustein nach MC Quality Overhaul
**Repos:** breakpilot-compliance (Hauptarbeit) + breakpilot-core (MC-Daten)
**Voraussetzung:** 13.588 Master Controls in DB (lokal + Production), Gap-Engine funktioniert

---

## Bestehende Use Cases (WICHTIG — darauf aufbauen!)

Wir haben bereits 3 Use Cases gebaut, jeder mit anderem Ansatz:

### 1. IACE CE-Compliance (`/sdk/iace`)
- **Ansatz:** Deterministisch, kein LLM
- **Technologie:** Tag-basiertes Pattern Matching (Go), 1.114 Hazard Patterns, 476 Maßnahmen
- **Flow:** Narrative Text → Parser → Tags → PatternEngine → Hazards → Mitigations → Tech-File
- **Pfad:** `ai-compliance-sdk/internal/iace/`
- **Learnings:** Pattern Matching skaliert und ist reproduzierbar. Kein LLM nötig für strukturierte Domänen.

### 2. Doc-Check Agent (`/sdk/agent`)
- **Ansatz:** LLM-gesteuert (ZeroClaw-artig)
- **Technologie:** LLM mit Tool Calling, RAG-Suche, binäre Prüffragen
- **Flow:** Dokument hochladen → LLM prüft gegen Controls → pass/fail pro Frage → Report
- **Pfad:** `backend-compliance/compliance/api/agent_doc_check_routes.py`
- **Learnings:** LLM kann Dokumente intelligent prüfen, braucht aber klare check_questions um präzise zu sein.

### 3. Gap-Analyse (`/sdk/gap-analysis`)
- **Ansatz:** Regelbasiert, kein LLM
- **Technologie:** Go Classifier + SQL-Queries gegen MCs + Priority Engine
- **Flow:** Produkt-Profil → Regulatory Classification → MC-Filter → IST-Zustand Assessment → Prioritätsliste
- **Pfad:** `ai-compliance-sdk/internal/gap/`
- **Learnings:** IST-Zustand (Normen, Zertifizierungen, Prozesse) reduziert Gaps massiv. Ohne IST = 500 Gaps, mit IST = 308.

### Was der Use-Case Compiler davon übernimmt

| Von | Übernehmen |
|-----|-----------|
| **IACE** | Deterministisches Pattern Matching für strukturierte Fragen, Completeness Gates als Vorlage |
| **Doc-Check Agent** | LLM-basierte Verifikation für unstrukturierte Fragen, Tool Calling Pattern |
| **Gap-Analyse** | MC-Filtering nach Regulation + Scope, IST-Zustand Assessment, Priority Engine |
| **Alle drei** | Das generische Frontend-Pattern (Wizard → Fragebogen → Result) |

### Der Compiler ist die GENERALISIERUNG

IACE funktioniert nur für CE/Maschinen. Doc-Check nur für Dokumente. Gap-Analyse zeigt Gaps aber keine konkreten Fragen. Der Use-Case Compiler kombiniert alle drei Ansätze in einem generischen System das JEDEN Use Case bedienen kann:

```
IACE (deterministisch)     + Doc-Check (LLM)        + Gap-Analyse (regelbasiert)
         ↓                          ↓                         ↓
    Pattern Matching          LLM-Verifikation          MC-Filtering + IST
         ↓                          ↓                         ↓
         └──────────── Use-Case Compiler ──────────────────────┘
                              ↓
              Generischer Fragebogen für JEDEN Use Case
```

---

## Problem

Die 13.588 MCs sind eine Wissensbasis, aber kein Produkt. Wenn ein Nutzer "Vendor Check" machen will, bekommt er 4.036 Controls — aber keine konkreten Fragen, keinen Fragebogen, keine Nachweissammlung.

## Ziel

Ein **Use-Case Compiler** der aus MCs automatisch interaktive Prüfungen generiert:

```
Use Case (z.B. "Vendor Check Cloud-Anbieter")
  → Relevante MCs filtern
  → Pro MC: 1-3 binäre Prüffragen ableiten
  → Fragebogen generieren (sortiert, gruppiert)
  → Nutzer beantwortet + lädt Nachweise hoch
  → Compliance-Score + Gap-Report
  → Fehlende Rechtsquellen automatisch identifizieren
```

## Was bereits existiert (WIEDERVERWENDEN!)

### Master Controls (Core DB)
```sql
-- 13.588 MCs mit 83.073 Members
SELECT mc.canonical_name, mc.total_controls, mc.phases_covered
FROM compliance.master_controls mc;

-- Members mit Regulation Source
SELECT cc.control_id, cc.title, cc.objective, mcm.phase, mcm.action,
       pc.source_citation::jsonb->>'source' as regulation
FROM compliance.master_control_members mcm
JOIN compliance.canonical_controls cc ON cc.id = mcm.control_uuid
LEFT JOIN compliance.canonical_controls pc ON pc.id = cc.parent_control_uuid;
```

### doc_check_controls (1.874 Controls mit check_question)
```sql
-- Bereits existierende binäre Prüffragen
SELECT doc_type, control_id, check_question, pass_criteria, fail_criteria, severity
FROM compliance.doc_check_controls WHERE doc_type = 'dse';
```
→ Das ist das TEMPLATE: Für jeden Use Case brauchen wir das Gleiche.

### Gap-Engine (Compliance SDK)
- `internal/gap/` — Product Profile, Classifier, Priority Engine
- `internal/gap/gap_engine.go` — assessGapStatus mit IST-Zustand
- `internal/gap/norm_mapping.go` — 20 Normen → MC-Topic Mapping
- API: `POST /sdk/v1/gap/analyze`

### IACE Pattern Engine
- Tag-basiertes Pattern Matching → domain-agnostisch
- `PatternEngine.Match(input)` → requirements
- Completeness Gates (25 Prüfpunkte)

### ZeroClaw Agent
- `backend-compliance/compliance/api/agent_doc_check_routes.py` — Doc-Check Agent
- LLM-basierte Verifikation mit Tool Calling
- `ai-compliance-sdk/internal/llm/` — Ollama/Claude Adapter

### Tenant Document Upload (Core RAG)
- `rag-service/api/tenant_documents.py` — tenant-isolierter Upload
- Funktioniert auf Mac Mini

---

## Architektur

### Neue Dateien (Go, im Compliance-Repo)

```
ai-compliance-sdk/internal/usecase/
├── models.go              — UseCaseTemplate, Question, Evidence, ComplianceResult
├── compiler.go            — MC → Fragen kompilieren
├── question_generator.go  — Aus MC + Controls Prüffragen ableiten
├── scoring.go             — Antworten → Compliance-Score
├── gap_detector.go        — Fehlende Rechtsquellen identifizieren
├── store.go               — DB CRUD (Audits, Antworten, Evidence)
└── templates.go           — Vordefinierte Use-Case Templates
```

```
ai-compliance-sdk/internal/api/handlers/
└── usecase_handler.go     — API Endpoints
```

```
ai-compliance-sdk/migrations/
└── 026_usecase_audits.sql  — Tabellen für Audits + Antworten
```

### Frontend (Next.js, im Compliance-Repo)

```
admin-compliance/app/sdk/use-case-audit/
├── page.tsx               — Use Case auswählen oder erstellen
├── [auditId]/
│   └── page.tsx           — Fragebogen ausfüllen + Ergebnis
└── _components/
    ├── UseCaseSelector.tsx — Template-Auswahl oder Custom
    ├── QuestionnaireView.tsx — Dynamischer Fragebogen
    └── AuditResult.tsx    — Score + Gaps + Report
```

---

## Datenmodell

### UseCaseTemplate
```go
type UseCaseTemplate struct {
    ID          string   // "vendor_check", "sast_dast_audit", "dsgvo_quick_check"
    Name        string   // "Vendor Check (Cloud-Anbieter)"
    Description string
    MCFilters   []string // ["third_party_management_*", "data_processing_agreement_*"]
    Regulations []string // ["dsgvo", "nis2"] — welche Regulierungen relevant
    Questions   []Question // vorgenerierte Fragen (oder leer → LLM generiert)
}
```

### Question (kompiliert aus MC)
```go
type Question struct {
    ID              string   // "Q1"
    MCID            string   // "MC-19012"
    MCName          string   // "third_party_management_vendor_assessment"
    Question        string   // "Hat der Anbieter ISO 27001?"
    QuestionType    string   // "yes_no", "file_upload", "text", "multi_select"
    EvidenceRequired bool   // true → Nutzer muss Nachweis hochladen
    PassCriteria    []string // ["Gültiges ISO 27001 Zertifikat vorhanden"]
    FailCriteria    []string // ["Kein Zertifikat, nur Selbstauskunft"]
    Severity        string   // "HIGH", "MEDIUM", "LOW"
    Regulation      string   // "DSGVO Art. 28"
    DependsOn       string   // "Q3" → nur anzeigen wenn Q3 = "Ja"
}
```

### Audit (laufende Prüfung)
```sql
CREATE TABLE compliance.usecase_audits (
    id UUID PRIMARY KEY,
    tenant_id UUID NOT NULL,
    template_id VARCHAR(100) NOT NULL,
    name VARCHAR(200) NOT NULL,        -- "Vendor Check: AWS"
    target_name VARCHAR(200),          -- "Amazon Web Services"
    status VARCHAR(20) DEFAULT 'draft', -- draft, in_progress, completed
    total_questions INT DEFAULT 0,
    answered_questions INT DEFAULT 0,
    compliance_score FLOAT DEFAULT 0,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    completed_at TIMESTAMPTZ
);

CREATE TABLE compliance.usecase_answers (
    id UUID PRIMARY KEY,
    audit_id UUID REFERENCES usecase_audits(id),
    question_id VARCHAR(50) NOT NULL,
    mc_id VARCHAR(50),
    answer JSONB NOT NULL,             -- {"value": true, "comment": "..."}
    evidence_ids JSONB DEFAULT '[]',   -- UUIDs von hochgeladenen Dateien
    status VARCHAR(20) DEFAULT 'answered', -- answered, skipped, escalated
    answered_at TIMESTAMPTZ DEFAULT NOW()
);
```

---

## Use-Case Templates (Erstausstattung)

### 1. Vendor Check (Cloud-Anbieter)
```yaml
id: vendor_check_cloud
mc_filters: ["third_party_management_*", "data_processing_agreement_*", "data_transfer_*"]
regulations: ["dsgvo", "nis2"]
questions:
  - "Hat der Anbieter ISO 27001 oder vergleichbare Zertifizierung?"
  - "Ist ein AVV nach Art. 28 DSGVO geschlossen?"
  - "Werden Daten in Drittländer übermittelt?"
  - "Gibt es SCC oder Angemessenheitsbeschluss?"
  - "Hat der Anbieter ein Schwachstellenmanagement?"
  - "Gibt es einen Incident-Response-Prozess?"
  - "Sind Sub-Auftragsverarbeiter dokumentiert?"
  ...
```

### 2. SAST/DAST Security Audit
```yaml
id: sast_dast_audit
mc_filters: ["secure_development_*", "vulnerability_*", "input_validation_*", "api_security_*"]
regulations: ["cra", "owasp"]
```

### 3. DSGVO Quick-Check
```yaml
id: dsgvo_quick_check
mc_filters: ["personal_data_*", "consent_*", "data_subject_rights_*", "dpia_*", "data_retention_*"]
regulations: ["dsgvo"]
```

### 4. NIS2 Readiness
```yaml
id: nis2_readiness
mc_filters: ["critical_infrastructure_*", "incident_*", "network_security_*", "risk_management_*"]
regulations: ["nis2"]
```

### 5. CRA Product Check
```yaml
id: cra_product_check
mc_filters: ["vulnerability_*", "patch_management_*", "encryption_*", "asset_management_inventory*"]
regulations: ["cra"]
```

---

## Lücken-Erkennung

### Automatische Identifikation fehlender Rechtsquellen

```go
func (d *GapDetector) DetectMissingRegulations(templateID string) []MissingSource {
    // 1. Lade alle MCs für diesen Use Case
    // 2. Für jeden MC: zähle Controls mit source_citation
    // 3. Wenn MC >20 Controls aber <3 mit Source → LÜCKE
    // 4. Wenn MC-Topic eine bekannte Regulation hat die nicht 
    //    in source_citation vorkommt → FEHLENDE QUELLE
    //
    // Beispiel:
    //   MC "aml_transaction_monitoring" → 18 Controls
    //   Source Citations: nur "Geldwäschegesetz (GwG)"
    //   FEHLEND: "5. Geldwäscherichtlinie (EU) 2024/1624"
    //   → Ingestion-Auftrag: EUR-Lex CELEX:32024L1624
}
```

### Output: Ingestion-Aufträge
```json
{
  "missing_sources": [
    {
      "regulation": "5. Geldwäscherichtlinie (EU) 2024/1624",
      "affects_mcs": ["aml_transaction_monitoring", "aml_customer_due_diligence"],
      "estimated_controls": 50,
      "source_url": "https://eur-lex.europa.eu/legal-content/DE/TXT/?uri=CELEX:32024L1624",
      "priority": "high"
    }
  ]
}
```

---

## API Endpoints

```
POST   /sdk/v1/use-case/templates           — Neues Template erstellen
GET    /sdk/v1/use-case/templates           — Verfügbare Templates
GET    /sdk/v1/use-case/templates/:id       — Template Detail + Fragen
POST   /sdk/v1/use-case/compile             — MC → Fragen kompilieren (ad-hoc)
POST   /sdk/v1/use-case/audits              — Neuen Audit starten
GET    /sdk/v1/use-case/audits              — Meine Audits
GET    /sdk/v1/use-case/audits/:id          — Audit Detail + Antworten
POST   /sdk/v1/use-case/audits/:id/answer   — Frage beantworten
GET    /sdk/v1/use-case/audits/:id/score    — Compliance-Score berechnen
GET    /sdk/v1/use-case/audits/:id/report   — Gap-Report generieren
GET    /sdk/v1/use-case/audits/:id/gaps     — Fehlende Rechtsquellen
```

---

## Fragen-Generierung (2 Modi)

### Modus A: Deterministisch (kein LLM nötig)
Für MCs die bereits doc_check_controls haben → direkt `check_question` nutzen.
Für MCs mit `scanner_hint` → in Prüffrage umwandeln (Regex/Template).

### Modus B: LLM-basiert (für neue Use Cases)
Wenn kein check_question existiert → Haiku/Qwen generiert aus MC-Title + Objective:
```
Input:  MC "third_party_management_vendor_assessment", 
        Title: "Cybersicherheitsrichtlinien kritischer Lieferanten prüfen"
Output: {
  "question": "Hat der Lieferant formalisierte Cybersicherheitsrichtlinien?",
  "pass_criteria": ["Dokumentierte Security Policy vorhanden", "Letzte Aktualisierung < 12 Monate"],
  "fail_criteria": ["Keine dokumentierte Policy", "Policy älter als 2 Jahre"]
}
```

Kosten: ~$0.001/Frage mit Haiku → $0.05 für 50 Fragen pro Template.

---

## Implementierungs-Reihenfolge

| Phase | Was | Aufwand |
|-------|-----|--------|
| 1 | Datenmodell + Store + Migration | 1h |
| 2 | Compiler (MC → Fragen) + Templates (5 Stück) | 2h |
| 3 | API Endpoints (8 Stück) | 1.5h |
| 4 | Frontend: Template-Auswahl + Fragebogen | 2h |
| 5 | Scoring Engine + Report | 1h |
| 6 | Lücken-Erkennung | 1h |
| 7 | LLM-basierte Fragen-Generierung | 1h |
| **Gesamt** | | **~10h (2 Sessions)** |

---

## Verifikation

Test-Szenario: Vendor Check für AWS

1. Template "vendor_check_cloud" auswählen
2. System generiert 25 Fragen aus MCs
3. Nutzer beantwortet alle Fragen + lädt AVV hoch
4. Score: 85% (3 Gaps: SCC fehlt, Sub-Processor-Liste unvollständig, Löschkonzept fehlt)
5. Report als PDF exportieren
6. Lücken-Erkennung: "Für NIS2 Supply Chain fehlen Controls aus ENISA Guidelines"

---

## Verbindung zur bestehenden Infrastruktur

| Bestehend | Nutzt der Compiler für |
|-----------|----------------------|
| Master Controls (13.588) | MC → Fragen Mapping |
| doc_check_controls (1.874) | Fertige Prüffragen (DSE, Cookie, etc.) |
| Gap-Engine | IST-Zustand Assessment + Priority |
| IACE Pattern Engine | CE-spezifische Prüfungen |
| Applicability Engine | Scope-Filter (Branche, Größe, Signale) |
| RAG Service | Kontext für LLM-Fragen-Generierung |
| Tenant Document Upload | Evidence-Speicherung |
| ZeroClaw Agent | LLM-basierte Verifikation |
| DSMS/IPFS | Revisionssichere Archivierung |

---

## DB-Zugang

```bash
# Lokal (Mac Mini)
ssh macmini "/usr/local/bin/docker exec bp-core-postgres psql -U breakpilot -d breakpilot_db"

# Production
PROD_DB="postgresql://postgres:GmyFD3wnU1NrKBdpU1nwLdE8MLts0A0eez8L5XXdvUCe05lWnWfVp3C6JJ8Yrmt2@46.225.100.82:54321/postgres?sslmode=require"
```