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

# Analyse-Module (Paket 2)

Die Analyse-Phase umfasst 7 Module, die den Compliance-Status systematisch erfassen und bewerten. Alle Module sind vollstaendig backend-persistent und bieten CRUD-Operationen ueber die REST-API.

---

## Uebersicht

| Modul | Checkpoint | Reviewer | Status |
|-------|-----------|----------|--------|
| [Requirements](#requirements) | CP-REQ (REQUIRED) | NONE | 100% |
| [Controls](#controls) | CP-CTRL (REQUIRED) | DSB | 100% |
| [Evidence](#evidence) | CP-EVI (RECOMMENDED) | NONE | 100% |
| [Risk Matrix](#risk-matrix) | CP-RISK (REQUIRED) | DSB | 100% |
| [AI Act Klassifizierung](#ai-act) | CP-AI (REQUIRED) | LEGAL | 100% |
| [Audit Checklist](#audit-checklist) | CP-CHK (RECOMMENDED) | NONE | 100% |
| [Audit Report](#audit-report) | CP-AREP (REQUIRED) | NONE | 100% |

---

## Requirements

**Route:** `/sdk/requirements` | **Rechtsgrundlage:** Art. 5, 24, 25 DSGVO

### Funktionen

- Automatische Ableitung von Anforderungen aus aktivierten Modulen
- Backend-persistente CRUD-Operationen (Erstellen, Lesen, Aktualisieren, Loeschen)
- Status-Workflow: `NOT_STARTED` → `IN_PROGRESS` → `IMPLEMENTED` → `VERIFIED`
- Fehlerbehandlung mit automatischem Rollback bei Backend-Fehler
- KI-gestuetzte Interpretation mit RAG-Rechtskontext
- Filterung und Volltextsuche
- Paginierung fuer grosse Datensaetze (500+ Anforderungen)

### API-Endpoints

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/api/compliance/requirements` | Paginierte Liste (page, page_size, regulation_code, status, search) |
| `GET` | `/api/compliance/requirements/{id}` | Detail mit optionalem `?include_legal_context=true` |
| `POST` | `/api/compliance/requirements` | Neue Anforderung erstellen (regulation_id, article, title, priority) |
| `PUT` | `/api/compliance/requirements/{id}` | Status/Details aktualisieren |
| `DELETE` | `/api/compliance/requirements/{id}` | Anforderung loeschen |

### DB-Tabellen

- `compliance_requirements` (read/write)

### RAG-Collections

- `bp_compliance_recht` — Deutsche Gesetze
- `bp_compliance_ce` — EU-Verordnungen

---

## Controls

**Route:** `/sdk/controls` | **Rechtsgrundlage:** Art. 32 DSGVO

### Funktionen

- Definition technischer und organisatorischer Kontrollmassnahmen
- Status-Tracking: pass, partial, fail, n/a, planned
- Evidence-Linking: Verknuepfung mit Nachweisen inkl. Gueltigkeits-Badge
- Navigation zur Evidence-Seite mit vorausgewaehltem Control
- Domänen-basierte Gruppierung (gov, priv, iam, crypto, sdlc, ops, ai, cra, aud)
- Review-Workflow mit Verantwortlichem und naechstem Review-Datum

### API-Endpoints

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/api/compliance/controls` | Alle Controls (domain, status, search Filter) |
| `GET` | `/api/compliance/controls/paginated` | Paginierte Liste |
| `GET` | `/api/compliance/controls/{control_id}` | Detail mit Evidence-Count |
| `PUT` | `/api/compliance/controls/{control_id}` | Control aktualisieren |
| `PUT` | `/api/compliance/controls/{control_id}/review` | Review durchfuehren |

### DB-Tabellen

- `compliance_controls` (read/write)

---

## Evidence

**Route:** `/sdk/evidence` | **Rechtsgrundlage:** Art. 5 Abs. 2 DSGVO

### Funktionen

- Sammlung und Verwaltung von Compliance-Nachweisen
- Server-seitige Pagination (`page`, `limit` Query-Parameter)
- Gueltigkeits-Tracking (valid_from, valid_until)
- Status: valid, expired, pending, failed
- Verknuepfung mit Controls
- Upload von Dateien als Nachweise

### API-Endpoints

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/api/compliance/evidence` | Paginierte Liste (`page`, `limit`, `control_id` Filter) |
| `POST` | `/api/compliance/evidence` | Neuen Nachweis erstellen |
| `PUT` | `/api/compliance/evidence/{id}` | Nachweis aktualisieren |

### DB-Tabellen

- `compliance_evidence` (write)

---

## Risk Matrix

**Route:** `/sdk/risks` | **Rechtsgrundlage:** Art. 35 DSGVO

### Funktionen

- 5x5 Risikomatrix (Wahrscheinlichkeit x Auswirkung)
- Inherent Risk vs. Residual Risk mit visuellem Vergleich
- Status-Workflow: `IDENTIFIED` → `ASSESSED` → `MITIGATED` → `ACCEPTED` → `CLOSED`
- Expandierbare Mitigations-Sektion pro Risiko
- Mitigating Controls mit Status-Badge und Beschreibung
- Automatische Risiko-Level-Berechnung (LOW/MEDIUM/HIGH/CRITICAL)
- Backend-Persistenz fuer Status-Aenderungen

### API-Endpoints

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/api/compliance/risks` | Alle Risiken |
| `POST` | `/api/compliance/risks` | Neues Risiko erstellen |
| `PUT` | `/api/compliance/risks/{risk_id}` | Risiko aktualisieren (inkl. Status) |

### Risiko-Berechnung

```
Score = Likelihood × Impact

Score >= 20  →  CRITICAL (rot)
Score >= 12  →  HIGH (orange)
Score >= 6   →  MEDIUM (gelb)
Score < 6    →  LOW (gruen)
```

### DB-Tabellen

- `compliance_risks` (write)

---

## AI Act

**Route:** `/sdk/ai-act` | **Rechtsgrundlage:** EU AI Act Art. 6-9

### Funktionen

- KI-System-Registrierung mit vollstaendiger Backend-Persistenz (CRUD)
- Risikopyramide (Minimal → Begrenzt → Hoch → Verboten)
- KI-gestuetzte Risikobewertung mit Rule-Based-Fallback
- Automatische Ableitung von AI Act Pflichten je Risikokategorie
- Filterung nach Klassifizierung, Status und Sektor
- Neues DB-Modell: `compliance_ai_systems`

### API-Endpoints

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/api/compliance/ai/systems` | Alle KI-Systeme (classification, status, sector Filter) |
| `POST` | `/api/compliance/ai/systems` | Neues KI-System registrieren |
| `GET` | `/api/compliance/ai/systems/{id}` | Detail |
| `PUT` | `/api/compliance/ai/systems/{id}` | KI-System aktualisieren |
| `DELETE` | `/api/compliance/ai/systems/{id}` | KI-System loeschen |
| `POST` | `/api/compliance/ai/systems/{id}/assess` | AI Act Risikobewertung durchfuehren |

### Risikokategorien & Pflichten

| Kategorie | AI Act Artikel | Pflichten |
|-----------|---------------|-----------|
| **Verboten** | Art. 5 | Einsatz verboten |
| **Hochrisiko** | Art. 6-15 | 8 Pflichten (Risikomanagement, Daten-Governance, Dokumentation, ...) |
| **Begrenztes Risiko** | Art. 52 | Transparenzpflicht, Kennzeichnung |
| **Minimales Risiko** | Art. 69 | Freiwillige Verhaltenskodizes |

### DB-Tabellen

- `compliance_ai_systems` (read/write)

---

## Audit Checklist

**Route:** `/sdk/audit-checklist` | **Rechtsgrundlage:** Art. 5 Abs. 2 DSGVO

### Funktionen

- Automatische Generierung der Checkliste aus Requirements und Controls
- Session-Management: Draft → In Progress → Completed → Archived
- Interaktiver Sign-Off-Workflow mit digitalem Signatur-Hash (SHA-256)
- PDF-Download in Deutsch oder Englisch
- Session-History: Anzeige vergangener Audit-Sitzungen
- JSON-Export der Checkliste

### API-Endpoints

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/api/compliance/audit/sessions` | Alle Audit-Sitzungen |
| `POST` | `/api/compliance/audit/sessions` | Neue Sitzung erstellen |
| `GET` | `/api/compliance/audit/checklist/{sessionId}` | Checkliste einer Sitzung |
| `PUT` | `/api/compliance/audit/checklist/{sessionId}/items/{reqId}/sign-off` | Pruefpunkt abzeichnen |
| `GET` | `/api/compliance/audit/sessions/{sessionId}/report/pdf` | PDF-Report generieren |

### DB-Tabellen

- `compliance_audit_sessions` (read/write)
- `compliance_audit_signoffs` (write)

---

## Audit Report

**Route:** `/sdk/audit-report` | **Rechtsgrundlage:** Art. 5 Abs. 2 DSGVO

### Funktionen

- Uebersicht aller Audit-Sitzungen mit Status-Badges
- Detail-Seite pro Sitzung (`/sdk/audit-report/{sessionId}`)
  - Session-Metadaten (Auditor, Zeitraum, Status)
  - Fortschrittsbalken (konform/nicht konform/ausstehend)
  - Interaktive Checklist-Items mit Sign-Off
  - Notizen-Bearbeitung pro Pruefpunkt
  - PDF-Download mit Sprachauswahl (DE/EN)
- Click-Navigation von der Uebersicht zur Detail-Seite
- Generiert: Audit-Report (PDF)

### API-Endpoints

Nutzt dieselben Backend-Endpoints wie Audit Checklist (s.o.).

### DB-Tabellen

- `compliance_audit_sessions` (write)

---

## Datenfluss

```mermaid
graph LR
    A[Requirements] --> B[Controls]
    B --> C[Evidence]
    C --> D[Risk Matrix]
    D --> E[AI Act]
    E --> F[Audit Checklist]
    F --> G[Audit Report]
```

Jedes Modul baut auf dem vorherigen auf. Die Reihenfolge ist durch Prerequisite-Steps im SDK-Flow erzwungen.