# AI Compliance SDK - Entwickler-Dokumentation

## Inhaltsverzeichnis

1. [Schnellstart](#1-schnellstart)
2. [Architektur-Übersicht](#2-architektur-übersicht)
3. [Policy Engine](#3-policy-engine)
4. [License Policy Engine](#4-license-policy-engine)
5. [Legal RAG Integration](#5-legal-rag-integration)
6. [Wizard & Legal Assistant](#6-wizard--legal-assistant)
7. [Eskalations-System](#7-eskalations-system)
8. [API-Endpoints](#8-api-endpoints)
9. [Policy-Dateien](#9-policy-dateien)
10. [Tests ausführen](#10-tests-ausführen)

---

## 1. Schnellstart

### Voraussetzungen

- Go 1.21+
- PostgreSQL (für Eskalations-Store)
- Qdrant (für Legal RAG)
- Ollama oder Anthropic API Key (für LLM)

### Build & Run

```bash
# Build
cd ai-compliance-sdk
go build -o server ./cmd/server

# Run
./server --config config.yaml

# Alternativ: mit Docker
docker compose up -d
```

### Erste Anfrage

```bash
# UCCA Assessment erstellen
curl -X POST http://localhost:8080/sdk/v1/ucca/assess \
  -H "Content-Type: application/json" \
  -d '{
    "use_case_text": "Chatbot für Kundenservice mit FAQ-Suche",
    "domain": "utilities",
    "data_types": {
      "personal_data": false,
      "public_data": true
    },
    "automation": "assistive",
    "model_usage": {
      "rag": true
    },
    "hosting": {
      "region": "eu"
    }
  }'
```

---

## 2. Architektur-Übersicht

```
┌─────────────────────────────────────────────────────────────────┐
│                        API Layer (Gin)                           │
│                    internal/api/handlers/                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │   UCCA      │  │   License   │  │      Eskalation         │  │
│  │   Handler   │  │   Handler   │  │      Handler            │  │
│  └──────┬──────┘  └──────┬──────┘  └───────────┬─────────────┘  │
│         │                │                      │                │
├─────────┼────────────────┼──────────────────────┼────────────────┤
│         ▼                ▼                      ▼                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │   Policy    │  │   License   │  │   Escalation            │  │
│  │   Engine    │  │   Policy    │  │   Store                 │  │
│  │             │  │   Engine    │  │                         │  │
│  └──────┬──────┘  └──────┬──────┘  └───────────┬─────────────┘  │
│         │                │                      │                │
│         └────────┬───────┴──────────────────────┘                │
│                  ▼                                               │
│         ┌─────────────────────────────────────────────────┐     │
│         │              Legal RAG System                    │     │
│         │         (Qdrant + LLM Integration)              │     │
│         └─────────────────────────────────────────────────┘     │
│                                                                   │
└─────────────────────────────────────────────────────────────────┘
```

### Kernprinzip

**LLM ist NICHT die Quelle der Wahrheit!**

| Komponente | Entscheidet | LLM-Nutzung |
|------------|-------------|-------------|
| Policy Engine | Feasibility, Risk Level | Nein |
| License Engine | Operation Mode, Stop-Lines | Nein |
| Gap Mapping | Facts → Gaps → Controls | Nein |
| Legal RAG | Erklärung generieren | Ja (nur Output) |

---

## 3. Policy Engine

### Übersicht

Die Policy Engine (`internal/ucca/policy_engine.go`) evaluiert Use Cases gegen deterministische Regeln.

### Verwendung

```go
import "ai-compliance-sdk/internal/ucca"

// Engine erstellen
engine, err := ucca.NewPolicyEngineFromPath("policies/ucca_policy_v1.yaml")
if err != nil {
    log.Fatal(err)
}

// Intake erstellen
intake := &ucca.UseCaseIntake{
    UseCaseText: "Chatbot für Kundenservice",
    Domain:      ucca.DomainUtilities,
    DataTypes: ucca.DataTypes{
        PersonalData: false,
        PublicData:   true,
    },
    Automation: ucca.AutomationAssistive,
    ModelUsage: ucca.ModelUsage{
        RAG: true,
    },
    Hosting: ucca.Hosting{
        Region: "eu",
    },
}

// Evaluieren
result := engine.Evaluate(intake)

// Ergebnis auswerten
fmt.Println("Feasibility:", result.Feasibility)   // YES, NO, CONDITIONAL
fmt.Println("Risk Level:", result.RiskLevel)      // MINIMAL, LOW, MEDIUM, HIGH
fmt.Println("Risk Score:", result.RiskScore)      // 0-100
```

### Ergebnis-Struktur

```go
type EvaluationResult struct {
    Feasibility           Feasibility            // YES, NO, CONDITIONAL
    RiskLevel             RiskLevel              // MINIMAL, LOW, MEDIUM, HIGH
    RiskScore             int                    // 0-100
    TriggeredRules        []TriggeredRule        // Ausgelöste Regeln
    RequiredControls      []Control              // Erforderliche Maßnahmen
    RecommendedArchitecture []Pattern            // Empfohlene Patterns
    DSFARecommended       bool                   // DSFA erforderlich?
    Art22Risk             bool                   // Art. 22 Risiko?
    TrainingAllowed       TrainingAllowed        // YES, NO, CONDITIONAL
    PolicyVersion         string                 // Version der Policy
}
```

### Regeln hinzufügen

Neue Regeln werden in `policies/ucca_policy_v1.yaml` definiert:

```yaml
rules:
  - id: R-CUSTOM-001
    code: R-CUSTOM-001
    category: custom
    title: Custom Rule
    title_de: Benutzerdefinierte Regel
    description: Custom rule description
    severity: WARN  # INFO, WARN, BLOCK
    gdpr_ref: "Art. 6 DSGVO"
    condition:
      all_of:
        - field: domain
          equals: custom_domain
        - field: data_types.personal_data
          equals: true
    controls:
      - C_CUSTOM_CONTROL
```

---

## 4. License Policy Engine

### Übersicht

Die License Policy Engine (`internal/ucca/license_policy.go`) prüft die Lizenz-Compliance für Standards und Normen.

### Operationsmodi

| Modus | Beschreibung | Lizenzanforderung |
|-------|--------------|-------------------|
| `LINK_ONLY` | Nur Verweise | Keine |
| `NOTES_ONLY` | Eigene Notizen | Keine |
| `EXCERPT_ONLY` | Kurzzitate (<150 Zeichen) | Standard-Lizenz |
| `FULLTEXT_RAG` | Volltext-Embedding | Explizite KI-Lizenz |
| `TRAINING` | Modell-Training | Enterprise + Vertrag |

### Verwendung

```go
import "ai-compliance-sdk/internal/ucca"

engine := ucca.NewLicensePolicyEngine()

facts := &ucca.LicensedContentFacts{
    Present:       true,
    Publisher:     "DIN_MEDIA",
    LicenseType:   "SINGLE_WORKSTATION",
    AIUsePermitted: "NO",
    ProofUploaded: false,
    OperationMode: "FULLTEXT_RAG",
}

result := engine.Evaluate(facts)

if !result.Allowed {
    fmt.Println("Blockiert:", result.StopLine.Message)
    fmt.Println("Effektiver Modus:", result.EffectiveMode)
}
```

### Ingest-Entscheidung

```go
// Prüfen ob Volltext-Ingest erlaubt ist
canIngest := engine.CanIngestFulltext(facts)

// Oder detaillierte Entscheidung
decision := engine.DecideIngest(facts)
fmt.Println("Fulltext:", decision.AllowFulltext)
fmt.Println("Notes:", decision.AllowNotes)
fmt.Println("Metadata:", decision.AllowMetadata)
```

### Audit-Logging

```go
// Audit-Entry erstellen
entry := engine.FormatAuditEntry("tenant-123", "doc-456", facts, result)

// Human-readable Summary
summary := engine.FormatHumanReadableSummary(result)
fmt.Println(summary)
```

### Publisher-spezifische Regeln

DIN Media hat explizite Restriktionen:

```go
// DIN Media blockiert FULLTEXT_RAG ohne AI-Lizenz
if facts.Publisher == "DIN_MEDIA" && facts.AIUsePermitted != "YES" {
    // → STOP_DIN_FULLTEXT_AI_NOT_ALLOWED
    // → Downgrade auf LINK_ONLY
}
```

---

## 5. Legal RAG Integration

### Übersicht

Das Legal RAG System (`internal/ucca/legal_rag.go`) generiert Erklärungen mit rechtlichem Kontext.

### Verwendung

```go
import "ai-compliance-sdk/internal/ucca"

rag := ucca.NewLegalRAGService(qdrantClient, llmClient, "bp_legal_corpus")

// Erklärung generieren
explanation, err := rag.Explain(ctx, result, intake)
if err != nil {
    log.Error(err)
}

fmt.Println("Erklärung:", explanation.Text)
fmt.Println("Rechtsquellen:", explanation.Sources)
```

### Rechtsquellen im RAG

| Quelle | Chunks | Beschreibung |
|--------|--------|--------------|
| DSGVO | 128 | EU Datenschutz-Grundverordnung |
| AI Act | 96 | EU AI-Verordnung |
| NIS2 | 128 | Netzwerk-Informationssicherheit |
| SCC | 32 | Standardvertragsklauseln |
| DPF | 714 | Data Privacy Framework |

---

## 6. Wizard & Legal Assistant

### Wizard-Schema

Das Wizard-Schema (`policies/wizard_schema_v1.yaml`) definiert die Fragen für das Frontend.

### Legal Assistant verwenden

```go
// Wizard-Frage an Legal Assistant stellen
type WizardAskRequest struct {
    Question    string                 `json:"question"`
    StepNumber  int                    `json:"step_number"`
    FieldID     string                 `json:"field_id,omitempty"`
    CurrentData map[string]interface{} `json:"current_data,omitempty"`
}

// POST /sdk/v1/ucca/wizard/ask
```

### Beispiel API-Call

```bash
curl -X POST http://localhost:8080/sdk/v1/ucca/wizard/ask \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Was sind personenbezogene Daten?",
    "step_number": 2,
    "field_id": "data_types.personal_data"
  }'
```

---

## 7. Eskalations-System

### Eskalationsstufen

| Level | Auslöser | Prüfer | SLA |
|-------|----------|--------|-----|
| E0 | Nur INFO | Automatisch | - |
| E1 | WARN, geringes Risiko | Team-Lead | 24h |
| E2 | Art. 9, DSFA empfohlen | DSB | 8h |
| E3 | BLOCK, hohes Risiko | DSB + Legal | 4h |

### Eskalation erstellen

```go
import "ai-compliance-sdk/internal/ucca"

store := ucca.NewEscalationStore(db)

escalation := &ucca.Escalation{
    AssessmentID:    "assess-123",
    Level:           ucca.EscalationE2,
    TriggerReason:   "Art. 9 Daten betroffen",
    RequiredReviews: 1,
}

err := store.CreateEscalation(ctx, escalation)
```

### SLA-Monitor

```go
monitor := ucca.NewSLAMonitor(store, notificationService)

// Im Hintergrund starten
go monitor.Start(ctx)
```

---

## 8. API-Endpoints

### UCCA Endpoints

| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| POST | `/sdk/v1/ucca/assess` | Assessment erstellen |
| GET | `/sdk/v1/ucca/assess/:id` | Assessment abrufen |
| POST | `/sdk/v1/ucca/explain` | Erklärung generieren |
| GET | `/sdk/v1/ucca/wizard/schema` | Wizard-Schema abrufen |
| POST | `/sdk/v1/ucca/wizard/ask` | Legal Assistant fragen |

### License Endpoints

| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| POST | `/sdk/v1/license/evaluate` | Lizenz-Prüfung |
| POST | `/sdk/v1/license/decide-ingest` | Ingest-Entscheidung |

### Eskalations-Endpoints

| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/sdk/v1/escalations` | Offene Eskalationen |
| GET | `/sdk/v1/escalations/:id` | Eskalation abrufen |
| POST | `/sdk/v1/escalations/:id/decide` | Entscheidung treffen |

---

## 9. Policy-Dateien

### Dateistruktur

```
policies/
├── ucca_policy_v1.yaml        # Haupt-Policy (Regeln, Controls, Patterns)
├── wizard_schema_v1.yaml      # Wizard-Fragen und Legal Assistant
├── controls_catalog.yaml      # Detaillierte Control-Beschreibungen
├── gap_mapping.yaml           # Facts → Gaps → Controls
├── licensed_content_policy.yaml # Standards/Normen Compliance
└── scc_legal_corpus.yaml      # SCC Rechtsquellen
```

### Policy-Version

Jede Policy hat eine Version:

```yaml
metadata:
  version: "1.0.0"
  effective_date: "2025-01-01"
  author: "Compliance Team"
```

---

## 10. Tests ausführen

### Alle Tests

```bash
cd ai-compliance-sdk
go test -v ./...
```

### Spezifische Tests

```bash
# Policy Engine Tests
go test -v ./internal/ucca/policy_engine_test.go

# License Policy Tests
go test -v ./internal/ucca/license_policy_test.go

# Eskalation Tests
go test -v ./internal/ucca/escalation_test.go
```

### Test-Coverage

```bash
go test -cover ./...

# HTML-Report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out
```

### Beispiel: Neuen Test hinzufügen

```go
func TestMyNewFeature(t *testing.T) {
    engine := NewLicensePolicyEngine()

    facts := &LicensedContentFacts{
        Present:       true,
        Publisher:     "DIN_MEDIA",
        OperationMode: "FULLTEXT_RAG",
    }

    result := engine.Evaluate(facts)

    if result.Allowed {
        t.Error("Expected blocked for DIN_MEDIA FULLTEXT_RAG")
    }
}
```

---

## 11. Generic Obligations Framework

### Übersicht

Das Obligations Framework ermöglicht die automatische Ableitung regulatorischer Pflichten aus NIS2, DSGVO und AI Act.

### Verwendung

```go
import "ai-compliance-sdk/internal/ucca"

// Registry erstellen (lädt alle Module)
registry := ucca.NewObligationsRegistry()

// UnifiedFacts aufbauen
facts := &ucca.UnifiedFacts{
    Organization: ucca.OrganizationFacts{
        EmployeeCount:  150,
        AnnualRevenue:  30000000,
        Country:        "DE",
        EUMember:       true,
    },
    Sector: ucca.SectorFacts{
        PrimarySector:    "digital_infrastructure",
        SpecialServices:  []string{"cloud", "msp"},
        IsKRITIS:         false,
    },
    DataProtection: ucca.DataProtectionFacts{
        ProcessesPersonalData: true,
    },
    AIUsage: ucca.AIUsageFacts{
        UsesAI:             true,
        HighRiskCategories: []string{"employment"},
        IsGPAIProvider:     false,
    },
}

// Alle anwendbaren Pflichten evaluieren
overview := registry.EvaluateAll(facts, "Muster GmbH")

// Ergebnis auswerten
fmt.Println("Anwendbare Regulierungen:", len(overview.ApplicableRegulations))
fmt.Println("Gesamtzahl Pflichten:", len(overview.Obligations))
fmt.Println("Kritische Pflichten:", overview.ExecutiveSummary.CriticalObligations)
```

### Neues Regulierungsmodul erstellen

```go
// 1. Module-Interface implementieren
type MyRegulationModule struct {
    obligations       []ucca.Obligation
    controls          []ucca.ObligationControl
    incidentDeadlines []ucca.IncidentDeadline
}

func (m *MyRegulationModule) ID() string { return "my_regulation" }
func (m *MyRegulationModule) Name() string { return "My Regulation" }

func (m *MyRegulationModule) IsApplicable(facts *ucca.UnifiedFacts) bool {
    // Prüflogik implementieren
    return facts.Organization.Country == "DE"
}

func (m *MyRegulationModule) DeriveObligations(facts *ucca.UnifiedFacts) []ucca.Obligation {
    // Pflichten basierend auf Facts ableiten
    return m.obligations
}

// 2. In Registry registrieren
func NewMyRegulationModule() (*MyRegulationModule, error) {
    m := &MyRegulationModule{}
    // YAML laden oder hardcoded Pflichten definieren
    return m, nil
}

// In obligations_registry.go:
// r.Register(NewMyRegulationModule())
```

### YAML-basierte Pflichten

```yaml
# policies/obligations/my_regulation_obligations.yaml
regulation: my_regulation
name: "My Regulation"

obligations:
  - id: "MYREG-OBL-001"
    title: "Compliance-Pflicht"
    description: "Beschreibung der Pflicht"
    applies_when: "classification != 'nicht_betroffen'"
    legal_basis:
      - norm: "§ 1 MyReg"
    category: "Governance"
    responsible: "Geschäftsführung"
    deadline:
      type: "relative"
      duration: "12 Monate"
    sanctions:
      max_fine: "1 Mio. EUR"
    priority: "high"

controls:
  - id: "MYREG-CTRL-001"
    name: "Kontrollmaßnahme"
    category: "Technical"
    when_applicable: "immer"
    what_to_do: "Maßnahme implementieren"
    evidence_needed:
      - "Dokumentation"
```

### PDF Export

```go
import "ai-compliance-sdk/internal/ucca"

// Exporter erstellen
exporter := ucca.NewPDFExporter("de")

// PDF generieren
response, err := exporter.ExportManagementMemo(overview)
if err != nil {
    log.Fatal(err)
}

// base64-kodierter PDF-Inhalt
fmt.Println("Content-Type:", response.ContentType)  // application/pdf
fmt.Println("Filename:", response.Filename)

// PDF speichern
decoded, _ := base64.StdEncoding.DecodeString(response.Content)
os.WriteFile("memo.pdf", decoded, 0644)

// Alternativ: Markdown
mdResponse, err := exporter.ExportMarkdown(overview)
fmt.Println(mdResponse.Content)  // Markdown-Text
```

### API-Endpoints

```bash
# Assessment erstellen
curl -X POST http://localhost:8090/sdk/v1/ucca/obligations/assess \
  -H "Content-Type: application/json" \
  -d '{
    "facts": {
      "organization": {"employee_count": 150, "country": "DE"},
      "sector": {"primary_sector": "healthcare"},
      "data_protection": {"processes_personal_data": true},
      "ai_usage": {"uses_ai": false}
    },
    "organization_name": "Test GmbH"
  }'

# PDF Export (direkt)
curl -X POST http://localhost:8090/sdk/v1/ucca/obligations/export/direct \
  -H "Content-Type: application/json" \
  -d '{
    "overview": { ... },
    "format": "pdf",
    "language": "de"
  }'
```

---

## 12. Tests für Obligations Framework

```bash
# Alle Obligations-Tests
go test -v ./internal/ucca/..._module_test.go

# NIS2 Module Tests
go test -v ./internal/ucca/nis2_module_test.go

# DSGVO Module Tests
go test -v ./internal/ucca/dsgvo_module_test.go

# AI Act Module Tests
go test -v ./internal/ucca/ai_act_module_test.go

# PDF Export Tests
go test -v ./internal/ucca/pdf_export_test.go
```

### Beispiel-Tests

```go
func TestNIS2Module_LargeCompanyInAnnexISector(t *testing.T) {
    module, _ := ucca.NewNIS2Module()

    facts := &ucca.UnifiedFacts{
        Organization: ucca.OrganizationFacts{
            EmployeeCount: 500,
            AnnualRevenue: 100000000,
            Country:       "DE",
        },
        Sector: ucca.SectorFacts{
            PrimarySector: "energy",
        },
    }

    if !module.IsApplicable(facts) {
        t.Error("Expected NIS2 to apply to large energy company")
    }

    classification := module.Classify(facts)
    if classification != "besonders_wichtige_einrichtung" {
        t.Errorf("Expected 'besonders_wichtige_einrichtung', got '%s'", classification)
    }
}

func TestAIActModule_HighRiskEmploymentAI(t *testing.T) {
    module, _ := ucca.NewAIActModule()

    facts := &ucca.UnifiedFacts{
        AIUsage: ucca.AIUsageFacts{
            UsesAI:             true,
            HighRiskCategories: []string{"employment"},
        },
    }

    if !module.IsApplicable(facts) {
        t.Error("Expected AI Act to apply")
    }

    riskLevel := module.ClassifyRisk(facts)
    if riskLevel != ucca.AIActHighRisk {
        t.Errorf("Expected 'high_risk', got '%s'", riskLevel)
    }
}
```

---

## Anhang: Wichtige Dateien

| Datei | Beschreibung |
|-------|--------------|
| `internal/ucca/policy_engine.go` | Haupt-Policy-Engine |
| `internal/ucca/license_policy.go` | License Policy Engine |
| `internal/ucca/obligations_framework.go` | Obligations Interfaces & Typen |
| `internal/ucca/obligations_registry.go` | Modul-Registry |
| `internal/ucca/nis2_module.go` | NIS2 Decision Tree |
| `internal/ucca/dsgvo_module.go` | DSGVO Pflichten |
| `internal/ucca/ai_act_module.go` | AI Act Risk Classification |
| `internal/ucca/pdf_export.go` | PDF/Markdown Export |
| `internal/api/handlers/obligations_handlers.go` | Obligations API |
| `policies/obligations/*.yaml` | Pflichten-Kataloge |

---

*Dokumentationsstand: 2026-01-29*