feat(reporting+docs): tenant-ID-Validierung, Go-Tests, 4 MkDocs-Einzelseiten

- reporting_handlers.go: uuid.Nil-Check vor Store-Aufruf (→ 400) - reporting_handlers_test.go: 4 MissingTenantID-Tests (PASS) + 4 WithTenant-Tests (SKIP) - docs-src: requirements.md, controls.md, evidence.md, risks.md (je mit API, Schema, Tests) - mkdocs.yml: 4 neue Nav-Einträge + \n-Bug auf Zeile 91 behoben - compliance-kern.md: Link-Hinweise zu Detailseiten ergänzt Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-05 18:25:26 +01:00
parent 35576fb6f8
commit a1980cd12d
8 changed files with 680 additions and 1 deletions
--- a/docs-src/services/sdk-modules/compliance-kern.md
+++ b/docs-src/services/sdk-modules/compliance-kern.md
@@ -5,6 +5,9 @@ Vier Module bilden das technische Rückgrat der Compliance-Plattform:

 Sie sind miteinander verknüpft: Anforderungen erzeugen Controls → Controls verlangen Nachweise → Risiken werden durch Controls gemindert.

+> **Detailseiten** — Jedes Modul hat eine eigene Seite mit vollständiger API-Referenz und Schema:
+> [Anforderungen (CP-ANF)](requirements.md) · [Controls (CP-CTR)](controls.md) · [Nachweise (CP-NAC)](evidence.md) · [Risiken (CP-RSK)](risks.md)
+
 ---

 ## Überblick
--- a/docs-src/services/sdk-modules/controls.md
+++ b/docs-src/services/sdk-modules/controls.md
@@ -0,0 +1,126 @@
+# Controls (CP-CTR)
+
+Verwaltet technische und organisatorische Kontrollen (TOMs, Prozesse) und deren Prüfstatus.
+
+**Prefix:** `CP-CTR` · **Frontend:** `https://macmini:3007/sdk/controls`
+**Proxy:** `/api/sdk/v1/compliance/[[...path]]` → `backend-compliance:8002/compliance/...`
+
+---
+
+## Features
+
+- Domain-basierte Filterung (gov, priv, iam, crypto, sdlc, ops, ai, cra, aud)
+- Status-Tracking: pass / partial / fail / planned / n/a
+- Evidence-Count pro Control
+- KI-basierte Control-Vorschläge via RAG
+- Automatisierte Controls via CI/CD-Ingest
+
+---
+
+## Rechtsgrundlage
+
+| Artikel | Bezug |
+|---------|-------|
+| Art. 24 DSGVO | Verantwortlichkeit des Verantwortlichen |
+| Art. 32 DSGVO | Sicherheit der Verarbeitung (TOMs) |
+| Art. 9 AI Act | Risikomanagementsystem |
+
+---
+
+## Status-Enum
+
+| Wert | Bedeutung |
+|------|-----------|
+| `pass` | Vollständig implementiert und geprüft |
+| `partial` | Teilweise implementiert |
+| `fail` | Nicht bestanden |
+| `planned` | In Planung |
+| `n/a` | Nicht anwendbar |
+
+## Domain-Enum
+
+`gov` · `priv` · `iam` · `crypto` · `sdlc` · `ops` · `ai` · `cra` · `aud`
+
+---
+
+## API Endpoints
+
+| Methode | Pfad | Beschreibung |
+|---------|------|--------------|
+| `GET` | `/compliance/controls` | Liste mit Filtern (`domain`, `status`, `is_automated`, `search`) |
+| `GET` | `/compliance/controls/paginated` | Paginiert (`page`, `page_size`) |
+| `GET` | `/compliance/controls/{control_id}` | Einzelne Kontrolle + Evidence-Count |
+| `PUT` | `/compliance/controls/{control_id}` | Titel, Status, Notizen aktualisieren |
+| `PUT` | `/compliance/controls/{control_id}/review` | Kontrolle als geprüft markieren |
+| `GET` | `/compliance/controls/by-domain/{domain}` | Alle Controls einer Domain |
+
+### KI-Controls aus RAG vorschlagen
+
+```http
+POST /compliance/ai/suggest-controls
+{
+  "requirement_id": "uuid-der-anforderung"
+}
+```
+
+Gibt bis zu 5 KI-generierte Control-Vorschläge zurück:
+
+```json
+{
+  "requirement_id": "...",
+  "suggestions": [
+    {
+      "control_id": "GOV-KI-001",
+      "domain": "gov",
+      "title": "Datenschutzbeauftragter für KI-Systeme",
+      "description": "...",
+      "pass_criteria": "DSB nachweislich ernannt",
+      "is_automated": false,
+      "priority": 1,
+      "confidence_score": 0.87
+    }
+  ]
+}
+```
+
+---
+
+## Frontend
+
+**URL:** `https://macmini:3007/sdk/controls`
+
+Tabelle mit Domain-Tabs und Status-Badges. "KI-Controls aus RAG vorschlagen"-Button öffnet ein Modal mit Vorschlägen basierend auf einer ausgewählten Anforderung.
+
+---
+
+## Datenbankschema
+
+```sql
+compliance_controls (
+  id            UUID PRIMARY KEY,
+  control_id    VARCHAR UNIQUE,        -- z.B. "GOV-001"
+  domain        VARCHAR,               -- gov/priv/iam/...
+  control_type  VARCHAR,               -- technical/organizational
+  title         TEXT,
+  description   TEXT,
+  status        VARCHAR DEFAULT 'planned',
+  is_automated  BOOLEAN DEFAULT false,
+  evidence_count INTEGER DEFAULT 0,
+  last_review   TIMESTAMP,
+  notes         TEXT,
+  created_at    TIMESTAMP,
+  updated_at    TIMESTAMP
+)
+```
+
+---
+
+## Tests
+
+**Testdatei:** `backend-compliance/tests/test_control_routes.py`
+**Anzahl Tests:** 21 · **Status:** ✅ alle bestanden (Stand 2026-03-05)
+
+```bash
+cd backend-compliance
+python3 -m pytest tests/test_control_routes.py -v
+```
--- a/docs-src/services/sdk-modules/evidence.md
+++ b/docs-src/services/sdk-modules/evidence.md
@@ -0,0 +1,99 @@
+# Nachweise / Evidence (CP-NAC)
+
+Verknüpft Prüfnachweise mit Controls. Unterstützt manuelle Uploads sowie CI/CD-Automatisierung.
+
+**Prefix:** `CP-NAC` · **Frontend:** `https://macmini:3007/sdk/evidence`
+**Proxy:** `/api/sdk/v1/compliance/[[...path]]` → `backend-compliance:8002/compliance/...`
+
+---
+
+## Features
+
+- Manuelle Nachweis-Uploads (PDF, ZIP, ...)
+- CI/CD-Integration: Nachweise automatisch via Pipeline erfassen
+- Automatischer Control-Status-Update nach Nachweis-Ingest (`AutoRiskUpdater`)
+- CI-Nachweisstand-Abfrage pro Control
+
+---
+
+## Nachweistypen
+
+`test_results` · `audit_report` · `penetration_test` · `sast` · `dependency_scan` · `sbom` · `container_scan` · `secret_scan` · `code_review`
+
+---
+
+## Rechtsgrundlage
+
+| Artikel | Bezug |
+|---------|-------|
+| Art. 5 Abs. 2 DSGVO | Rechenschaftspflicht |
+| Art. 24 DSGVO | Nachweis der Compliance |
+| Art. 32 DSGVO | Sicherheitsmaßnahmen dokumentieren |
+
+---
+
+## API Endpoints
+
+| Methode | Pfad | Beschreibung |
+|---------|------|--------------|
+| `GET` | `/evidence` | Liste (`control_id`, `evidence_type`, `status`, `page`, `limit`) |
+| `POST` | `/evidence` | Nachweis manuell anlegen |
+| `DELETE` | `/evidence/{id}` | Nachweis löschen |
+| `POST` | `/evidence/upload` | Datei hochladen (PDF, ZIP, ...) |
+| `POST` | `/evidence/collect` | CI/CD-Nachweis automatisch erfassen |
+| `GET` | `/evidence/ci-status` | CI-Nachweisstand für eine Kontrolle |
+
+### CI/CD-Integration
+
+```json
+POST /evidence/collect
+{
+  "control_id": "SDLC-001",
+  "evidence_type": "test_results",
+  "title": "Pytest Run 2026-03-05",
+  "ci_job_id": "gh-actions-12345",
+  "artifact_url": "https://github.com/.../artifacts/report.xml"
+}
+```
+
+Nach dem Collect wird automatisch der Control-Status aktualisiert (`AutoRiskUpdater`).
+
+---
+
+## Frontend
+
+**URL:** `https://macmini:3007/sdk/evidence`
+
+Tabelle mit Nachweis-Einträgen, filterbar nach Control und Typ. Upload-Button für manuelle Nachweise. CI-Status-Badge zeigt automatisierungsgrad pro Control.
+
+---
+
+## Datenbankschema
+
+```sql
+compliance_evidence (
+  id             UUID PRIMARY KEY,
+  control_id     VARCHAR REFERENCES compliance_controls(control_id),
+  evidence_type  VARCHAR,               -- test_results/audit_report/...
+  title          TEXT,
+  description    TEXT,
+  artifact_path  TEXT,
+  artifact_url   TEXT,
+  ci_job_id      VARCHAR,
+  status         VARCHAR DEFAULT 'pending',
+  collected_at   TIMESTAMP,
+  created_at     TIMESTAMP
+)
+```
+
+---
+
+## Tests
+
+**Testdatei:** `backend-compliance/tests/test_evidence_routes.py`
+**Anzahl Tests:** 11 · **Status:** ✅ alle bestanden (Stand 2026-03-05)
+
+```bash
+cd backend-compliance
+python3 -m pytest tests/test_evidence_routes.py -v
+```
--- a/docs-src/services/sdk-modules/requirements.md
+++ b/docs-src/services/sdk-modules/requirements.md
@@ -0,0 +1,126 @@
+# Anforderungen (CP-ANF)
+
+Verwaltet regulatorische Anforderungen aus DSGVO, AI Act, CRA, NIS2 und weiteren Regulierungen.
+
+**Prefix:** `CP-ANF` · **Frontend:** `https://macmini:3007/sdk/anforderungen`
+**Proxy:** `/api/sdk/v1/compliance/[[...path]]` → `backend-compliance:8002/compliance/...`
+
+---
+
+## Features
+
+- Paginierte Anforderungsliste mit Freitextsuche
+- Filtert nach Regulierung, Anwendbarkeit und Implementierungsstatus
+- Verknüpfung mit Controls und Audit-Tracking
+- RAG-Rechtskontext: Holt passende Gesetzestexte aus dem Vector-Store
+
+---
+
+## Rechtsgrundlage
+
+| Regulierung | Beispielartikel |
+|-------------|-----------------|
+| DSGVO | Art. 5, Art. 24, Art. 32 |
+| AI Act | Art. 9, Art. 13 |
+| NIS2 | Art. 21 |
+| CRA | Art. 13 |
+
+---
+
+## API Endpoints
+
+| Methode | Pfad | Beschreibung |
+|---------|------|--------------|
+| `GET` | `/compliance/requirements` | Paginierte Liste (`page`, `page_size`, `search`, `is_applicable`) |
+| `GET` | `/compliance/requirements/{id}` | Einzelne Anforderung + optionaler RAG-Rechtskontext |
+| `GET` | `/compliance/regulations/{code}/requirements` | Alle Anforderungen einer Regulierung |
+| `POST` | `/compliance/requirements` | Neue Anforderung anlegen |
+| `PUT` | `/compliance/requirements/{id}` | Implementierungsstatus, Audit-Notizen aktualisieren |
+| `DELETE` | `/compliance/requirements/{id}` | Anforderung löschen |
+
+### RAG-Rechtskontext
+
+```http
+GET /compliance/requirements/{id}?include_legal_context=true
+```
+
+Gibt zusätzlich `legal_context[]` mit RAG-Ergebnissen zurück:
+
+```json
+{
+  "legal_context": [
+    {
+      "text": "...",
+      "regulation_code": "GDPR",
+      "article": "Art. 32",
+      "score": 0.92,
+      "source_url": "https://eur-lex.europa.eu/..."
+    }
+  ]
+}
+```
+
+### Request-Beispiel (POST)
+
+```json
+{
+  "regulation_id": "uuid-der-regulierung",
+  "article": "Art. 32",
+  "title": "Sicherheit der Verarbeitung",
+  "is_applicable": true,
+  "priority": 1
+}
+```
+
+### Response-Felder (RequirementResponse)
+
+| Feld | Typ | Beschreibung |
+|------|-----|--------------|
+| `id` | string | UUID |
+| `regulation_code` | string | z.B. "GDPR", "AI_ACT" |
+| `article` | string | Artikel-Referenz |
+| `implementation_status` | string | `not_started` / `implemented` / `partial` |
+| `audit_status` | string | `pending` / `passed` / `failed` |
+| `last_audit_date` | datetime? | Letztes Audit-Datum |
+
+---
+
+## Frontend
+
+**URL:** `https://macmini:3007/sdk/anforderungen`
+
+Zeigt eine filterbare Tabelle aller Anforderungen. Detailansicht öffnet sich per Klick und zeigt neben Metadaten optional den RAG-Rechtskontext mit Quellenangabe.
+
+---
+
+## Datenbankschema
+
+```sql
+compliance_requirements (
+  id                    UUID PRIMARY KEY,
+  regulation_id         UUID REFERENCES compliance_regulations(id),
+  article               VARCHAR,
+  title                 TEXT,
+  description           TEXT,
+  is_applicable         BOOLEAN DEFAULT true,
+  priority              INTEGER,
+  implementation_status VARCHAR DEFAULT 'not_started',
+  audit_status          VARCHAR DEFAULT 'pending',
+  last_audit_date       TIMESTAMP,
+  audit_notes           TEXT,
+  created_at            TIMESTAMP,
+  updated_at            TIMESTAMP
+)
+```
+
+---
+
+## Tests
+
+**Testdatei:** `backend-compliance/tests/test_requirement_routes.py`
+**Anzahl Tests:** 18 · **Status:** ✅ alle bestanden (Stand 2026-03-05)
+
+```bash
+cd backend-compliance
+python3 -m pytest tests/test_requirement_routes.py -v
+```
--- a/docs-src/services/sdk-modules/risks.md
+++ b/docs-src/services/sdk-modules/risks.md
@@ -0,0 +1,124 @@
+# Risiken (CP-RSK)
+
+Verwaltet Datenschutz- und KI-Risiken mit Risikobewertung nach Likelihood × Impact.
+
+**Prefix:** `CP-RSK` · **Frontend:** `https://macmini:3007/sdk/risks`
+**Proxy:** `/api/sdk/v1/compliance/[[...path]]` → `backend-compliance:8002/compliance/...`
+
+---
+
+## Features
+
+- Risikomatrix (Likelihood × Impact, 5×5)
+- Kategorisierung nach Datenschutz, KI, Betrieb, Sicherheit
+- Status-Tracking: open / mitigated / accepted / closed
+- Restrisiko nach Mitigationsmaßnahmen
+- Verknüpfung mit Controls
+
+---
+
+## Rechtsgrundlage
+
+| Artikel | Bezug |
+|---------|-------|
+| Art. 24 DSGVO | Risikobasierter Ansatz |
+| Art. 32 DSGVO | Risikobewertung für Sicherheitsmaßnahmen |
+| Art. 35 DSGVO | DSFA bei hohem Risiko |
+| Art. 9 AI Act | Risikomanagementsystem für KI |
+
+---
+
+## Risikobewertung
+
+| Stufe | Likelihood × Impact | Farbe |
+|-------|---------------------|-------|
+| `low` | ≤ 4 | Grün |
+| `medium` | 5–9 | Gelb |
+| `high` | 10–19 | Orange |
+| `critical` | ≥ 20 | Rot |
+
+---
+
+## API Endpoints
+
+| Methode | Pfad | Beschreibung |
+|---------|------|--------------|
+| `GET` | `/risks` | Liste (`category`, `status`, `risk_level`) |
+| `POST` | `/risks` | Neues Risiko anlegen |
+| `PUT` | `/risks/{risk_id}` | Risiko aktualisieren (Status, Restrisiko) |
+| `DELETE` | `/risks/{risk_id}` | Risiko löschen |
+| `GET` | `/risks/matrix` | Risikomatrix (Likelihood × Impact) |
+
+### Risikomatrix-Response
+
+```http
+GET /risks/matrix
+```
+
+```json
+{
+  "matrix": {
+    "3": { "4": ["RISK-001", "RISK-007"] },
+    "1": { "1": [] }
+  },
+  "risks": [...]
+}
+```
+
+Die Matrix ist nach `likelihood` (1–5) → `impact` (1–5) → `[risk_ids]` strukturiert.
+
+### Request-Beispiel (POST)
+
+```json
+{
+  "title": "Unbefugter Datenzugriff durch Dritte",
+  "category": "data_privacy",
+  "likelihood": 3,
+  "impact": 4,
+  "description": "Dritte könnten über unsichere APIs auf personenbezogene Daten zugreifen.",
+  "mitigation": "Einführung von API-Gateway mit Authentifizierung"
+}
+```
+
+---
+
+## Frontend
+
+**URL:** `https://macmini:3007/sdk/risks`
+
+Interaktive Risikomatrix als 5×5-Heatmap. Listenansicht mit Status-Badges und Kategorie-Filter. Neue Risiken können über ein Formular angelegt und direkt gemindert werden.
+
+---
+
+## Datenbankschema
+
+```sql
+compliance_risks (
+  id              UUID PRIMARY KEY,
+  risk_id         VARCHAR UNIQUE,        -- z.B. "RISK-001"
+  title           TEXT,
+  category        VARCHAR,               -- data_privacy/ai/operational/security
+  description     TEXT,
+  likelihood      INTEGER CHECK (likelihood BETWEEN 1 AND 5),
+  impact          INTEGER CHECK (impact BETWEEN 1 AND 5),
+  inherent_risk   VARCHAR,               -- low/medium/high/critical
+  residual_risk   VARCHAR,
+  status          VARCHAR DEFAULT 'open',
+  mitigation      TEXT,
+  owner           VARCHAR,
+  created_at      TIMESTAMP,
+  updated_at      TIMESTAMP
+)
+```
+
+---
+
+## Tests
+
+**Testdatei:** `backend-compliance/tests/test_risk_routes.py`
+**Anzahl Tests:** 16 (+ 8 aus Paket 2) · **Status:** ✅ alle bestanden (Stand 2026-03-05)
+
+```bash
+cd backend-compliance
+python3 -m pytest tests/test_risk_routes.py -v
+```