Add CLAUDE.md, MkDocs docs, docs page in admin, .claude/rules

- CLAUDE.md: Comprehensive documentation for Compliance SDK platform - docs-src: AI-Compliance-SDK docs (architecture, developer, auditor, SBOM) - mkdocs.yml: Compliance-specific nav with purple theme - docker-compose: Added docs service (port 8011, profile: docs) - admin-compliance: New /development/docs page with iframe + quick links - navigation.ts: Added development category with docs module - .claude/rules: testing, docs, open-source, compliance-checklist Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-12 00:49:28 +01:00
parent 4435e7ea0a
commit c11270f8e0
22 changed files with 4374 additions and 31 deletions
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -1,34 +1,93 @@
-# BreakPilot Compliance — DSGVO/AI-Act SDK Platform
+# BreakPilot Compliance - DSGVO/AI-Act SDK Platform

-## Entwicklungsumgebung
+## Entwicklungsumgebung (WICHTIG - IMMER ZUERST LESEN)

 ### Zwei-Rechner-Setup
-| Gerät | Rolle |
-|-------|-------|
-| **MacBook** | Client/Terminal |
-| **Mac Mini** | Server/Docker/Git |
+
+| Geraet | Rolle | Aufgaben |
+|--------|-------|----------|
+| **MacBook** | Client | Claude Terminal, Browser (Frontend-Tests) |
+| **Mac Mini** | Server | Docker, alle Services, Code-Ausfuehrung, Tests, Git |
+
+**WICHTIG:** Die Entwicklung findet vollstaendig auf dem **Mac Mini** statt!
+
+### SSH-Verbindung

 ```bash
+ssh macmini
+# Projektverzeichnis:
+cd /Users/benjaminadmin/Projekte/breakpilot-compliance
+
+# Einzelbefehle (BEVORZUGT):
 ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-compliance && <cmd>"
 ```

+---
+
 ## Voraussetzung
-**breakpilot-core MUSS laufen!** Dieses Projekt nutzt Core-Services (DB, Cache, Auth, RAG).

-## Projektübersicht
+**breakpilot-core MUSS laufen!** Dieses Projekt nutzt Core-Services:
+- PostgreSQL (Schema: `compliance`, `core`)
+- Valkey (Session-Cache)
+- Vault (Secrets)
+- RAG-Service (Vektorsuche fuer Compliance-Dokumente)
+- Nginx (Reverse Proxy)

-**breakpilot-compliance** ist die Compliance-SDK-Plattform für DSGVO, AI Act und Datenschutz.
+Pruefen: `curl -sf http://macmini:8099/health`

-### Enthaltene Services (~8 Container)
+---

-| Service | Port | Beschreibung |
-|---------|------|--------------|
-| admin-compliance | 3007 | Compliance Admin (Next.js) |
-| developer-portal | 3006 | API-Dokumentation |
-| backend-compliance | 8002 | Compliance APIs (FastAPI) |
-| ai-compliance-sdk | 8093 | KI-Compliance SDK |
-| dsms-node | 4001 | IPFS Node |
-| dsms-gateway | 8085 | IPFS Gateway |
+## Haupt-URLs (Browser auf MacBook)
+
+### Frontends
+
+| URL | Service | Beschreibung |
+|-----|---------|--------------|
+| **https://macmini:3007/** | Admin Compliance | SDK-Dashboard, alle Compliance-Module |
+| **https://macmini:3006/** | Developer Portal | API-Dokumentation fuer Kunden |
+
+### Backend-APIs
+
+| URL | Service | Beschreibung |
+|-----|---------|--------------|
+| https://macmini:8002/ | Backend Compliance | Compliance APIs (DSGVO, DSR, GDPR) |
+| https://macmini:8093/ | AI Compliance SDK | KI-konforme Compliance-Analyse |
+
+### Admin Compliance Module (https://macmini:3007/)
+
+| Pfad | Modul | Beschreibung |
+|------|-------|--------------|
+| `/dashboard` | Dashboard | Uebersicht + Catalog-Manager |
+| `/sdk/tom` | TOM | Technisch-Organisatorische Massnahmen |
+| `/sdk/dsfa` | DSFA | Datenschutz-Folgenabschaetzung |
+| `/sdk/vvt` | VVT | Verzeichnis von Verarbeitungstaetigkeiten |
+| `/sdk/loeschfristen` | Loeschfristen | Loeschfristen-Verwaltung |
+| `/sdk/ai-act` | AI Act | KI-Verordnung Compliance |
+| `/sdk/consent` | Consent | Einwilligungsmanagement |
+| `/sdk/dsr` | DSR | Betroffenenrechte |
+| `/sdk/vendor-compliance` | Vendor | Auftragsverarbeitung |
+| `/sdk/risk-assessment` | Risiko | Risikobewertung |
+| `/sdk/incident-response` | Vorfaelle | Datenschutz-Vorfaelle |
+| `/sdk/training` | Schulung | Mitarbeiter-Schulungen |
+| `/sdk/audit` | Audit | Audit-Management |
+| `/sdk/policy-generator` | Policies | Richtlinien-Generator |
+| `/sdk/data-mapping` | Data Map | Datenfluss-Mapping |
+| `/developers` | Developer Portal | SDK API-Docs |
+
+---
+
+## Services (~8 Container)
+
+| Service | Tech | Port | Container |
+|---------|------|------|-----------|
+| admin-compliance | Next.js 15 | 3007 (via nginx) | bp-compliance-admin |
+| backend-compliance | Python/FastAPI | 8002 | bp-compliance-backend |
+| ai-compliance-sdk | Python/FastAPI | 8093 | bp-compliance-ai-sdk |
+| developer-portal | Next.js | 3006 (via nginx) | bp-compliance-developer-portal |
+| dsms-node | Node.js | 4001/5001 | bp-compliance-dsms-node |
+| dsms-gateway | Node.js | 8085 | bp-compliance-dsms-gateway |
+| pca-platform | Python | - | bp-compliance-pca |
+| consent-sdk | Node.js | - | bp-compliance-consent-sdk |

 ### Docker-Netzwerk
 Nutzt das externe Core-Netzwerk:
@@ -42,10 +101,143 @@ networks:
 ### Container-Naming: `bp-compliance-*`
 ### DB search_path: `compliance,core,public`

-### SDK-Module (37 Routes)
-TOM, DSFA, VVT, Löschfristen, AI-Act, Consent, DSR, Vendor Compliance, etc.
+---

-## Git Remotes
-Immer zu BEIDEN pushen:
- `origin`: lokale Gitea (macmini:3003)
- `gitea`: gitea.meghsakha.com
+## Verzeichnisstruktur
+
+```
+breakpilot-compliance/
+├── .claude/
+│   ├── CLAUDE.md             # Diese Datei
+│   └── rules/                # Automatische Regeln
+├── admin-compliance/         # Next.js Compliance Dashboard
+│   ├── app/(sdk)/            # 37 SDK-Route-Dirs
+│   ├── app/(admin)/          # Dashboard + Catalog-Manager
+│   ├── components/sdk/       # SDKSidebar, CommandBar, ComplianceAdvisor
+│   ├── components/catalog-manager/  # Shared Catalog UI
+│   └── lib/sdk/              # SDK Context, Types, API-Client
+├── backend-compliance/       # Python/FastAPI Backend
+│   ├── compliance/           # Haupt-Package (40 Dateien)
+│   │   ├── api/              # API Router
+│   │   ├── db/               # DB Models
+│   │   ├── services/         # Business Logic
+│   │   └── data/             # Stammdaten
+│   ├── consent_admin_api.py
+│   ├── dsr_api.py
+│   └── gdpr_api.py
+├── ai-compliance-sdk/        # KI-Compliance Analyse Service
+├── developer-portal/         # API-Dokumentation (Next.js)
+├── breakpilot-compliance-sdk/ # SDK Package
+├── consent-sdk/              # Consent SDK Package
+├── pca-platform/             # Privacy Compliance Automation
+├── dsms-node/                # IPFS Node
+├── dsms-gateway/             # IPFS Gateway
+├── scripts/                  # Helper Scripts
+└── docker-compose.yml        # Compliance Compose (~8 Services)
+```
+
+---
+
+## Haeufige Befehle
+
+### Docker
+
+```bash
+# Compliance-Services starten (Core muss laufen!)
+ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-compliance && /usr/local/bin/docker compose up -d"
+
+# Einzelnen Service neu bauen
+ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-compliance && /usr/local/bin/docker compose build --no-cache <service>"
+
+# Logs
+ssh macmini "/usr/local/bin/docker logs -f bp-compliance-<service>"
+
+# Status
+ssh macmini "/usr/local/bin/docker ps --filter name=bp-compliance"
+```
+
+**WICHTIG:** Docker-Pfad auf Mac Mini ist `/usr/local/bin/docker` (nicht im Standard-SSH-PATH).
+
+### Git
+
+```bash
+# Zu BEIDEN Remotes pushen (PFLICHT!):
+ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-compliance && git push all main"
+
+# Remotes:
+# origin: lokale Gitea (macmini:3003)
+# gitea:  gitea.meghsakha.com
+# all:    beide gleichzeitig
+```
+
+---
+
+## Kernprinzipien
+
+### 1. Open Source Policy
+- **NUR Open Source mit kommerziell nutzbarer Lizenz**
+- Erlaubt: MIT, Apache-2.0, BSD, ISC, MPL-2.0, LGPL
+- **VERBOTEN:** GPL (ausser LGPL), AGPL, proprietaer
+
+### 2. DSGVO-Compliance
+- Dieses Projekt implementiert DSGVO-Tools — es muss selbst DSGVO-konform sein
+- Audit-Logging fuer alle Compliance-Aktionen
+- Consent-Management via Core consent-service
+
+### 3. AI Act Compliance
+- KI-Risikobewertung fuer alle KI-Features
+- Human Oversight sicherstellen
+- Transparenzpflicht bei KI-Nutzung
+
+### 4. Testing & Dokumentation
+- Tests sind Pflicht bei jeder Aenderung
+- Compliance-Checkliste bei neuen Features durchgehen
+
+### 5. Sensitive Dateien
+**NIEMALS aendern oder committen:**
+- `.env`, `.env.local`, Vault-Tokens, SSL-Zertifikate
+- `*.pdf`, `*.docx`, kompilierte Binaries, grosse Medien
+
+---
+
+## Tech-Stack
+
+| Sprache | Services |
+|---------|----------|
+| Python/FastAPI | backend-compliance, ai-compliance-sdk, pca-platform |
+| TypeScript/Next.js | admin-compliance, developer-portal |
+| Node.js | dsms-node, dsms-gateway, consent-sdk |
+
+---
+
+## SDK-Module im Detail
+
+### Katalog-System (Shared mit Lehrer)
+- `components/catalog-manager/` — CatalogManagerContent, CatalogTable, CatalogModuleTabs, CatalogEntryForm
+- `lib/sdk/catalog-manager/` — catalog-registry.ts, types.ts
+- 17 DSGVO/AI-Act Kataloge (dsfa, vvt-baseline, vendor-compliance, etc.)
+
+### Backend-Compliance APIs
+```
+POST/GET /api/v1/compliance/risks
+POST/GET /api/v1/compliance/controls
+POST/GET /api/v1/compliance/requirements
+POST/GET /api/v1/compliance/evidence
+POST/GET /api/v1/dsr/requests
+POST/GET /api/v1/gdpr/exports
+POST/GET /api/v1/consent/admin
+```
+
+---
+
+## Wichtige Dateien (Referenz)
+
+| Datei | Beschreibung |
+|-------|--------------|
+| `admin-compliance/app/(sdk)/` | Alle 37 SDK-Routes |
+| `admin-compliance/components/sdk/SDKSidebar.tsx` | SDK Navigation |
+| `admin-compliance/components/sdk/CommandBar.tsx` | Command Palette |
+| `admin-compliance/lib/sdk/context.tsx` | SDK State (Provider) |
+| `backend-compliance/compliance/` | Haupt-Package (40 Dateien) |
+| `ai-compliance-sdk/` | KI-Compliance Analyse |
+| `developer-portal/` | API-Dokumentation |
--- a/.claude/rules/compliance-checklist.md
+++ b/.claude/rules/compliance-checklist.md
@@ -0,0 +1,141 @@
+# Compliance-Checkliste
+
+## Wann diese Checkliste anwenden?
+
+**AUTOMATISCH bei:**
+- Neuen Features mit Nutzerdaten
+- Änderungen an Datenflüssen
+- KI/ML-Funktionen
+- Neuen API-Endpoints
+- Datenbankschema-Änderungen
+
+---
+
+## 1. DSGVO-Check (Datenschutz-Grundverordnung)
+
+### Rechtsgrundlage klären
+
+| Rechtsgrundlage | Wann verwenden |
+|-----------------|----------------|
+| **Einwilligung (Art. 6 Abs. 1a)** | Optionale Features, Marketing, Analytics |
+| **Vertragserfüllung (Art. 6 Abs. 1b)** | Kernfunktionen der Plattform |
+| **Berechtigtes Interesse (Art. 6 Abs. 1f)** | Sicherheit, Betrugsprävention |
+| **Rechtliche Verpflichtung (Art. 6 Abs. 1c)** | Aufbewahrungspflichten |
+
+### Datenminimierung
+
+- [ ] Werden nur notwendige Daten erhoben?
+- [ ] Gibt es Felder, die optional sein könnten?
+- [ ] Werden Daten nach Zweckerfüllung gelöscht?
+
+### Besondere Kategorien (Art. 9)
+
+**ACHTUNG bei:**
+- Gesundheitsdaten (Krankheitstage, Atteste)
+- Biometrische Daten (Gesichtserkennung, Stimme)
+- Religiöse Überzeugungen
+- Politische Meinungen
+
+→ **Explizite Einwilligung erforderlich!**
+
+### Minderjährige (Art. 8)
+
+**Breakpilot-spezifisch:**
+- Unter 16 Jahren: Einwilligung der Eltern
+- Altersverifikation implementieren
+- Kindgerechte Datenschutzerklärung
+
+### Betroffenenrechte sicherstellen
+
+- [ ] **Auskunft (Art. 15):** Kann der Nutzer seine Daten einsehen?
+- [ ] **Berichtigung (Art. 16):** Kann der Nutzer Daten korrigieren?
+- [ ] **Löschung (Art. 17):** Kann der Nutzer Löschung beantragen?
+- [ ] **Datenportabilität (Art. 20):** Export in maschinenlesbarem Format?
+
+---
+
+## 2. AI Act Check (KI-Verordnung)
+
+### Risikokategorie bestimmen
+
+| Kategorie | Beispiele | Anforderungen |
+|-----------|-----------|---------------|
+| **Unakzeptabel** | Social Scoring, Manipulation | ❌ VERBOTEN |
+| **Hochrisiko** | Bildungszugang, Prüfungsbewertung | Strenge Auflagen |
+| **Begrenzt** | Chatbots, Empfehlungen | Transparenzpflicht |
+| **Minimal** | Spam-Filter, Autokorrektur | Keine Auflagen |
+
+### Breakpilot KI-Features prüfen
+
+| Feature | Risiko | Maßnahmen |
+|---------|--------|-----------|
+| Klausur-OCR | Begrenzt | Transparenz, Human-in-Loop |
+| KI-Korrekturvorschläge | Hochrisiko | Audit-Log, Erklärbarkeit |
+| Lernempfehlungen | Begrenzt | Transparenz |
+| Spracherkennung | Begrenzt | Consent, Transparenz |
+
+### Hochrisiko-KI Anforderungen
+
+Wenn Hochrisiko:
+- [ ] Risikomanagementsystem dokumentiert
+- [ ] Qualität der Trainingsdaten sichergestellt
+- [ ] Technische Dokumentation vorhanden
+- [ ] Audit-Logging aktiviert
+- [ ] Human Oversight möglich
+- [ ] Genauigkeit/Robustheit getestet
+
+---
+
+## 3. Technische Maßnahmen (TOM)
+
+### Verschlüsselung
+
+- [ ] **Transit:** TLS 1.3 für alle Verbindungen
+- [ ] **Rest:** Datenbank-Verschlüsselung
+- [ ] **Secrets:** Vault für Credentials
+
+### Zugriffskontrollen
+
+- [ ] RBAC implementiert
+- [ ] Least Privilege Prinzip
+- [ ] Session-Timeouts
+
+### Audit-Logging
+
+```python
+# Beispiel: Audit-Event loggen
+audit_log.info({
+    "action": "data_export",
+    "user_id": user.id,
+    "timestamp": datetime.utcnow(),
+    "data_categories": ["grades", "personal"],
+    "legal_basis": "Art. 20 DSGVO"
+})
+```
+
+---
+
+## 4. Dokumentationspflichten
+
+### Bei neuen Features aktualisieren
+
+| Dokument | URL | Wann aktualisieren |
+|----------|-----|-------------------|
+| VVT | https://macmini:3002/sdk/vvt | Neue Verarbeitung |
+| TOM | https://macmini:3002/sdk/tom | Neue Schutzmaßnahme |
+| DSFA | https://macmini:3002/sdk/dsfa | Hochrisiko-Verarbeitung |
+| Löschfristen | https://macmini:3002/sdk/loeschfristen | Neue Datenkategorie |
+
+---
+
+## 5. Schnell-Check (5 Fragen)
+
+Vor jedem Feature diese 5 Fragen beantworten:
+
+1. **WER** sind die Betroffenen? (Schüler, Lehrer, Eltern)
+2. **WAS** für Daten werden verarbeitet?
+3. **WARUM** werden sie verarbeitet? (Rechtsgrundlage)
+4. **WIE LANGE** werden sie gespeichert?
+5. **WER** hat Zugriff?
+
+Können alle 5 Fragen beantwortet werden? → Feature ist dokumentierbar.
--- a/.claude/rules/documentation.md
+++ b/.claude/rules/documentation.md
@@ -0,0 +1,91 @@
+# Dokumentations-Regeln
+
+## Automatische Dokumentations-Aktualisierung
+
+**WICHTIG:** Bei JEDER Code-Änderung muss die entsprechende Dokumentation aktualisiert werden!
+
+## Wann Dokumentation aktualisieren?
+
+### API-Änderungen
+Wenn du einen Endpoint änderst, hinzufügst oder entfernst:
+- Aktualisiere `/docs/api/consent-service-api.md` (Go Endpoints)
+- Aktualisiere `/docs/api/backend-api.md` (Python Endpoints)
+
+### Neue Funktionen/Klassen
+Wenn du neue Funktionen, Klassen oder Module erstellst:
+- Aktualisiere `/docs/consent-service/README.md` (für Go)
+- Aktualisiere `/docs/backend/README.md` (für Python)
+
+### Architektur-Änderungen
+Wenn du die Systemarchitektur änderst:
+- Aktualisiere `/docs/architecture/system-architecture.md`
+- Aktualisiere `/docs/architecture/data-model.md` (bei DB-Änderungen)
+
+### Neue Konfigurationsoptionen
+Wenn du neue Umgebungsvariablen oder Konfigurationen hinzufügst:
+- Aktualisiere die entsprechende README
+- Füge zur `guides/local-development.md` hinzu
+
+## Dokumentations-Format
+
+### API-Endpoints dokumentieren
+
+```markdown
+### METHOD /path/to/endpoint
+
+Kurze Beschreibung.
+
+**Request Body:**
+\`\`\`json
+{
+  "field": "value"
+}
+\`\`\`
+
+**Response (200):**
+\`\`\`json
+{
+  "result": "value"
+}
+\`\`\`
+
+**Errors:**
+- `400`: Beschreibung
+- `401`: Beschreibung
+```
+
+### Funktionen dokumentieren
+
+```markdown
+### FunctionName (file.go:123)
+
+\`\`\`go
+func FunctionName(param Type) ReturnType
+\`\`\`
+
+**Beschreibung:** Was macht die Funktion?
+
+**Parameter:**
+- `param`: Beschreibung
+
+**Rückgabe:** Beschreibung
+```
+
+## Checkliste nach Code-Änderungen
+
+Vor dem Abschluss einer Aufgabe prüfe:
+
+- [ ] Wurden neue API-Endpoints hinzugefügt? → API-Docs aktualisieren
+- [ ] Wurden Datenmodelle geändert? → data-model.md aktualisieren
+- [ ] Wurden neue Konfigurationen hinzugefügt? → README aktualisieren
+- [ ] Wurden neue Abhängigkeiten hinzugefügt? → requirements.txt/go.mod UND Docs
+- [ ] Wurde die Architektur geändert? → architecture/ aktualisieren
+
+## Beispiel: Vollständige Dokumentation einer neuen Funktion
+
+Wenn du z.B. `GetUserStats()` im Go Service hinzufügst:
+
+1. **Code schreiben** in `internal/services/stats_service.go`
+2. **API-Doc aktualisieren** in `docs/api/consent-service-api.md`
+3. **Service-Doc aktualisieren** in `docs/consent-service/README.md`
+4. **Test schreiben** (siehe testing.md)
--- a/.claude/rules/open-source-policy.md
+++ b/.claude/rules/open-source-policy.md
@@ -0,0 +1,99 @@
+# Open Source Policy
+
+## Lizenzprüfung (AUTOMATISCH BEI JEDER DEPENDENCY)
+
+### Erlaubte Lizenzen ✅
+
+| Lizenz | Typ | Kommerziell OK |
+|--------|-----|----------------|
+| MIT | Permissive | ✅ |
+| Apache-2.0 | Permissive | ✅ |
+| BSD-2-Clause | Permissive | ✅ |
+| BSD-3-Clause | Permissive | ✅ |
+| ISC | Permissive | ✅ |
+| MPL-2.0 | Weak Copyleft | ✅ |
+| LGPL-2.1 / LGPL-3.0 | Weak Copyleft | ✅ (nur linking) |
+| CC0-1.0 | Public Domain | ✅ |
+| Unlicense | Public Domain | ✅ |
+
+### Verbotene Lizenzen ❌
+
+| Lizenz | Grund |
+|--------|-------|
+| GPL-2.0 / GPL-3.0 | Copyleft - infiziert Projekt |
+| AGPL-3.0 | Network Copyleft - SaaS-Killer |
+| SSPL | Server Side Public License |
+| BSL | Business Source License |
+| "Non-Commercial" | Keine kommerzielle Nutzung |
+| "Educational Only" | Nur für Bildung |
+| Proprietary | Keine OSS |
+
+---
+
+## Workflow bei neuer Dependency
+
+### 1. Vor dem Hinzufügen prüfen
+
+```bash
+# NPM Package
+npm view <package> license
+
+# Python Package
+pip show <package> | grep License
+
+# Go Module
+go-licenses check <module>
+```
+
+### 2. Bei Unklarheit
+
+- README.md des Projekts lesen
+- LICENSE-Datei prüfen
+- SPDX-Identifier suchen
+- Im Zweifel: **NICHT verwenden**
+
+### 3. Nach dem Hinzufügen
+
+**SBOM aktualisieren:** https://macmini:3002/infrastructure/sbom
+
+```bash
+# SBOM generieren
+cd /Users/benjaminadmin/Projekte/breakpilot-pwa
+
+# Python
+pip-licenses --format=json > sbom/python-licenses.json
+
+# Node.js
+npx license-checker --json > sbom/node-licenses.json
+
+# Go
+go-licenses csv ./... > sbom/go-licenses.csv
+```
+
+---
+
+## Grenzfälle
+
+### Dual-Licensed Packages
+- Wenn MIT **oder** GPL angeboten wird → MIT wählen
+- Dokumentieren welche Lizenz gewählt wurde
+
+### Transitive Dependencies
+- Auch indirekte Abhängigkeiten prüfen
+- `npm ls`, `pip-tree`, `go mod graph`
+
+### Fonts & Assets
+- Google Fonts: ✅ (OFL)
+- Font Awesome Free: ✅ (CC BY 4.0 / OFL / MIT)
+- Icons8: ❌ (Attribution required, kompliziert)
+
+---
+
+## Checkliste bei PR/Commit
+
+Wenn neue Dependencies hinzugefügt wurden:
+
+- [ ] Lizenz ist in der Whitelist
+- [ ] SBOM wurde aktualisiert
+- [ ] Keine GPL/AGPL-Abhängigkeiten eingeschleppt
+- [ ] Bei Dual-License: MIT/Apache gewählt
--- a/.claude/rules/testing.md
+++ b/.claude/rules/testing.md
@@ -0,0 +1,202 @@
+# Test-Regeln
+
+## Automatische Test-Erweiterung
+
+**WICHTIG:** Bei JEDER Code-Änderung müssen entsprechende Tests erstellt oder aktualisiert werden!
+
+## Wann Tests schreiben?
+
+### IMMER wenn du:
+1. **Neue Funktionen** erstellst → Unit Test
+2. **Neue API-Endpoints** hinzufügst → Handler Test
+3. **Bugs fixst** → Regression Test (der Bug sollte nie wieder auftreten)
+4. **Bestehenden Code änderst** → Bestehende Tests anpassen
+
+## Test-Struktur
+
+### Go Tests (Consent Service)
+
+**Speicherort:** Im gleichen Verzeichnis wie der Code
+
+```
+internal/
+├── services/
+│   ├── auth_service.go
+│   └── auth_service_test.go    ← Test hier
+├── handlers/
+│   ├── handlers.go
+│   └── handlers_test.go        ← Test hier
+└── middleware/
+    ├── auth.go
+    └── middleware_test.go      ← Test hier
+```
+
+**Test-Namenskonvention:**
+```go
+func TestFunctionName_Scenario_ExpectedResult(t *testing.T)
+
+// Beispiele:
+func TestHashPassword_ValidPassword_ReturnsHash(t *testing.T)
+func TestLogin_InvalidCredentials_Returns401(t *testing.T)
+func TestCreateDocument_MissingTitle_ReturnsError(t *testing.T)
+```
+
+**Test-Template:**
+```go
+func TestFunctionName(t *testing.T) {
+    // Arrange
+    service := &MyService{}
+    input := "test-input"
+
+    // Act
+    result, err := service.DoSomething(input)
+
+    // Assert
+    if err != nil {
+        t.Fatalf("Expected no error, got %v", err)
+    }
+    if result != expected {
+        t.Errorf("Expected %v, got %v", expected, result)
+    }
+}
+```
+
+**Table-Driven Tests bevorzugen:**
+```go
+func TestValidateEmail(t *testing.T) {
+    tests := []struct {
+        name     string
+        email    string
+        expected bool
+    }{
+        {"valid email", "test@example.com", true},
+        {"missing @", "testexample.com", false},
+        {"empty", "", false},
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            result := ValidateEmail(tt.email)
+            if result != tt.expected {
+                t.Errorf("Expected %v, got %v", tt.expected, result)
+            }
+        })
+    }
+}
+```
+
+### Python Tests (Backend)
+
+**Speicherort:** `/backend/tests/`
+
+```
+backend/
+├── consent_client.py
+├── gdpr_api.py
+└── tests/
+    ├── __init__.py
+    ├── test_consent_client.py  ← Tests für consent_client.py
+    └── test_gdpr_api.py        ← Tests für gdpr_api.py
+```
+
+**Test-Namenskonvention:**
+```python
+class TestClassName:
+    def test_method_scenario_expected_result(self):
+        pass
+
+# Beispiele:
+class TestConsentClient:
+    def test_check_consent_valid_token_returns_status(self):
+        pass
+
+    def test_check_consent_expired_token_raises_error(self):
+        pass
+```
+
+**Test-Template:**
+```python
+import pytest
+from unittest.mock import AsyncMock, patch, MagicMock
+
+class TestMyFeature:
+    def test_sync_function(self):
+        # Arrange
+        input_data = "test"
+
+        # Act
+        result = my_function(input_data)
+
+        # Assert
+        assert result == expected
+
+    @pytest.mark.asyncio
+    async def test_async_function(self):
+        # Arrange
+        client = MyClient()
+
+        # Act
+        with patch("httpx.AsyncClient") as mock:
+            mock_instance = AsyncMock()
+            mock.return_value = mock_instance
+            result = await client.fetch_data()
+
+        # Assert
+        assert result is not None
+```
+
+## Test-Kategorien
+
+### 1. Unit Tests (Höchste Priorität)
+- Testen einzelne Funktionen/Methoden
+- Keine externen Abhängigkeiten (Mocks verwenden)
+- Schnell ausführbar
+
+### 2. Integration Tests
+- Testen Zusammenspiel mehrerer Komponenten
+- Können echte DB verwenden (Test-DB)
+
+### 3. Security Tests
+- Auth/JWT Validierung
+- Passwort-Hashing
+- Berechtigungsprüfung
+
+## Checkliste vor Abschluss
+
+Vor dem Abschluss einer Aufgabe:
+
+- [ ] Gibt es Tests für alle neuen Funktionen?
+- [ ] Gibt es Tests für alle Edge Cases?
+- [ ] Gibt es Tests für Fehlerfälle?
+- [ ] Laufen alle bestehenden Tests noch? (`go test ./...` / `pytest`)
+- [ ] Ist die Test-Coverage angemessen?
+
+## Tests ausführen
+
+```bash
+# Go - Alle Tests
+cd consent-service && go test -v ./...
+
+# Go - Mit Coverage
+cd consent-service && go test -cover ./...
+
+# Python - Alle Tests
+cd backend && source venv/bin/activate && pytest -v
+
+# Python - Mit Coverage
+cd backend && pytest --cov=. --cov-report=html
+```
+
+## Beispiel: Vollständiger Test-Workflow
+
+Wenn du z.B. eine neue `GetUserStats()` Funktion im Go Service hinzufügst:
+
+1. **Funktion schreiben** in `internal/services/stats_service.go`
+2. **Test erstellen** in `internal/services/stats_service_test.go`:
+   ```go
+   func TestGetUserStats_ValidUser_ReturnsStats(t *testing.T) {...}
+   func TestGetUserStats_InvalidUser_ReturnsError(t *testing.T) {...}
+   func TestGetUserStats_NoConsents_ReturnsEmptyStats(t *testing.T) {...}
+   ```
+3. **Tests ausführen**: `go test -v ./internal/services/...`
+4. **Dokumentation aktualisieren** (siehe documentation.md)