breakpilot-pwa/AI_COMPLIANCE_SDK_IMPLEMENTATION_PLAN.md

AI Compliance SDK - Vollständige Implementierungsspezifikation

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

---

Inhaltsverzeichnis

1. Executive Summary
2. SDK-Architektur Übersicht
3. Logische Navigationsstruktur
4. Datenfluss & Abhängigkeiten
5. Checkpoint-System
6. Unified Command Bar
7. State Management
8. API-Struktur
9. UI-Komponenten
10. TypeScript Interfaces
11. Implementierungs-Roadmap
12. Testplan
13. Dokumentation
14. Offene Fragen & Klärungsbedarf
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

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)

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

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

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

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

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

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

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

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

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

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

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

// 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)

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

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

// 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
• DSGVO
• NIS2 Directive
• CycloneDX SBOM Standard
• SPDX Standard

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.