# AI Compliance SDK - Vollständige Implementierungsspezifikation

> **Version:** 1.0.0
> **Erstellt:** 2026-02-03
> **Status:** In Planung
> **Projekt:** breakpilot-pwa

---

## Inhaltsverzeichnis

1. [Executive Summary](#1-executive-summary)
2. [SDK-Architektur Übersicht](#2-sdk-architektur-übersicht)
3. [Logische Navigationsstruktur](#3-logische-navigationsstruktur)
4. [Datenfluss & Abhängigkeiten](#4-datenfluss--abhängigkeiten)
5. [Checkpoint-System](#5-checkpoint-system)
6. [Unified Command Bar](#6-unified-command-bar)
7. [State Management](#7-state-management)
8. [API-Struktur](#8-api-struktur)
9. [UI-Komponenten](#9-ui-komponenten)
10. [TypeScript Interfaces](#10-typescript-interfaces)
11. [Implementierungs-Roadmap](#11-implementierungs-roadmap)
12. [Testplan](#12-testplan)
13. [Dokumentation](#13-dokumentation)
14. [Offene Fragen & Klärungsbedarf](#14-offene-fragen--klärungsbedarf)
15. [Akzeptanzkriterien](#15-akzeptanzkriterien)

---

## 1. Executive Summary

Der AI Compliance SDK ist ein **B2B SaaS-Produkt** für Compliance-Management von KI-Anwendungsfällen. Er besteht aus zwei Hauptmodulen:

| Modul | Beschreibung | Hauptfunktionen |
|-------|--------------|-----------------|
| **Modul 1** | Automatisches Compliance Assessment | Use Case → Risiko → Controls |
| **Modul 2** | Dokumentengenerierung | DSFA, TOMs, Verträge, Cookie Banner |

### Zielgruppen

- **Datenschutzbeauftragte (DSB)**: Compliance-Überwachung, DSFA-Erstellung
- **IT-Sicherheitsbeauftragte**: Security Screening, TOMs
- **Entwickler**: Use Case Workshop, Technical Controls
- **Management**: Risk Matrix, Audit Reports
- **Auditoren**: Evidence, Checklists, Compliance Reports

### Technologie-Stack

| Komponente | Technologie | Version |
|------------|-------------|---------|
| Frontend | Next.js (App Router) | 15.1 |
| UI Framework | React + TypeScript | 18.3 / 5.7 |
| Styling | Tailwind CSS | 3.4.16 |
| Backend | Go + Gin | 1.24.0 / 1.10.1 |
| Datenbank | PostgreSQL | 15+ |
| Cache | Valkey/Redis | - |
| Vector DB | Qdrant | - |

---

## 2. SDK-Architektur Übersicht

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           AI COMPLIANCE SDK                                  │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌────────────────────────────────────────────────────────────────────────┐ │
│  │                    UNIFIED COMMAND BAR                                  │ │
│  │  [🔍 Prompt: "Erstelle DSFA für Marketing-KI..." ]  [⌘K]              │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
│                                                                              │
│  ┌──────────────┐  ┌─────────────────────────────────────────────────────┐ │
│  │              │  │                                                      │ │
│  │   SIDEBAR    │  │                    MAIN CONTENT                     │ │
│  │   (Guided    │  │                                                      │ │
│  │    Flow)     │  │   [Progress Bar: Phase 1 ████████░░ Phase 2]       │ │
│  │              │  │                                                      │ │
│  │  ┌─────────┐ │  │   ┌─────────────────────────────────────────────┐  │ │
│  │  │Phase 1  │ │  │   │                                             │  │ │
│  │  │━━━━━━━━━│ │  │   │          CURRENT STEP CONTENT               │  │ │
│  │  │1.Use Case│ │  │   │                                             │  │ │
│  │  │2.Screening│ │  │   │                                             │  │ │
│  │  │3.Compliance│ │  │   └─────────────────────────────────────────────┘  │ │
│  │  │4.Controls│ │  │                                                      │ │
│  │  │5.Evidence│ │  │   ┌─────────────────────────────────────────────┐  │ │
│  │  │6.Checklist│ │ │   │  CHECKPOINT: Qualitätsprüfung               │  │ │
│  │  │7.Risk    │ │  │   │  ☑ Alle Pflichtfelder ausgefüllt           │  │ │
│  │  │━━━━━━━━━│ │  │   │  ☑ Keine kritischen Lücken                  │  │ │
│  │  │Phase 2  │ │  │   │  ☐ DSB-Review erforderlich                  │  │ │
│  │  │━━━━━━━━━│ │  │   └─────────────────────────────────────────────┘  │ │
│  │  │8.AI Act │ │  │                                                      │ │
│  │  │9.DSFA   │ │  │   [← Zurück]              [Weiter →] [Überspringen] │ │
│  │  │10.TOMs  │ │  │                                                      │ │
│  │  │...      │ │  │                                                      │ │
│  │  └─────────┘ │  │                                                      │ │
│  │              │  │                                                      │ │
│  └──────────────┘  └─────────────────────────────────────────────────────┘ │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘
```

### Komponenten-Hierarchie

```
SDKLayout
├── CommandBar (global, ⌘K aktiviert)
├── SDKSidebar
│   ├── PhaseIndicator
│   ├── StepList (Phase 1)
│   │   └── StepItem[] mit CheckpointBadge
│   └── StepList (Phase 2)
│       └── StepItem[] mit CheckpointBadge
├── MainContent
│   ├── ProgressBar
│   ├── PageContent (dynamisch je nach Route)
│   └── CheckpointCard
└── NavigationFooter
    ├── BackButton
    ├── NextButton
    └── SkipButton
```

---

## 3. Logische Navigationsstruktur

### Phase 1: Automatisches Compliance Assessment

| # | Schritt | URL | Funktion | Voraussetzung | Checkpoint |
|---|---------|-----|----------|---------------|------------|
| 1.1 | **Use Case Workshop** | `/sdk/advisory-board` | 5-Schritte-Wizard für Use Case Erfassung | - | CP-UC |
| 1.2 | **System Screening** | `/sdk/screening` | SBOM + Security Check | Use Case erstellt | CP-SCAN |
| 1.3 | **Compliance Modules** | `/sdk/modules` | Abgleich welche Regulierungen gelten | Screening abgeschlossen | CP-MOD |
| 1.4 | **Requirements** | `/sdk/requirements` | Prüfaspekte aus Regulierungen ableiten | Module zugewiesen | CP-REQ |
| 1.5 | **Controls** | `/sdk/controls` | Erforderliche Maßnahmen ermitteln | Requirements definiert | CP-CTRL |
| 1.6 | **Evidence** | `/sdk/evidence` | Nachweise dokumentieren | Controls definiert | CP-EVI |
| 1.7 | **Audit Checklist** | `/sdk/audit-checklist` | Prüfliste generieren | Evidence vorhanden | CP-CHK |
| 1.8 | **Risk Matrix** | `/sdk/risks` | Risikobewertung & Residual Risk | Checklist abgeschlossen | CP-RISK |

### Phase 2: Dokumentengenerierung

| # | Schritt | URL | Funktion | Voraussetzung | Checkpoint |
|---|---------|-----|----------|---------------|------------|
| 2.1 | **AI Act Klassifizierung** | `/sdk/ai-act` | Risikostufe nach EU AI Act | Phase 1 abgeschlossen | CP-AI |
| 2.2 | **Pflichtenübersicht** | `/sdk/obligations` | NIS2, DSGVO, AI Act Pflichten | AI Act Klassifizierung | CP-OBL |
| 2.3 | **DSFA** | `/sdk/dsfa` | Datenschutz-Folgenabschätzung | Bei DSFA-Empfehlung | CP-DSFA |
| 2.4 | **TOMs** | `/sdk/tom` | Technische & Org. Maßnahmen | DSFA oder Controls | CP-TOM |
| 2.5 | **Löschfristen** | `/sdk/loeschfristen` | Aufbewahrungsrichtlinien | TOMs definiert | CP-RET |
| 2.6 | **Verarbeitungsverzeichnis** | `/sdk/vvt` | Art. 30 DSGVO Dokumentation | Löschfristen definiert | CP-VVT |
| 2.7 | **Rechtliche Vorlagen** | `/sdk/consent` | AGB, Datenschutz, Nutzungsbedingungen | VVT erstellt | CP-DOC |
| 2.8 | **Cookie Banner** | `/sdk/cookie-banner` | Cookie-Consent Generator | Rechtl. Vorlagen | CP-COOK |
| 2.9 | **Einwilligungen** | `/sdk/einwilligungen` | Consent-Tracking Setup | Cookie Banner | CP-CONS |
| 2.10 | **DSR Portal** | `/sdk/dsr` | Betroffenenrechte-Portal | Einwilligungen | CP-DSR |
| 2.11 | **Escalations** | `/sdk/escalations` | Management-Workflows | DSR Portal | CP-ESC |

### Zusatzmodule (Nicht im Hauptflow)

| Modul | URL | Funktion | Zugang |
|-------|-----|----------|--------|
| **Legal RAG** | `/sdk/rag` | Rechtliche Suche | Jederzeit |
| **AI Quality** | `/sdk/quality` | Qualitätsprüfung | Nach Phase 1 |
| **Security Backlog** | `/sdk/security-backlog` | Aus Screening generiert | Nach Screening |

---

## 4. Datenfluss & Abhängigkeiten

```
┌─────────────────┐
│  Use Case       │
│  Workshop       │
│  (Advisory)     │
└────────┬────────┘
         │ UseCaseIntake + AssessmentResult
         ▼
┌─────────────────┐     ┌─────────────────┐
│  System         │────▶│  Security       │
│  Screening      │     │  Backlog        │
│  (SBOM+Sec)     │     │  (Issues)       │
└────────┬────────┘     └─────────────────┘
         │ ServiceModules[] + Vulnerabilities[]
         ▼
┌─────────────────┐
│  Compliance     │
│  Modules        │
│  (Regulations)  │
└────────┬────────┘
         │ ApplicableRegulations[]
         ▼
┌─────────────────┐
│  Requirements   │
│  (558+ Rules)   │
└────────┬────────┘
         │ Requirements[] + Gaps[]
         ▼
┌─────────────────┐
│  Controls       │
│  (44+ TOM)      │
└────────┬────────┘
         │ Controls[] + ImplementationStatus
         ▼
┌─────────────────┐
│  Evidence       │
│  Management     │
└────────┬────────┘
         │ Evidence[] + Validity
         ▼
┌─────────────────┐
│  Audit          │
│  Checklist      │
└────────┬────────┘
         │ ChecklistItems[] + ComplianceScore
         ▼
┌─────────────────┐
│  Risk Matrix    │──────────────────────────────────┐
│  (5x5)          │                                  │
└────────┬────────┘                                  │
         │ Risks[] + ResidualRisks[]                 │
         ▼                                           │
═════════════════════════════════════════════════════│═══════
         │ PHASE 2 START                             │
         ▼                                           │
┌─────────────────┐                                  │
│  AI Act         │◀─────────────────────────────────┘
│  Klassifizierung│  (Risikodaten aus Phase 1)
└────────┬────────┘
         │ RiskLevel + Obligations
         ▼
┌─────────────────┐
│  Pflichten-     │
│  übersicht      │
└────────┬────────┘
         │ AllObligations[] grouped by Regulation
         ▼
┌─────────────────┐
│  DSFA           │ (Nur wenn dsfa_recommended=true)
│  Generator      │
└────────┬────────┘
         │ DSFA Document + Mitigations
         ▼
┌─────────────────┐
│  TOMs           │
│  Katalog        │
└────────┬────────┘
         │ TOM[] + ImplementationPlan
         ▼
┌─────────────────┐
│  Löschfristen   │
│  Definieren     │
└────────┬────────┘
         │ RetentionPolicies[]
         ▼
┌─────────────────┐
│  Verarbeitungs- │
│  verzeichnis    │
└────────┬────────┘
         │ ProcessingActivities[] (Art. 30)
         ▼
┌─────────────────┐
│  Rechtliche     │
│  Vorlagen       │
└────────┬────────┘
         │ Documents[] (AGB, Privacy, Terms)
         ▼
┌─────────────────┐
│  Cookie Banner  │
│  Generator      │
└────────┬────────┘
         │ CookieBannerConfig + Scripts
         ▼
┌─────────────────┐
│  Einwilligungen │
│  Tracking       │
└────────┬────────┘
         │ ConsentRecords[] + AuditTrail
         ▼
┌─────────────────┐
│  DSR Portal     │
│  Setup          │
└────────┬────────┘
         │ DSRWorkflow + Templates
         ▼
┌─────────────────┐
│  Escalations    │
│  Workflows      │
└─────────────────┘
```

---

## 5. Checkpoint-System

### 5.1 Checkpoint-Typen

```typescript
interface Checkpoint {
  id: string                              // z.B. "CP-UC"
  step: string                            // z.B. "use-case-workshop"
  name: string                            // z.B. "Use Case Checkpoint"
  type: 'REQUIRED' | 'RECOMMENDED' | 'OPTIONAL'
  validation: ValidationRule[]
  blocksProgress: boolean
  requiresReview: 'NONE' | 'TEAM_LEAD' | 'DSB' | 'LEGAL'
  autoValidate: boolean                   // Automatische Validierung bei Änderungen
}

interface ValidationRule {
  id: string
  field: string                           // Pfad zum Feld im State
  condition: 'NOT_EMPTY' | 'MIN_COUNT' | 'MIN_VALUE' | 'CUSTOM' | 'REGEX'
  value?: number | string | RegExp        // Vergleichswert
  customValidator?: (state: SDKState) => boolean
  message: string                         // Fehlermeldung
  severity: 'ERROR' | 'WARNING' | 'INFO'
}

interface CheckpointStatus {
  checkpointId: string
  passed: boolean
  validatedAt: Date | null
  validatedBy: string | null              // User ID oder "SYSTEM"
  errors: ValidationError[]
  warnings: ValidationError[]
  overrideReason?: string                 // Falls manuell überschrieben
  overriddenBy?: string
  overriddenAt?: Date
}
```

### 5.2 Checkpoint-Matrix

| Checkpoint | Schritt | Validierung | Blockiert | Review |
|------------|---------|-------------|-----------|--------|
| CP-UC | 1.1 Use Case | Min. 1 Use Case mit allen 5 Schritten | ✅ Ja | NONE |
| CP-SCAN | 1.2 Screening | SBOM generiert, Security Scan abgeschlossen | ✅ Ja | NONE |
| CP-MOD | 1.3 Modules | Min. 1 Regulierung zugewiesen | ✅ Ja | NONE |
| CP-REQ | 1.4 Requirements | Alle kritischen Requirements adressiert | ✅ Ja | NONE |
| CP-CTRL | 1.5 Controls | Alle BLOCK-Controls definiert | ✅ Ja | DSB |
| CP-EVI | 1.6 Evidence | Evidence für alle kritischen Controls | ❌ Nein | NONE |
| CP-CHK | 1.7 Checklist | Checklist generiert | ❌ Nein | NONE |
| CP-RISK | 1.8 Risk Matrix | Alle HIGH/CRITICAL Risiken mit Mitigation | ✅ Ja | DSB |
| CP-AI | 2.1 AI Act | Risikostufe bestätigt | ✅ Ja | LEGAL |
| CP-OBL | 2.2 Pflichten | Pflichten zugewiesen | ❌ Nein | NONE |
| CP-DSFA | 2.3 DSFA | DSFA abgeschlossen (wenn erforderlich) | ✅ Ja* | DSB |
| CP-TOM | 2.4 TOMs | Alle erforderlichen TOMs definiert | ✅ Ja | NONE |
| CP-RET | 2.5 Löschfristen | Fristen für alle Datenkategorien | ✅ Ja | NONE |
| CP-VVT | 2.6 VVT | Verzeichnis vollständig | ✅ Ja | DSB |
| CP-DOC | 2.7 Vorlagen | Dokumente erstellt | ❌ Nein | LEGAL |
| CP-COOK | 2.8 Cookie | Banner konfiguriert | ❌ Nein | NONE |
| CP-CONS | 2.9 Einwilligungen | Tracking aktiviert | ❌ Nein | NONE |
| CP-DSR | 2.10 DSR | Portal konfiguriert | ❌ Nein | NONE |
| CP-ESC | 2.11 Escalations | Workflows definiert | ❌ Nein | NONE |

*Nur wenn DSFA empfohlen wurde

### 5.3 Validierungsregeln (Beispiele)

```typescript
const checkpointValidations: Record<string, ValidationRule[]> = {
  'CP-UC': [
    {
      id: 'uc-min-count',
      field: 'useCases',
      condition: 'MIN_COUNT',
      value: 1,
      message: 'Mindestens ein Use Case muss erstellt werden',
      severity: 'ERROR'
    },
    {
      id: 'uc-steps-complete',
      field: 'useCases',
      condition: 'CUSTOM',
      customValidator: (state) => state.useCases.every(uc => uc.stepsCompleted === 5),
      message: 'Alle Use Cases müssen alle 5 Schritte abgeschlossen haben',
      severity: 'ERROR'
    }
  ],
  'CP-SCAN': [
    {
      id: 'sbom-exists',
      field: 'sbom',
      condition: 'NOT_EMPTY',
      message: 'SBOM muss generiert werden',
      severity: 'ERROR'
    },
    {
      id: 'scan-complete',
      field: 'screening.status',
      condition: 'CUSTOM',
      customValidator: (state) => state.screening?.status === 'completed',
      message: 'Security Scan muss abgeschlossen sein',
      severity: 'ERROR'
    }
  ],
  'CP-RISK': [
    {
      id: 'critical-risks-mitigated',
      field: 'risks',
      condition: 'CUSTOM',
      customValidator: (state) => {
        const criticalRisks = state.risks.filter(r =>
          r.severity === 'CRITICAL' || r.severity === 'HIGH'
        );
        return criticalRisks.every(r => r.mitigation && r.mitigation.length > 0);
      },
      message: 'Alle kritischen und hohen Risiken müssen Mitigationsmaßnahmen haben',
      severity: 'ERROR'
    }
  ]
};
```

---

## 6. Unified Command Bar

### 6.1 Architektur

```typescript
interface CommandBarState {
  isOpen: boolean
  query: string
  context: SDKContext
  suggestions: CommandSuggestion[]
  history: CommandHistory[]
  isLoading: boolean
  error: string | null
}

interface SDKContext {
  currentPhase: 1 | 2
  currentStep: string
  completedSteps: string[]
  activeCheckpoint: Checkpoint | null
  useCases: UseCaseAssessment[]
  pendingActions: Action[]
}

interface CommandSuggestion {
  id: string
  type: 'ACTION' | 'NAVIGATION' | 'SEARCH' | 'GENERATE' | 'HELP'
  label: string
  description: string
  shortcut?: string
  icon?: string
  action: () => void | Promise<void>
  relevanceScore: number
}

interface CommandHistory {
  id: string
  query: string
  type: CommandSuggestion['type']
  timestamp: Date
  success: boolean
}
```

### 6.2 Unterstützte Befehle

| Kategorie | Befehl | Aktion |
|-----------|--------|--------|
| **Navigation** | "Gehe zu DSFA" | navigiert zu `/sdk/dsfa` |
| | "Öffne Risk Matrix" | navigiert zu `/sdk/risks` |
| | "Zurück" | vorheriger Schritt |
| | "Phase 2" | springt zu Phase 2 Start |
| **Aktionen** | "Erstelle neuen Use Case" | startet Wizard |
| | "Exportiere als PDF" | generiert Export |
| | "Starte Security Scan" | triggert Screening |
| | "Validiere Checkpoint" | führt Validierung durch |
| **Generierung** | "Erstelle DSFA für Marketing-KI" | RAG-basierte Generierung |
| | "Welche TOMs brauche ich für Gesundheitsdaten?" | Empfehlungen |
| | "Erkläre Art. 9 DSGVO" | Rechtliche Erklärung |
| **Suche** | "Suche DSGVO Artikel 17" | Rechtliche Suche |
| | "Finde Controls für Verschlüsselung" | Control-Suche |
| **Hilfe** | "Hilfe" | zeigt verfügbare Befehle |
| | "Was muss ich als nächstes tun?" | Kontextbezogene Hilfe |

### 6.3 Keyboard Shortcuts

| Shortcut | Aktion |
|----------|--------|
| `⌘K` / `Ctrl+K` | Command Bar öffnen |
| `Escape` | Command Bar schließen |
| `↑` / `↓` | Navigation in Suggestions |
| `Enter` | Suggestion ausführen |
| `⌘→` / `Ctrl+→` | Nächster Schritt |
| `⌘←` / `Ctrl+←` | Vorheriger Schritt |
| `⌘S` / `Ctrl+S` | State speichern |
| `⌘E` / `Ctrl+E` | Export-Dialog |

---

## 7. State Management

### 7.1 Globaler SDK-State

```typescript
interface SDKState {
  // Metadata
  version: string                         // Schema-Version
  lastModified: Date

  // Tenant & User
  tenantId: string
  userId: string
  subscription: SubscriptionTier

  // Progress
  currentPhase: 1 | 2
  currentStep: string
  completedSteps: string[]
  checkpoints: Record<string, CheckpointStatus>

  // Phase 1 Data
  useCases: UseCaseAssessment[]
  activeUseCase: string | null
  screening: ScreeningResult | null
  modules: ServiceModule[]
  requirements: Requirement[]
  controls: Control[]
  evidence: Evidence[]
  checklist: ChecklistItem[]
  risks: Risk[]

  // Phase 2 Data
  aiActClassification: AIActResult | null
  obligations: Obligation[]
  dsfa: DSFA | null
  toms: TOM[]
  retentionPolicies: RetentionPolicy[]
  vvt: ProcessingActivity[]
  documents: LegalDocument[]
  cookieBanner: CookieBannerConfig | null
  consents: ConsentRecord[]
  dsrConfig: DSRConfig | null
  escalationWorkflows: EscalationWorkflow[]

  // Security
  sbom: SBOM | null
  securityIssues: SecurityIssue[]
  securityBacklog: BacklogItem[]

  // UI State
  commandBarHistory: CommandHistory[]
  recentSearches: string[]
  preferences: UserPreferences
}

type SubscriptionTier = 'FREE' | 'STARTER' | 'PROFESSIONAL' | 'ENTERPRISE';

interface UserPreferences {
  language: 'de' | 'en'
  theme: 'light' | 'dark' | 'system'
  compactMode: boolean
  showHints: boolean
  autoSave: boolean
  autoValidate: boolean
}
```

### 7.2 Persistierung

```typescript
// Auto-Save bei jeder Änderung
const autoSave = debounce(async (state: SDKState) => {
  await api.post('/sdk/v1/state/save', {
    tenantId: state.tenantId,
    state: serializeState(state),
    checksum: calculateChecksum(state)
  });
}, 2000);

// Load bei App-Start
const loadState = async (tenantId: string): Promise<SDKState> => {
  const saved = await api.get(`/sdk/v1/state/${tenantId}`);
  return deserializeState(saved);
};

// Conflict Resolution
const mergeStates = (local: SDKState, remote: SDKState): SDKState => {
  if (local.lastModified > remote.lastModified) {
    return local;
  }
  return remote;
};
```

### 7.3 React Context

```typescript
interface SDKContextValue {
  state: SDKState
  dispatch: React.Dispatch<SDKAction>

  // Navigation
  goToStep: (step: string) => void
  goToNextStep: () => void
  goToPreviousStep: () => void

  // Checkpoints
  validateCheckpoint: (checkpointId: string) => Promise<CheckpointStatus>
  overrideCheckpoint: (checkpointId: string, reason: string) => Promise<void>

  // State Updates
  updateUseCase: (id: string, data: Partial<UseCaseAssessment>) => void
  addRisk: (risk: Risk) => void
  updateControl: (id: string, data: Partial<Control>) => void

  // Export
  exportState: (format: 'json' | 'pdf' | 'zip') => Promise<Blob>
}

const SDKContext = React.createContext<SDKContextValue | null>(null);

export const useSDK = () => {
  const context = useContext(SDKContext);
  if (!context) {
    throw new Error('useSDK must be used within SDKProvider');
  }
  return context;
};
```

---

## 8. API-Struktur

### 8.1 SDK-spezifische Endpoints

```
# State Management
GET    /sdk/v1/state/{tenantId}              → Kompletten State laden
POST   /sdk/v1/state/save                    → State speichern
POST   /sdk/v1/state/reset                   → State zurücksetzen
GET    /sdk/v1/state/history                 → State-Historie (für Undo)

# Screening
POST   /sdk/v1/screening/start               → SBOM + Security Scan starten
GET    /sdk/v1/screening/status              → Scan-Status abrufen
GET    /sdk/v1/screening/sbom                → SBOM abrufen
GET    /sdk/v1/screening/security            → Security Issues abrufen
POST   /sdk/v1/screening/backlog             → Backlog aus Issues generieren

# Checkpoints
GET    /sdk/v1/checkpoints                   → Alle Checkpoint-Status
GET    /sdk/v1/checkpoints/{id}              → Einzelner Checkpoint
POST   /sdk/v1/checkpoints/{id}/validate     → Checkpoint validieren
POST   /sdk/v1/checkpoints/{id}/override     → Checkpoint überschreiben (mit Review)
GET    /sdk/v1/checkpoints/{id}/history      → Validierungs-Historie

# Wizard Flow
GET    /sdk/v1/flow/current                  → Aktueller Schritt + Kontext
POST   /sdk/v1/flow/next                     → Zum nächsten Schritt
POST   /sdk/v1/flow/previous                 → Zum vorherigen Schritt
GET    /sdk/v1/flow/suggestions              → Kontextbezogene Vorschläge
GET    /sdk/v1/flow/progress                 → Gesamtfortschritt

# Document Generation
POST   /sdk/v1/generate/dsfa                 → DSFA generieren
POST   /sdk/v1/generate/tom                  → TOMs generieren
POST   /sdk/v1/generate/vvt                  → VVT generieren
POST   /sdk/v1/generate/documents            → Rechtliche Vorlagen
POST   /sdk/v1/generate/cookie-banner        → Cookie Banner Code
POST   /sdk/v1/generate/dsr-portal           → DSR Portal Config

# Export
GET    /sdk/v1/export/full                   → Kompletter Export (ZIP)
GET    /sdk/v1/export/phase1                 → Phase 1 Export
GET    /sdk/v1/export/phase2                 → Phase 2 Export
GET    /sdk/v1/export/{document}             → Einzelnes Dokument
GET    /sdk/v1/export/audit-report           → Audit-Report (PDF)

# Command Bar / RAG
POST   /sdk/v1/command/execute               → Befehl ausführen
POST   /sdk/v1/command/search                → Suche durchführen
POST   /sdk/v1/command/generate              → Content generieren (RAG)
GET    /sdk/v1/command/suggestions           → Vorschläge basierend auf Kontext
```

### 8.2 Request/Response Beispiele

```typescript
// POST /sdk/v1/checkpoints/{id}/validate
// Request
{
  "checkpointId": "CP-RISK",
  "context": {
    "userId": "user-123",
    "timestamp": "2026-02-03T10:30:00Z"
  }
}

// Response
{
  "checkpointId": "CP-RISK",
  "passed": false,
  "validatedAt": "2026-02-03T10:30:01Z",
  "validatedBy": "SYSTEM",
  "errors": [
    {
      "ruleId": "critical-risks-mitigated",
      "field": "risks[2]",
      "message": "Risiko 'Datenverlust' hat keine Mitigationsmaßnahme",
      "severity": "ERROR"
    }
  ],
  "warnings": [
    {
      "ruleId": "risk-owner-assigned",
      "field": "risks[5]",
      "message": "Risiko 'Performance-Degradation' hat keinen Owner",
      "severity": "WARNING"
    }
  ],
  "nextActions": [
    {
      "type": "FIX_ERROR",
      "targetField": "risks[2].mitigation",
      "suggestion": "Fügen Sie eine Mitigationsmaßnahme hinzu"
    }
  ]
}
```

---

## 9. UI-Komponenten

### 9.1 Komponentenstruktur

```
admin-v2/components/sdk/
├── CommandBar/
│   ├── CommandBar.tsx              # Hauptkomponente (⌘K Modal)
│   ├── CommandInput.tsx            # Eingabefeld mit Autocomplete
│   ├── SuggestionList.tsx          # Vorschlagsliste
│   ├── SuggestionItem.tsx          # Einzelner Vorschlag
│   ├── CommandHistory.tsx          # Historie-Anzeige
│   ├── useCommandBar.ts            # Hook für State & Logic
│   └── index.ts
│
├── Sidebar/
│   ├── SDKSidebar.tsx              # Hauptnavigation
│   ├── PhaseIndicator.tsx          # Phase 1/2 Anzeige mit Progress
│   ├── StepList.tsx                # Liste der Schritte
│   ├── StepItem.tsx                # Einzelner Schritt
│   ├── CheckpointBadge.tsx         # Checkpoint-Status Badge
│   ├── CollapsibleSection.tsx      # Einklappbare Sektion
│   └── index.ts
│
├── Progress/
│   ├── ProgressBar.tsx             # Gesamtfortschritt
│   ├── StepProgress.tsx            # Schritt-Fortschritt (circular)
│   ├── PhaseTransition.tsx         # Übergang Phase 1→2 Animation
│   ├── CompletionCard.tsx          # Abschluss-Karte
│   └── index.ts
│
├── Checkpoint/
│   ├── CheckpointCard.tsx          # Checkpoint-Anzeige
│   ├── ValidationList.tsx          # Validierungsfehler/-warnungen
│   ├── ValidationItem.tsx          # Einzelner Validierungsfehler
│   ├── ReviewRequest.tsx           # Review anfordern
│   ├── CheckpointOverride.tsx      # Override mit Begründung
│   ├── CheckpointHistory.tsx       # Validierungs-Historie
│   └── index.ts
│
├── Wizard/
│   ├── WizardContainer.tsx         # Wizard-Rahmen
│   ├── WizardStep.tsx              # Einzelner Schritt
│   ├── WizardNavigation.tsx        # Vor/Zurück/Überspringen
│   ├── WizardSummary.tsx           # Zusammenfassung
│   ├── WizardProgress.tsx          # Progress Indicator
│   └── index.ts
│
├── Screening/
│   ├── ScreeningDashboard.tsx      # Übersicht
│   ├── SBOMViewer.tsx              # SBOM Anzeige (Tabelle)
│   ├── SBOMGraph.tsx               # SBOM als Dependency Graph
│   ├── SecurityIssues.tsx          # Issues Liste
│   ├── SecurityIssueCard.tsx       # Einzelne Issue
│   ├── BacklogGenerator.tsx        # Backlog erstellen
│   ├── ScanProgress.tsx            # Scan-Fortschritt
│   └── index.ts
│
├── Generation/
│   ├── DocumentGenerator.tsx       # Dokument-Generierung
│   ├── GenerationProgress.tsx      # Fortschritt (Streaming)
│   ├── DocumentPreview.tsx         # Vorschau (Markdown/PDF)
│   ├── DocumentEditor.tsx          # Inline-Editor
│   ├── ExportDialog.tsx            # Export-Optionen
│   └── index.ts
│
├── Risk/
│   ├── RiskMatrix.tsx              # 5x5 Risk Matrix
│   ├── RiskCard.tsx                # Einzelnes Risiko
│   ├── RiskForm.tsx                # Risiko hinzufügen/bearbeiten
│   ├── MitigationForm.tsx          # Mitigation hinzufügen
│   └── index.ts
│
├── Layout/
│   ├── SDKLayout.tsx               # SDK-spezifisches Layout
│   ├── SDKHeader.tsx               # Header mit Aktionen
│   ├── NavigationFooter.tsx        # Vor/Zurück Footer
│   └── index.ts
│
└── common/
    ├── StatusBadge.tsx             # Status-Anzeige
    ├── ActionButton.tsx            # Primäre Aktionen
    ├── InfoTooltip.tsx             # Hilfe-Tooltips
    ├── EmptyState.tsx              # Leerer Zustand
    ├── LoadingState.tsx            # Ladezustand
    ├── ErrorBoundary.tsx           # Fehlerbehandlung
    └── index.ts
```

### 9.2 Beispiel-Komponenten

```typescript
// SDKSidebar.tsx
interface SDKSidebarProps {
  currentStep: string
  completedSteps: string[]
  checkpoints: Record<string, CheckpointStatus>
  onStepClick: (step: string) => void
}

// CheckpointCard.tsx
interface CheckpointCardProps {
  checkpoint: Checkpoint
  status: CheckpointStatus
  onValidate: () => Promise<void>
  onOverride: (reason: string) => Promise<void>
  onRequestReview: (reviewerType: string) => Promise<void>
}

// CommandBar.tsx
interface CommandBarProps {
  isOpen: boolean
  onClose: () => void
  context: SDKContext
  onExecute: (command: CommandSuggestion) => Promise<void>
}
```

---

## 10. TypeScript Interfaces

### 10.1 Core Models

```typescript
// Use Case Assessment
interface UseCaseAssessment {
  id: string
  name: string
  description: string
  category: string
  stepsCompleted: number
  steps: UseCaseStep[]
  assessmentResult: AssessmentResult | null
  createdAt: Date
  updatedAt: Date
}

interface UseCaseStep {
  id: string
  name: string
  completed: boolean
  data: Record<string, unknown>
}

interface AssessmentResult {
  riskLevel: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL'
  applicableRegulations: string[]
  recommendedControls: string[]
  dsfaRequired: boolean
  aiActClassification: string
}

// Screening
interface ScreeningResult {
  id: string
  status: 'pending' | 'running' | 'completed' | 'failed'
  startedAt: Date
  completedAt: Date | null
  sbom: SBOM | null
  securityScan: SecurityScanResult | null
  error: string | null
}

interface SBOM {
  format: 'CycloneDX' | 'SPDX'
  version: string
  components: SBOMComponent[]
  dependencies: SBOMDependency[]
  generatedAt: Date
}

interface SBOMComponent {
  name: string
  version: string
  type: 'library' | 'framework' | 'application' | 'container'
  purl: string
  licenses: string[]
  vulnerabilities: Vulnerability[]
}

interface SecurityScanResult {
  totalIssues: number
  critical: number
  high: number
  medium: number
  low: number
  issues: SecurityIssue[]
}

interface SecurityIssue {
  id: string
  severity: 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW'
  title: string
  description: string
  cve: string | null
  cvss: number | null
  affectedComponent: string
  remediation: string
  status: 'OPEN' | 'IN_PROGRESS' | 'RESOLVED' | 'ACCEPTED'
}

// Compliance
interface ServiceModule {
  id: string
  name: string
  description: string
  regulations: string[]
  criticality: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL'
  processesPersonalData: boolean
  hasAIComponents: boolean
}

interface Requirement {
  id: string
  regulation: string
  article: string
  title: string
  description: string
  criticality: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL'
  applicableModules: string[]
  status: 'NOT_STARTED' | 'IN_PROGRESS' | 'IMPLEMENTED' | 'VERIFIED'
  controls: string[]
}

interface Control {
  id: string
  name: string
  description: string
  type: 'TECHNICAL' | 'ORGANIZATIONAL' | 'PHYSICAL'
  category: string
  implementationStatus: 'NOT_IMPLEMENTED' | 'PARTIAL' | 'IMPLEMENTED'
  effectiveness: 'LOW' | 'MEDIUM' | 'HIGH'
  evidence: string[]
  owner: string | null
  dueDate: Date | null
}

interface Evidence {
  id: string
  controlId: string
  type: 'DOCUMENT' | 'SCREENSHOT' | 'LOG' | 'CERTIFICATE' | 'AUDIT_REPORT'
  name: string
  description: string
  fileUrl: string | null
  validFrom: Date
  validUntil: Date | null
  uploadedBy: string
  uploadedAt: Date
}

// Risk
interface Risk {
  id: string
  title: string
  description: string
  category: string
  likelihood: 1 | 2 | 3 | 4 | 5
  impact: 1 | 2 | 3 | 4 | 5
  severity: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL'
  inherentRiskScore: number
  residualRiskScore: number
  status: 'IDENTIFIED' | 'ASSESSED' | 'MITIGATED' | 'ACCEPTED' | 'CLOSED'
  mitigation: RiskMitigation[]
  owner: string | null
  relatedControls: string[]
  relatedRequirements: string[]
}

interface RiskMitigation {
  id: string
  description: string
  type: 'AVOID' | 'TRANSFER' | 'MITIGATE' | 'ACCEPT'
  status: 'PLANNED' | 'IN_PROGRESS' | 'COMPLETED'
  effectiveness: number // 0-100
  controlId: string | null
}

// Phase 2 Models
interface AIActResult {
  riskCategory: 'MINIMAL' | 'LIMITED' | 'HIGH' | 'UNACCEPTABLE'
  systemType: string
  obligations: AIActObligation[]
  assessmentDate: Date
  assessedBy: string
  justification: string
}

interface DSFA {
  id: string
  status: 'DRAFT' | 'IN_REVIEW' | 'APPROVED' | 'REJECTED'
  version: number
  sections: DSFASection[]
  approvals: DSFAApproval[]
  createdAt: Date
  updatedAt: Date
}

interface TOM {
  id: string
  category: string
  name: string
  description: string
  type: 'TECHNICAL' | 'ORGANIZATIONAL'
  implementationStatus: 'NOT_IMPLEMENTED' | 'PARTIAL' | 'IMPLEMENTED'
  priority: 'LOW' | 'MEDIUM' | 'HIGH'
  responsiblePerson: string | null
  implementationDate: Date | null
  reviewDate: Date | null
  evidence: string[]
}

interface RetentionPolicy {
  id: string
  dataCategory: string
  description: string
  legalBasis: string
  retentionPeriod: string // ISO 8601 Duration
  deletionMethod: string
  exceptions: string[]
}

interface ProcessingActivity {
  id: string
  name: string
  purpose: string
  legalBasis: string
  dataCategories: string[]
  dataSubjects: string[]
  recipients: string[]
  thirdCountryTransfers: boolean
  retentionPeriod: string
  technicalMeasures: string[]
  organizationalMeasures: string[]
}

interface CookieBannerConfig {
  id: string
  style: 'BANNER' | 'MODAL' | 'FLOATING'
  position: 'TOP' | 'BOTTOM' | 'CENTER'
  theme: 'LIGHT' | 'DARK' | 'CUSTOM'
  texts: {
    title: string
    description: string
    acceptAll: string
    rejectAll: string
    settings: string
    save: string
  }
  categories: CookieCategory[]
  generatedCode: {
    html: string
    css: string
    js: string
  }
}

interface CookieCategory {
  id: string
  name: string
  description: string
  required: boolean
  cookies: Cookie[]
}
```

---

## 11. Implementierungs-Roadmap

### Sprint 1: Foundation (2 Wochen)

| Task | Beschreibung | Priorität | Abhängigkeiten |
|------|--------------|-----------|----------------|
| SDK-Routing | `/sdk/*` Routen einrichten | KRITISCH | - |
| SDKProvider | State Management Context | KRITISCH | - |
| SDKLayout | Layout mit Sidebar | KRITISCH | SDKProvider |
| SDKSidebar | Navigation mit Phasen | HOCH | SDKLayout |
| Checkpoint-Types | TypeScript Interfaces | HOCH | - |
| Checkpoint-Service | Validierungs-Logik | HOCH | Checkpoint-Types |
| API: State | GET/POST /sdk/v1/state/* | HOCH | - |
| API: Checkpoints | GET/POST /sdk/v1/checkpoints/* | HOCH | Checkpoint-Service |

**Deliverables Sprint 1:**
- Funktionierendes SDK-Routing
- State-Persistierung
- Basis-Navigation zwischen Schritten

### Sprint 2: Phase 1 Flow (3 Wochen)

| Task | Beschreibung | Priorität | Abhängigkeiten |
|------|--------------|-----------|----------------|
| Use Case Workshop | Integration bestehender Advisory Board | KRITISCH | Sprint 1 |
| Screening-UI | Dashboard + SBOM Viewer | KRITISCH | Sprint 1 |
| Screening-Backend | SBOM Generation + Security Scan | KRITISCH | - |
| SecurityBacklog | Backlog aus Issues generieren | HOCH | Screening |
| Modules-Integration | Compliance Module Verknüpfung | HOCH | Screening |
| Requirements-Flow | Requirements aus Modulen ableiten | HOCH | Modules |
| Controls-Flow | Controls aus Requirements | HOCH | Requirements |
| Evidence-Management | Evidence Upload + Validierung | MITTEL | Controls |
| Audit-Checklist | Checklist generieren | MITTEL | Evidence |
| Risk-Matrix | 5x5 Matrix + Mitigation | KRITISCH | Checklist |

**Deliverables Sprint 2:**
- Vollständiger Phase 1 Flow
- SBOM-Generierung
- Security Scanning
- Risk Assessment

### Sprint 3: Phase 2 Flow (3 Wochen)

| Task | Beschreibung | Priorität | Abhängigkeiten |
|------|--------------|-----------|----------------|
| AI Act Klassifizierung | Wizard + Empfehlungen | KRITISCH | Phase 1 |
| Pflichtenübersicht | Gruppierte Pflichten-Ansicht | HOCH | AI Act |
| DSFA Generator | RAG-basierte Generierung | KRITISCH | Pflichtenübersicht |
| TOMs Katalog | TOM-Auswahl + Priorisierung | HOCH | DSFA |
| Löschfristen | Fristen-Management | MITTEL | TOMs |
| VVT Generator | Art. 30 Export | HOCH | Löschfristen |
| Rechtliche Vorlagen | Template-System | MITTEL | VVT |

**Deliverables Sprint 3:**
- AI Act Compliance
- DSFA-Generierung
- TOM-Management
- VVT-Export

### Sprint 4: Consent & DSR (2 Wochen)

| Task | Beschreibung | Priorität | Abhängigkeiten |
|------|--------------|-----------|----------------|
| Cookie Banner Generator | Konfigurator + Code-Export | HOCH | Sprint 3 |
| Cookie Kategorien | Kategorie-Management | HOCH | Cookie Banner |
| Einwilligungen Tracking | Consent Records | MITTEL | Cookie Banner |
| DSR Portal Config | Portal-Einrichtung | MITTEL | Einwilligungen |
| DSR Workflows | Bearbeitungs-Workflows | MITTEL | DSR Portal |
| Escalations | Management-Workflows | NIEDRIG | DSR |

**Deliverables Sprint 4:**
- Cookie Consent System
- DSR Management
- Escalation Workflows

### Sprint 5: Command Bar & Polish (2 Wochen)

| Task | Beschreibung | Priorität | Abhängigkeiten |
|------|--------------|-----------|----------------|
| CommandBar UI | Modal + Input | HOCH | Sprint 4 |
| Command Parser | Befehlserkennung | HOCH | CommandBar UI |
| RAG Integration | Suche + Generierung | HOCH | Command Parser |
| Suggestion Engine | Kontextbezogene Vorschläge | MITTEL | RAG |
| Keyboard Shortcuts | Global Shortcuts | MITTEL | CommandBar |
| Export-Funktionen | PDF/ZIP/JSON Export | HOCH | - |
| Progress Animations | Übergangs-Animationen | NIEDRIG | - |
| Responsive Design | Mobile Optimierung | MITTEL | - |

**Deliverables Sprint 5:**
- Unified Command Bar
- Export-System
- Polish & UX

### Sprint 6: Testing & QA (1 Woche)

| Task | Beschreibung | Priorität | Abhängigkeiten |
|------|--------------|-----------|----------------|
| Unit Tests | Komponenten-Tests | KRITISCH | Sprint 5 |
| Integration Tests | API-Tests | KRITISCH | Sprint 5 |
| E2E Tests | Flow-Tests | KRITISCH | Sprint 5 |
| Performance Tests | Load Testing | HOCH | Sprint 5 |
| Security Audit | Sicherheitsprüfung | KRITISCH | Sprint 5 |
| Dokumentation | User Guide + API Docs | HOCH | Sprint 5 |
| Bug Fixes | Fehlerbehebung | KRITISCH | Tests |

**Deliverables Sprint 6:**
- Vollständige Testabdeckung
- Dokumentation
- Production-Ready Release

---

## 12. Testplan

### 12.1 Unit Tests

```typescript
// Beispiel: Checkpoint Validation Tests
describe('CheckpointService', () => {
  describe('validateCheckpoint', () => {
    it('should return passed=true when all validations pass', async () => {
      const state = createMockState({
        useCases: [{ id: '1', stepsCompleted: 5 }]
      });

      const result = await checkpointService.validate('CP-UC', state);

      expect(result.passed).toBe(true);
      expect(result.errors).toHaveLength(0);
    });

    it('should return errors when use case steps incomplete', async () => {
      const state = createMockState({
        useCases: [{ id: '1', stepsCompleted: 3 }]
      });

      const result = await checkpointService.validate('CP-UC', state);

      expect(result.passed).toBe(false);
      expect(result.errors).toContainEqual(
        expect.objectContaining({ ruleId: 'uc-steps-complete' })
      );
    });

    it('should allow override with valid reason', async () => {
      const result = await checkpointService.override(
        'CP-UC',
        'Genehmigt durch DSB am 2026-02-03',
        'user-123'
      );

      expect(result.overrideReason).toBeTruthy();
      expect(result.passed).toBe(true);
    });
  });
});

// Beispiel: Risk Matrix Tests
describe('RiskMatrix', () => {
  describe('calculateRiskScore', () => {
    it('should calculate correct risk score', () => {
      const risk: Risk = {
        likelihood: 4,
        impact: 5
      };

      const score = calculateRiskScore(risk);

      expect(score).toBe(20);
      expect(getRiskSeverity(score)).toBe('CRITICAL');
    });

    it('should calculate residual risk after mitigation', () => {
      const risk: Risk = {
        likelihood: 4,
        impact: 5,
        mitigation: [{ effectiveness: 60 }]
      };

      const residualScore = calculateResidualRisk(risk);

      expect(residualScore).toBe(8); // 20 * 0.4
    });
  });
});

// Beispiel: Command Bar Tests
describe('CommandParser', () => {
  it('should parse navigation commands', () => {
    const result = parseCommand('Gehe zu DSFA');

    expect(result.type).toBe('NAVIGATION');
    expect(result.target).toBe('/sdk/dsfa');
  });

  it('should parse generation commands', () => {
    const result = parseCommand('Erstelle DSFA für Marketing-KI');

    expect(result.type).toBe('GENERATE');
    expect(result.documentType).toBe('dsfa');
    expect(result.context).toContain('Marketing-KI');
  });

  it('should return suggestions for partial input', () => {
    const suggestions = getSuggestions('Erst', mockContext);

    expect(suggestions).toContainEqual(
      expect.objectContaining({ label: 'Erstelle neuen Use Case' })
    );
  });
});
```

### 12.2 Integration Tests

```typescript
// API Integration Tests
describe('SDK API', () => {
  describe('POST /sdk/v1/state/save', () => {
    it('should save state successfully', async () => {
      const state = createMockState();

      const response = await request(app)
        .post('/sdk/v1/state/save')
        .send({ tenantId: 'tenant-1', state })
        .expect(200);

      expect(response.body.success).toBe(true);
      expect(response.body.savedAt).toBeTruthy();
    });

    it('should reject invalid state schema', async () => {
      const invalidState = { invalid: 'data' };

      await request(app)
        .post('/sdk/v1/state/save')
        .send({ tenantId: 'tenant-1', state: invalidState })
        .expect(400);
    });
  });

  describe('POST /sdk/v1/screening/start', () => {
    it('should start SBOM generation', async () => {
      const response = await request(app)
        .post('/sdk/v1/screening/start')
        .send({
          repositoryUrl: 'https://github.com/example/repo',
          branch: 'main'
        })
        .expect(202);

      expect(response.body.scanId).toBeTruthy();
      expect(response.body.status).toBe('pending');
    });
  });

  describe('POST /sdk/v1/generate/dsfa', () => {
    it('should generate DSFA document', async () => {
      const response = await request(app)
        .post('/sdk/v1/generate/dsfa')
        .send({
          useCaseId: 'uc-1',
          includeRiskAssessment: true
        })
        .expect(200);

      expect(response.body.dsfa).toBeTruthy();
      expect(response.body.dsfa.sections).toHaveLength(8);
    });
  });
});
```

### 12.3 E2E Tests

```typescript
// Playwright E2E Tests
import { test, expect } from '@playwright/test';

test.describe('SDK Complete Flow', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/sdk');
    await page.waitForSelector('[data-testid="sdk-sidebar"]');
  });

  test('should complete Phase 1 workflow', async ({ page }) => {
    // Step 1.1: Use Case Workshop
    await page.click('[data-testid="step-use-case"]');
    await page.fill('[data-testid="use-case-name"]', 'Marketing AI');
    await page.click('[data-testid="wizard-next"]');
    // ... complete all 5 steps
    await expect(page.locator('[data-testid="checkpoint-CP-UC"]')).toHaveAttribute(
      'data-passed',
      'true'
    );

    // Step 1.2: Screening
    await page.click('[data-testid="step-screening"]');
    await page.fill('[data-testid="repository-url"]', 'https://github.com/example/repo');
    await page.click('[data-testid="start-scan"]');
    await page.waitForSelector('[data-testid="scan-complete"]', { timeout: 60000 });

    // ... continue through Phase 1
  });

  test('should block progress when checkpoint fails', async ({ page }) => {
    await page.click('[data-testid="step-requirements"]');
    await page.click('[data-testid="nav-next"]');

    // Should show checkpoint error
    await expect(page.locator('[data-testid="checkpoint-error"]')).toBeVisible();
    await expect(page.locator('[data-testid="checkpoint-error"]')).toContainText(
      'Vorherige Schritte nicht abgeschlossen'
    );
  });

  test('should open command bar with Cmd+K', async ({ page }) => {
    await page.keyboard.press('Meta+k');

    await expect(page.locator('[data-testid="command-bar"]')).toBeVisible();

    await page.fill('[data-testid="command-input"]', 'Gehe zu DSFA');
    await page.keyboard.press('Enter');

    await expect(page).toHaveURL('/sdk/dsfa');
  });

  test('should export complete documentation', async ({ page }) => {
    // Navigate to completed state
    await page.goto('/sdk/escalations');

    // Open command bar and export
    await page.keyboard.press('Meta+k');
    await page.fill('[data-testid="command-input"]', 'Exportiere als PDF');
    await page.keyboard.press('Enter');

    // Wait for download
    const [download] = await Promise.all([
      page.waitForEvent('download'),
      page.click('[data-testid="confirm-export"]')
    ]);

    expect(download.suggestedFilename()).toMatch(/compliance-report.*\.pdf/);
  });
});
```

### 12.4 Performance Tests

```typescript
// k6 Load Tests
import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
  stages: [
    { duration: '30s', target: 20 },  // Ramp up
    { duration: '1m', target: 20 },   // Stay at 20 users
    { duration: '30s', target: 50 },  // Ramp up more
    { duration: '1m', target: 50 },   // Stay at 50 users
    { duration: '30s', target: 0 },   // Ramp down
  ],
  thresholds: {
    http_req_duration: ['p(95)<500'],  // 95% of requests < 500ms
    http_req_failed: ['rate<0.01'],    // Error rate < 1%
  },
};

export default function () {
  // State Load Test
  const stateRes = http.get('http://localhost:3002/api/sdk/v1/state/tenant-1');
  check(stateRes, {
    'state load status 200': (r) => r.status === 200,
    'state load time < 200ms': (r) => r.timings.duration < 200,
  });

  // Checkpoint Validation Test
  const checkpointRes = http.post(
    'http://localhost:3002/api/sdk/v1/checkpoints/CP-UC/validate',
    JSON.stringify({ context: { userId: 'user-1' } }),
    { headers: { 'Content-Type': 'application/json' } }
  );
  check(checkpointRes, {
    'checkpoint validation status 200': (r) => r.status === 200,
    'checkpoint validation time < 300ms': (r) => r.timings.duration < 300,
  });

  sleep(1);
}
```

### 12.5 Test Coverage Requirements

| Bereich | Minimum Coverage | Ziel Coverage |
|---------|------------------|---------------|
| Komponenten | 80% | 90% |
| Hooks | 85% | 95% |
| Services | 90% | 95% |
| API Endpoints | 90% | 95% |
| State Management | 85% | 95% |
| Checkpoint Logic | 95% | 100% |
| **Gesamt** | **85%** | **92%** |

---

## 13. Dokumentation

### 13.1 Benutzerhandbuch

#### Inhaltsverzeichnis

1. **Erste Schritte**
   - SDK aktivieren
   - Dashboard Übersicht
   - Navigation verstehen

2. **Phase 1: Compliance Assessment**
   - 1.1 Use Case Workshop durchführen
   - 1.2 System Screening starten
   - 1.3 Compliance Module zuweisen
   - 1.4 Requirements prüfen
   - 1.5 Controls definieren
   - 1.6 Evidence hochladen
   - 1.7 Audit Checklist erstellen
   - 1.8 Risk Matrix ausfüllen

3. **Phase 2: Dokumentengenerierung**
   - 2.1 AI Act Klassifizierung
   - 2.2 Pflichtenübersicht verstehen
   - 2.3 DSFA erstellen
   - 2.4 TOMs auswählen
   - 2.5 Löschfristen festlegen
   - 2.6 Verarbeitungsverzeichnis pflegen
   - 2.7 Rechtliche Vorlagen nutzen
   - 2.8 Cookie Banner konfigurieren
   - 2.9 Einwilligungen tracken
   - 2.10 DSR Portal einrichten
   - 2.11 Escalations konfigurieren

4. **Command Bar**
   - Befehle verwenden
   - Tastaturkürzel
   - Suche und RAG

5. **Export & Berichte**
   - PDF Export
   - ZIP Export
   - Audit-Berichte

6. **FAQ & Troubleshooting**

### 13.2 API-Dokumentation

#### OpenAPI Specification (Auszug)

```yaml
openapi: 3.1.0
info:
  title: AI Compliance SDK API
  version: 1.0.0
  description: API für das AI Compliance SDK

servers:
  - url: /api/sdk/v1
    description: SDK API v1

paths:
  /state/{tenantId}:
    get:
      summary: Kompletten State laden
      tags: [State Management]
      parameters:
        - name: tenantId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: State erfolgreich geladen
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SDKState'
        '404':
          description: Tenant nicht gefunden

  /state/save:
    post:
      summary: State speichern
      tags: [State Management]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tenantId:
                  type: string
                state:
                  $ref: '#/components/schemas/SDKState'
      responses:
        '200':
          description: State erfolgreich gespeichert

  /checkpoints/{id}/validate:
    post:
      summary: Checkpoint validieren
      tags: [Checkpoints]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            enum: [CP-UC, CP-SCAN, CP-MOD, CP-REQ, CP-CTRL, CP-EVI, CP-CHK, CP-RISK, CP-AI, CP-OBL, CP-DSFA, CP-TOM, CP-RET, CP-VVT, CP-DOC, CP-COOK, CP-CONS, CP-DSR, CP-ESC]
      responses:
        '200':
          description: Validierungsergebnis
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckpointStatus'

  /screening/start:
    post:
      summary: SBOM + Security Scan starten
      tags: [Screening]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                repositoryUrl:
                  type: string
                  format: uri
                branch:
                  type: string
                  default: main
                scanTypes:
                  type: array
                  items:
                    type: string
                    enum: [sbom, security, license]
      responses:
        '202':
          description: Scan gestartet
          content:
            application/json:
              schema:
                type: object
                properties:
                  scanId:
                    type: string
                  status:
                    type: string
                    enum: [pending, running]

  /generate/dsfa:
    post:
      summary: DSFA generieren
      tags: [Document Generation]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                useCaseId:
                  type: string
                includeRiskAssessment:
                  type: boolean
                language:
                  type: string
                  enum: [de, en]
                  default: de
      responses:
        '200':
          description: DSFA erfolgreich generiert
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DSFA'

components:
  schemas:
    SDKState:
      type: object
      properties:
        version:
          type: string
        tenantId:
          type: string
        currentPhase:
          type: integer
          enum: [1, 2]
        currentStep:
          type: string
        completedSteps:
          type: array
          items:
            type: string
        checkpoints:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/CheckpointStatus'
        useCases:
          type: array
          items:
            $ref: '#/components/schemas/UseCaseAssessment'
        # ... weitere Felder

    CheckpointStatus:
      type: object
      properties:
        checkpointId:
          type: string
        passed:
          type: boolean
        validatedAt:
          type: string
          format: date-time
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'

    ValidationError:
      type: object
      properties:
        ruleId:
          type: string
        field:
          type: string
        message:
          type: string
        severity:
          type: string
          enum: [ERROR, WARNING, INFO]
```

### 13.3 Entwickler-Dokumentation

#### Architektur-Übersicht

```
┌─────────────────────────────────────────────────────────────────┐
│                        FRONTEND (Next.js)                        │
├─────────────────────────────────────────────────────────────────┤
│  Pages (/sdk/*)  │  Components  │  Hooks  │  State (Context)   │
└────────┬────────────────────────────────────────────────────────┘
         │
         │ HTTP/REST
         ▼
┌─────────────────────────────────────────────────────────────────┐
│                    API Layer (Next.js Route Handlers)           │
├─────────────────────────────────────────────────────────────────┤
│  /api/sdk/v1/*  │  Authentication  │  Rate Limiting  │  CORS   │
└────────┬────────────────────────────────────────────────────────┘
         │
         │ Internal HTTP
         ▼
┌─────────────────────────────────────────────────────────────────┐
│                      BACKEND (Go/Gin)                           │
├─────────────────────────────────────────────────────────────────┤
│  Handlers  │  Services  │  UCCA Framework  │  LLM Integration  │
└────────┬────────────────────────────────────────────────────────┘
         │
         │ SQL/Cache
         ▼
┌─────────────────────────────────────────────────────────────────┐
│                      DATA LAYER                                  │
├─────────────────────────────────────────────────────────────────┤
│  PostgreSQL  │  Valkey/Redis  │  MinIO  │  Qdrant (Vector DB)  │
└─────────────────────────────────────────────────────────────────┘
```

#### Neue Komponente erstellen

```typescript
// 1. Erstelle die Komponente in components/sdk/
// components/sdk/MyComponent/MyComponent.tsx

import { useSDK } from '@/lib/sdk/context';

interface MyComponentProps {
  title: string;
  onAction: () => void;
}

export function MyComponent({ title, onAction }: MyComponentProps) {
  const { state, dispatch } = useSDK();

  return (
    <div className="p-4 bg-white rounded-lg shadow">
      <h2 className="text-xl font-semibold">{title}</h2>
      <p>Current Step: {state.currentStep}</p>
      <button
        onClick={onAction}
        className="mt-4 px-4 py-2 bg-blue-600 text-white rounded"
      >
        Action
      </button>
    </div>
  );
}

// 2. Exportiere in index.ts
// components/sdk/MyComponent/index.ts
export { MyComponent } from './MyComponent';

// 3. Verwende in einer Page
// app/(admin)/sdk/my-page/page.tsx
import { MyComponent } from '@/components/sdk/MyComponent';

export default function MyPage() {
  return (
    <MyComponent
      title="Meine Seite"
      onAction={() => console.log('clicked')}
    />
  );
}
```

#### Neuen API-Endpoint hinzufügen

```typescript
// app/api/sdk/v1/my-endpoint/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function GET(request: NextRequest) {
  try {
    const tenantId = request.headers.get('x-tenant-id');

    // Backend aufrufen
    const backendUrl = process.env.SDK_BACKEND_URL;
    const response = await fetch(`${backendUrl}/my-endpoint`, {
      headers: {
        'X-Tenant-ID': tenantId,
      },
    });

    const data = await response.json();

    return NextResponse.json(data);
  } catch (error) {
    return NextResponse.json(
      { error: 'Internal Server Error' },
      { status: 500 }
    );
  }
}

export async function POST(request: NextRequest) {
  try {
    const body = await request.json();

    // Validierung
    if (!body.requiredField) {
      return NextResponse.json(
        { error: 'requiredField is required' },
        { status: 400 }
      );
    }

    // Backend aufrufen
    const backendUrl = process.env.SDK_BACKEND_URL;
    const response = await fetch(`${backendUrl}/my-endpoint`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(body),
    });

    const data = await response.json();

    return NextResponse.json(data);
  } catch (error) {
    return NextResponse.json(
      { error: 'Internal Server Error' },
      { status: 500 }
    );
  }
}
```

---

## 14. Offene Fragen & Klärungsbedarf

### Fragen die VOR Sprint 1 geklärt werden müssen

| # | Frage | Bereich | Auswirkung | Entscheidungsträger |
|---|-------|---------|------------|---------------------|
| 1 | **Backend-Verbindung für Screening**: Wie verbindet sich der SDK mit dem Kunden-Backend? Welche Authentifizierung wird verwendet? | Architektur | Blockiert Screening-Implementierung | Tech Lead + Security |
| 2 | **Welche Systeme sollen gescannt werden können?** (Git Repos, Container Registries, Cloud APIs) | Screening | Bestimmt SBOM-Generierungs-Strategie | Product Owner |
| 3 | **Multi-Use-Case Handling**: Sollen alle Use Cases denselben Compliance-Flow durchlaufen? Oder gibt es einen übergeordneten "Projekt"-Kontext? | Datenmodell | Beeinflusst State-Struktur | Product Owner |

### Fragen die VOR Sprint 4 geklärt werden müssen

| # | Frage | Bereich | Auswirkung | Entscheidungsträger |
|---|-------|---------|------------|---------------------|
| 4 | **Cookie Banner Integration**: Welche Plattformen sollen unterstützt werden? (Web, iOS, Android) | Cookie Banner | Bestimmt Umfang der Implementierung | Product Owner |
| 5 | **Soll ein fertiger Code-Snippet generiert werden?** Oder nur Konfiguration? | Cookie Banner | Frontend-Aufwand | Tech Lead |

### Fragen die VOR Go-Live geklärt werden müssen

| # | Frage | Bereich | Auswirkung | Entscheidungsträger |
|---|-------|---------|------------|---------------------|
| 6 | **Subscription Tiers**: Welche Features sind in welchem Tier verfügbar? | Business | Feature Flags Implementierung | Product Owner + Business |
| 7 | **Gibt es Nutzungslimits?** (z.B. max. Use Cases, Scans pro Monat) | Business | Rate Limiting Implementierung | Product Owner + Business |

### Zusätzliche technische Fragen

| # | Frage | Bereich | Auswirkung | Entscheidungsträger |
|---|-------|---------|------------|---------------------|
| 8 | **LLM Provider für RAG/Generierung**: Ollama, Anthropic, oder OpenAI als Standard? | Infrastruktur | Kosten, Performance, Datenschutz | Tech Lead + DSB |
| 9 | **Datenhoheit**: Wo werden generierte Dokumente gespeichert? On-Premise Option? | Infrastruktur | Speicher-Architektur | Tech Lead + Security |
| 10 | **Audit Trail**: Wie granular soll die Änderungsverfolgung sein? | Compliance | Datenbankschema | DSB + Tech Lead |

### Empfohlene Klärungsreihenfolge

```
Woche 0 (vor Projektstart):
├── Frage 1-3 klären (Architektur-Entscheidungen)
├── Frage 8 klären (LLM Provider)
└── Frage 9 klären (Datenhoheit)

Sprint 1-2:
├── Frage 10 klären (Audit Trail)
└── Dokumentation der Entscheidungen

Sprint 3 (vor Phase 2):
├── Frage 4-5 klären (Cookie Banner)
└── Feature-Scope finalisieren

Sprint 5 (vor Go-Live):
├── Frage 6-7 klären (Subscription Tiers)
└── Pricing-Modell integrieren
```

---

## 15. Akzeptanzkriterien

### Funktionale Anforderungen

| # | Kriterium | Testmethode | Status |
|---|-----------|-------------|--------|
| F1 | Nutzer kann kompletten Flow in einer Session durchlaufen | E2E Test | ⬜ |
| F2 | Checkpoints blockieren korrekt bei fehlenden Daten | Integration Test | ⬜ |
| F3 | Command Bar funktioniert in jedem Schritt | E2E Test | ⬜ |
| F4 | Alle 11 Dokument-Typen werden korrekt generiert | Unit + Integration | ⬜ |
| F5 | Export enthält alle relevanten Daten (PDF, ZIP, JSON) | Integration Test | ⬜ |
| F6 | SBOM-Generierung funktioniert für Git Repositories | Integration Test | ⬜ |
| F7 | Security Scan identifiziert bekannte CVEs | Integration Test | ⬜ |
| F8 | Risk Matrix berechnet korrekte Scores | Unit Test | ⬜ |
| F9 | Cookie Banner generiert funktionierenden Code | Manual + E2E | ⬜ |
| F10 | DSR Portal kann Anfragen entgegennehmen | E2E Test | ⬜ |

### Nicht-funktionale Anforderungen

| # | Kriterium | Zielwert | Testmethode | Status |
|---|-----------|----------|-------------|--------|
| NF1 | Page Load Time | < 2s | Lighthouse | ⬜ |
| NF2 | State Save Latency | < 500ms | Performance Test | ⬜ |
| NF3 | Checkpoint Validation | < 300ms | Performance Test | ⬜ |
| NF4 | Document Generation | < 30s | Performance Test | ⬜ |
| NF5 | Concurrent Users | 50+ | Load Test | ⬜ |
| NF6 | Error Rate | < 1% | Monitoring | ⬜ |
| NF7 | Test Coverage | > 85% | Jest/Vitest | ⬜ |
| NF8 | Accessibility | WCAG 2.1 AA | axe-core | ⬜ |
| NF9 | Mobile Responsive | iOS/Android | Manual Test | ⬜ |
| NF10 | Browser Support | Chrome, Firefox, Safari, Edge | E2E Test | ⬜ |

### Sicherheitsanforderungen

| # | Kriterium | Standard | Status |
|---|-----------|----------|--------|
| S1 | Authentifizierung | OAuth 2.0 / OIDC | ⬜ |
| S2 | Autorisierung | RBAC mit 4 Rollen | ⬜ |
| S3 | Datenverschlüsselung at Rest | AES-256 | ⬜ |
| S4 | Datenverschlüsselung in Transit | TLS 1.3 | ⬜ |
| S5 | Input Validation | OWASP Guidelines | ⬜ |
| S6 | Audit Logging | Alle Schreiboperationen | ⬜ |
| S7 | Rate Limiting | 100 req/min pro User | ⬜ |
| S8 | CSRF Protection | Token-basiert | ⬜ |
| S9 | XSS Prevention | CSP Headers | ⬜ |
| S10 | SQL Injection Prevention | Parameterized Queries | ⬜ |

---

## Anhang

### A. Glossar

| Begriff | Definition |
|---------|------------|
| **DSFA** | Datenschutz-Folgenabschätzung (Art. 35 DSGVO) |
| **TOM** | Technische und Organisatorische Maßnahmen |
| **VVT** | Verarbeitungsverzeichnis (Art. 30 DSGVO) |
| **DSR** | Data Subject Request (Betroffenenrechte) |
| **SBOM** | Software Bill of Materials |
| **UCCA** | Unified Compliance Control Architecture |
| **RAG** | Retrieval-Augmented Generation |
| **CVE** | Common Vulnerabilities and Exposures |
| **CVSS** | Common Vulnerability Scoring System |

### B. Referenzen

- [EU AI Act](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:52021PC0206)
- [DSGVO](https://eur-lex.europa.eu/eli/reg/2016/679/oj)
- [NIS2 Directive](https://eur-lex.europa.eu/eli/dir/2022/2555)
- [CycloneDX SBOM Standard](https://cyclonedx.org/)
- [SPDX Standard](https://spdx.dev/)

### C. Änderungshistorie

| Version | Datum | Autor | Änderungen |
|---------|-------|-------|------------|
| 1.0.0 | 2026-02-03 | AI Compliance Team | Initiale Version |

---

*Dieses Dokument wurde erstellt für das AI Compliance SDK Projekt.*