# Breakpilot Compliance & Audit Framework

## Uebersicht

Enterprise-ready GRC (Governance, Risk, Compliance) Framework fuer die Breakpilot EdTech-Plattform.

### Kernfunktionen

| Feature | Status | Beschreibung |
|---------|--------|--------------|
| **19 EU-Regulations** | Aktiv | DSGVO, AI Act, CRA, NIS2, Data Act, etc. |
| **558 Requirements** | Aktiv | Automatisch extrahiert aus EUR-Lex + BSI-TR PDFs |
| **44 Controls** | Aktiv | Technische und organisatorische Massnahmen |
| **474 Control-Mappings** | Aktiv | Keyword-basiertes Auto-Mapping |
| **KI-Interpretation** | Aktiv | Claude API fuer Anforderungsanalyse |
| **Executive Dashboard** | Aktiv | Ampel-Status, Trends, Top-Risiken |

## Architektur

```
backend/compliance/
├── api/
│   ├── routes.py         # 52 FastAPI Endpoints
│   └── schemas.py        # Pydantic Response Models
├── db/
│   ├── models.py         # SQLAlchemy Models
│   └── repository.py     # CRUD Operations
├── data/
│   ├── regulations.py    # 19 Regulations Seed
│   ├── controls.py       # 44 Controls Seed
│   ├── requirements.py   # Requirements Seed
│   └── service_modules.py # 30 Service-Module
├── services/
│   ├── ai_compliance_assistant.py  # Claude Integration
│   ├── llm_provider.py             # LLM Abstraction Layer
│   ├── pdf_extractor.py            # BSI-TR PDF Parser
│   └── regulation_scraper.py       # EUR-Lex Scraper
└── tests/                # Pytest Tests (in /backend/tests/)
```

## Schnellstart

### 1. Backend starten

```bash
cd backend
docker-compose up -d
# ODER
uvicorn main:app --reload --port 8000
```

### 2. Datenbank initialisieren

```bash
# Regulations, Controls, Requirements seeden
curl -X POST http://localhost:8000/api/v1/compliance/seed \
  -H "Content-Type: application/json" \
  -d '{"force": false}'

# Service-Module seeden
curl -X POST http://localhost:8000/api/v1/compliance/modules/seed \
  -H "Content-Type: application/json" \
  -d '{"force": false}'
```

### 3. KI-Interpretation aktivieren

```bash
# Vault-gesteuerte API-Keys
export VAULT_ADDR=http://localhost:8200
export VAULT_TOKEN=breakpilot-dev-token

# Status pruefen
curl http://localhost:8000/api/v1/compliance/ai/status

# Einzelne Anforderung interpretieren
curl -X POST http://localhost:8000/api/v1/compliance/ai/interpret \
  -H "Content-Type: application/json" \
  -d '{"requirement_id": "REQ-ID", "save_to_db": true}'
```

## API-Endpoints

### Dashboard & Executive View

| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/api/v1/compliance/dashboard` | Dashboard-Daten mit Scores |
| GET | `/api/v1/compliance/dashboard/executive` | Executive Dashboard (Ampel, Trends) |
| GET | `/api/v1/compliance/dashboard/trend` | Score-Trend (12 Monate) |

### Regulations & Requirements

| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/api/v1/compliance/regulations` | Alle 19 Regulations |
| GET | `/api/v1/compliance/regulations/{code}` | Eine Regulation |
| GET | `/api/v1/compliance/requirements` | 558 Requirements (paginiert) |
| GET | `/api/v1/compliance/requirements/{id}` | Einzelnes Requirement |

### Controls & Mappings

| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/api/v1/compliance/controls` | Alle 44 Controls |
| GET | `/api/v1/compliance/controls/{id}` | Ein Control |
| GET | `/api/v1/compliance/controls/by-domain/{domain}` | Controls nach Domain |
| GET | `/api/v1/compliance/mappings` | 474 Control-Mappings |

### KI-Features

| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/api/v1/compliance/ai/status` | LLM Provider Status |
| POST | `/api/v1/compliance/ai/interpret` | Requirement interpretieren |
| POST | `/api/v1/compliance/ai/batch` | Batch-Interpretation |
| POST | `/api/v1/compliance/ai/suggest-controls` | Control-Vorschlaege |

### Scraper & Import

| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| POST | `/api/v1/compliance/scraper/fetch` | EUR-Lex Live-Fetch |
| POST | `/api/v1/compliance/scraper/extract-pdf` | BSI-TR PDF Extraktion |
| GET | `/api/v1/compliance/scraper/status` | Scraper-Status |

### Evidence & Risks

| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/api/v1/compliance/evidence` | Alle Nachweise |
| POST | `/api/v1/compliance/evidence/collect` | CI/CD Evidence Upload |
| GET | `/api/v1/compliance/risks` | Risk Register |
| GET | `/api/v1/compliance/risks/matrix` | Risk Matrix View |

## Datenmodell

### RegulationDB

```python
class RegulationDB(Base):
    id: str                    # UUID
    code: str                  # "GDPR", "AIACT", etc.
    name: str                  # Kurzname
    full_name: str             # Vollstaendiger Name
    regulation_type: enum      # eu_regulation, bsi_standard, etc.
    source_url: str            # EUR-Lex URL
    effective_date: date       # Inkrafttreten
```

### RequirementDB

```python
class RequirementDB(Base):
    id: str                    # UUID
    regulation_id: str         # FK zu Regulation
    article: str               # "Art. 32"
    paragraph: str             # "(1)(a)"
    title: str                 # Kurztitel
    requirement_text: str      # Original-Text
    breakpilot_interpretation: str  # KI-Interpretation
    priority: int              # 1-5
```

### ControlDB

```python
class ControlDB(Base):
    id: str                    # UUID
    control_id: str            # "PRIV-001"
    domain: enum               # gov, priv, iam, crypto, sdlc, ops, ai
    control_type: enum         # preventive, detective, corrective
    title: str                 # Kontroll-Titel
    pass_criteria: str         # Messbare Kriterien
    code_reference: str        # z.B. "middleware/pii_redactor.py:45"
    status: enum               # pass, partial, fail, planned
```

## Frontend-Integration

### Compliance Dashboard

```
/admin/compliance           # Haupt-Dashboard
/admin/compliance/controls  # Control Catalogue
/admin/compliance/evidence  # Evidence Management
/admin/compliance/risks     # Risk Matrix
/admin/compliance/scraper   # Regulation Scraper
/admin/compliance/audit-workspace  # Audit Workspace
```

### Neue Komponenten (Sprint 1+2)

- `ComplianceTrendChart.tsx` - Recharts-basierter Trend-Chart
- `TrafficLightIndicator.tsx` - Ampel-Status Anzeige
- `LanguageSwitch.tsx` - DE/EN Terminologie-Umschaltung
- `GlossaryTooltip.tsx` - Erklaerungen fuer Fachbegriffe

### i18n-System

```typescript
import { getTerm, Language } from '@/lib/compliance-i18n'

// Nutzung
const label = getTerm('de', 'control')  // "Massnahme"
const label = getTerm('en', 'control')  // "Control"
```

## Tests

```bash
# Alle Compliance-Tests ausfuehren
cd backend
pytest tests/test_compliance_*.py -v

# Einzelne Test-Dateien
pytest tests/test_compliance_api.py -v      # API Endpoints
pytest tests/test_compliance_ai.py -v       # KI-Integration
pytest tests/test_compliance_repository.py -v  # Repository
pytest tests/test_compliance_pdf_extractor.py -v  # PDF Parser
```

## Umgebungsvariablen

```bash
# LLM Provider
COMPLIANCE_LLM_PROVIDER=anthropic  # oder "mock" fuer Tests
ANTHROPIC_API_KEY=sk-ant-...       # Falls nicht ueber Vault

# Vault Integration
VAULT_ADDR=http://localhost:8200
VAULT_TOKEN=breakpilot-dev-token

# Datenbank
DATABASE_URL=postgresql://user:pass@localhost:5432/breakpilot
```

## Regulations-Uebersicht

| Code | Name | Typ | Requirements |
|------|------|-----|--------------|
| GDPR | DSGVO | EU-Verordnung | ~50 |
| AIACT | AI Act | EU-Verordnung | ~80 |
| CRA | Cyber Resilience Act | EU-Verordnung | ~60 |
| NIS2 | NIS2-Richtlinie | EU-Richtlinie | ~40 |
| DATAACT | Data Act | EU-Verordnung | ~35 |
| DGA | Data Governance Act | EU-Verordnung | ~30 |
| DSA | Digital Services Act | EU-Verordnung | ~25 |
| EUCSA | EU Cybersecurity Act | EU-Verordnung | ~20 |
| EAA | European Accessibility Act | EU-Richtlinie | ~15 |
| BSI-TR-03161-1 | Mobile Anwendungen Teil 1 | BSI-Standard | ~30 |
| BSI-TR-03161-2 | Mobile Anwendungen Teil 2 | BSI-Standard | ~100 |
| BSI-TR-03161-3 | Mobile Anwendungen Teil 3 | BSI-Standard | ~50 |
| ... | 7 weitere | ... | ~50 |

## Control-Domains

| Domain | Beschreibung | Anzahl Controls |
|--------|--------------|-----------------|
| `gov` | Governance & Organisation | 5 |
| `priv` | Datenschutz & Privacy | 7 |
| `iam` | Identity & Access Management | 5 |
| `crypto` | Kryptografie | 4 |
| `sdlc` | Secure Development | 6 |
| `ops` | Betrieb & Monitoring | 5 |
| `ai` | KI-spezifisch | 5 |
| `cra` | CRA & Supply Chain | 4 |
| `aud` | Audit & Nachvollziehbarkeit | 3 |

## Erweiterungen

### Neue Regulation hinzufuegen

1. Eintrag in `data/regulations.py`
2. Requirements ueber Scraper importieren
3. Control-Mappings generieren

```bash
# EUR-Lex Regulation importieren
curl -X POST http://localhost:8000/api/v1/compliance/scraper/fetch \
  -H "Content-Type: application/json" \
  -d '{"regulation_code": "NEW_REG", "url": "https://eur-lex.europa.eu/..."}'
```

### Neues Control hinzufuegen

1. Eintrag in `data/controls.py`
2. Re-Seed ausfuehren
3. Mappings werden automatisch generiert

## Multi-Projekt-Architektur (Migration 039)

Jeder Tenant kann mehrere Compliance-Projekte anlegen. Neue Tabelle `compliance_projects`, `sdk_states` erweitert um `project_id`.

### Projekt-API Endpoints

| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/api/v1/projects` | Alle Projekte des Tenants |
| POST | `/api/v1/projects` | Neues Projekt erstellen |
| GET | `/api/v1/projects/{id}` | Einzelnes Projekt |
| PATCH | `/api/v1/projects/{id}` | Projekt aktualisieren |
| DELETE | `/api/v1/projects/{id}` | Projekt archivieren |

Siehe `compliance/api/project_routes.py` und `migrations/039_compliance_projects.sql`.

## Changelog

### v2.0 (2026-01-17)
- Executive Dashboard mit Ampel-Status
- Trend-Charts (Recharts)
- DE/EN Terminologie-Umschaltung
- 52 API-Endpoints
- 558 Requirements aus 19 Regulations
- 474 Auto-Mappings
- KI-Interpretation (Claude API)

### v1.0 (2026-01-16)
- Basis-Dashboard
- EUR-Lex Scraper
- BSI-TR PDF Parser
- Control Catalogue
- Evidence Management