From c11270f8e027f62780fc406fb0920a30b901672b Mon Sep 17 00:00:00 2001 From: Benjamin Boenisch Date: Thu, 12 Feb 2026 00:49:28 +0100 Subject: [PATCH] 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 --- .claude/CLAUDE.md | 240 ++++- .claude/rules/compliance-checklist.md | 141 +++ .claude/rules/documentation.md | 91 ++ .claude/rules/open-source-policy.md | 99 ++ .claude/rules/testing.md | 202 ++++ .../app/(admin)/development/docs/page.tsx | 188 ++++ .../catalog-manager/CatalogEntryForm.tsx | 11 +- .../components/common/ModuleCard.tsx | 2 +- admin-compliance/lib/navigation.ts | 27 +- .../sdk/catalog-manager/catalog-registry.ts | 73 +- docker-compose.yml | 21 + docs-src/Dockerfile | 48 + docs-src/development/ci-cd-pipeline.md | 402 ++++++++ docs-src/development/documentation.md | 159 +++ docs-src/development/testing.md | 211 ++++ docs-src/index.md | 25 + .../ai-compliance-sdk/ARCHITECTURE.md | 947 ++++++++++++++++++ .../AUDITOR_DOCUMENTATION.md | 387 +++++++ .../services/ai-compliance-sdk/DEVELOPER.md | 746 ++++++++++++++ docs-src/services/ai-compliance-sdk/SBOM.md | 220 ++++ docs-src/services/ai-compliance-sdk/index.md | 97 ++ mkdocs.yml | 68 ++ 22 files changed, 4374 insertions(+), 31 deletions(-) create mode 100644 .claude/rules/compliance-checklist.md create mode 100644 .claude/rules/documentation.md create mode 100644 .claude/rules/open-source-policy.md create mode 100644 .claude/rules/testing.md create mode 100644 admin-compliance/app/(admin)/development/docs/page.tsx create mode 100644 docs-src/Dockerfile create mode 100644 docs-src/development/ci-cd-pipeline.md create mode 100644 docs-src/development/documentation.md create mode 100644 docs-src/development/testing.md create mode 100644 docs-src/index.md create mode 100644 docs-src/services/ai-compliance-sdk/ARCHITECTURE.md create mode 100644 docs-src/services/ai-compliance-sdk/AUDITOR_DOCUMENTATION.md create mode 100644 docs-src/services/ai-compliance-sdk/DEVELOPER.md create mode 100644 docs-src/services/ai-compliance-sdk/SBOM.md create mode 100644 docs-src/services/ai-compliance-sdk/index.md create mode 100644 mkdocs.yml diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index acc2a4b..a19c043 100644 --- 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 && " ``` +--- + ## 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 " + +# Logs +ssh macmini "/usr/local/bin/docker logs -f bp-compliance-" + +# 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 | diff --git a/.claude/rules/compliance-checklist.md b/.claude/rules/compliance-checklist.md new file mode 100644 index 0000000..2b6cc2d --- /dev/null +++ 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. diff --git a/.claude/rules/documentation.md b/.claude/rules/documentation.md new file mode 100644 index 0000000..e5e035f --- /dev/null +++ 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) diff --git a/.claude/rules/open-source-policy.md b/.claude/rules/open-source-policy.md new file mode 100644 index 0000000..af7001a --- /dev/null +++ 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 license + +# Python Package +pip show | grep License + +# Go Module +go-licenses check +``` + +### 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 diff --git a/.claude/rules/testing.md b/.claude/rules/testing.md new file mode 100644 index 0000000..d7441f6 --- /dev/null +++ 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) diff --git a/admin-compliance/app/(admin)/development/docs/page.tsx b/admin-compliance/app/(admin)/development/docs/page.tsx new file mode 100644 index 0000000..6081778 --- /dev/null +++ b/admin-compliance/app/(admin)/development/docs/page.tsx @@ -0,0 +1,188 @@ +'use client' + +import { useState } from 'react' +import { ExternalLink, Maximize2, Minimize2, RefreshCw, Search, BookOpen, ArrowRight } from 'lucide-react' + +// Quick links to compliance documentation sections +const quickLinks = [ + { name: 'AI Compliance SDK', path: 'services/ai-compliance-sdk/', icon: '🔒' }, + { name: 'Architektur', path: 'services/ai-compliance-sdk/ARCHITECTURE/', icon: '🏗️' }, + { name: 'Developer Guide', path: 'services/ai-compliance-sdk/DEVELOPER/', icon: '👩‍💻' }, + { name: 'Auditor Doku', path: 'services/ai-compliance-sdk/AUDITOR_DOCUMENTATION/', icon: '📋' }, + { name: 'SBOM', path: 'services/ai-compliance-sdk/SBOM/', icon: '📦' }, + { name: 'CI/CD Pipeline', path: 'development/ci-cd-pipeline/', icon: '🚀' }, +] + +export default function DocsPage() { + const [isFullscreen, setIsFullscreen] = useState(false) + const [isLoading, setIsLoading] = useState(true) + const [currentPath, setCurrentPath] = useState('') + + const getDocsUrl = () => { + if (typeof window !== 'undefined') { + const protocol = window.location.protocol + const hostname = window.location.hostname + const port = window.location.port + return `${protocol}//${hostname}${port ? ':' + port : ''}/docs` + } + return '/docs' + } + + const docsUrl = getDocsUrl() + + const handleIframeLoad = () => { + setIsLoading(false) + } + + const navigateTo = (path: string) => { + setCurrentPath(path) + setIsLoading(true) + } + + const toggleFullscreen = () => { + setIsFullscreen(!isFullscreen) + } + + const openInNewTab = () => { + window.open(`${docsUrl}/${currentPath}`, '_blank') + } + + const refreshDocs = () => { + setIsLoading(true) + setCurrentPath(currentPath + '?refresh=' + Date.now()) + setTimeout(() => setCurrentPath(currentPath), 100) + } + + if (isFullscreen) { + return ( +
+
+
+ + BreakPilot Compliance Dokumentation +
+
+ + +
+
+