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>
This commit is contained in:
Benjamin Boenisch
@@ -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 |
|
||||
|
||||
141
.claude/rules/compliance-checklist.md
Normal file
141
.claude/rules/compliance-checklist.md
Normal file
@@ -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.
|
||||
91
.claude/rules/documentation.md
Normal file
91
.claude/rules/documentation.md
Normal file
@@ -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)
|
||||
99
.claude/rules/open-source-policy.md
Normal file
99
.claude/rules/open-source-policy.md
Normal file
@@ -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
|
||||
202
.claude/rules/testing.md
Normal file
202
.claude/rules/testing.md
Normal file
@@ -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)
|
||||
188
admin-compliance/app/(admin)/development/docs/page.tsx
Normal file
188
admin-compliance/app/(admin)/development/docs/page.tsx
Normal file
@@ -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 (
|
||||
<div className="fixed inset-0 z-50 bg-white">
|
||||
<div className="absolute top-0 left-0 right-0 h-12 bg-slate-900 flex items-center justify-between px-4 z-10">
|
||||
<div className="flex items-center gap-2 text-white">
|
||||
<BookOpen className="w-5 h-5" />
|
||||
<span className="font-semibold">BreakPilot Compliance Dokumentation</span>
|
||||
</div>
|
||||
<div className="flex items-center gap-2">
|
||||
<button
|
||||
onClick={openInNewTab}
|
||||
className="p-2 text-slate-300 hover:text-white hover:bg-slate-700 rounded transition-colors"
|
||||
title="In neuem Tab oeffnen"
|
||||
>
|
||||
<ExternalLink className="w-4 h-4" />
|
||||
</button>
|
||||
<button
|
||||
onClick={toggleFullscreen}
|
||||
className="p-2 text-slate-300 hover:text-white hover:bg-slate-700 rounded transition-colors"
|
||||
title="Vollbild beenden"
|
||||
>
|
||||
<Minimize2 className="w-4 h-4" />
|
||||
</button>
|
||||
</div>
|
||||
</div>
|
||||
<iframe
|
||||
src={`${docsUrl}/${currentPath}`}
|
||||
className="w-full h-full pt-12"
|
||||
title="BreakPilot Compliance Documentation"
|
||||
onLoad={handleIframeLoad}
|
||||
/>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
return (
|
||||
<div className="space-y-6">
|
||||
{/* Quick Links */}
|
||||
<div className="bg-white border border-slate-200 rounded-xl p-4">
|
||||
<h3 className="text-sm font-semibold text-slate-700 mb-3 flex items-center gap-2">
|
||||
<Search className="w-4 h-4" />
|
||||
Schnellzugriff
|
||||
</h3>
|
||||
<div className="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-6 gap-2">
|
||||
{quickLinks.map((link) => (
|
||||
<button
|
||||
key={link.path}
|
||||
onClick={() => navigateTo(link.path)}
|
||||
className="flex items-center gap-2 px-3 py-2 text-sm bg-slate-50 hover:bg-slate-100 border border-slate-200 rounded-lg transition-colors text-left"
|
||||
>
|
||||
<span>{link.icon}</span>
|
||||
<span className="truncate">{link.name}</span>
|
||||
</button>
|
||||
))}
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{/* Toolbar */}
|
||||
<div className="flex items-center justify-between bg-white border border-slate-200 rounded-xl p-3">
|
||||
<div className="flex items-center gap-2">
|
||||
<BookOpen className="w-5 h-5 text-slate-500" />
|
||||
<span className="text-sm font-medium text-slate-700">
|
||||
BreakPilot Compliance Dokumentation
|
||||
</span>
|
||||
<span className="text-xs text-slate-400">
|
||||
(MkDocs Material)
|
||||
</span>
|
||||
</div>
|
||||
<div className="flex items-center gap-2">
|
||||
<button
|
||||
onClick={refreshDocs}
|
||||
className="p-2 text-slate-500 hover:text-slate-700 hover:bg-slate-100 rounded-lg transition-colors"
|
||||
title="Aktualisieren"
|
||||
>
|
||||
<RefreshCw className={`w-4 h-4 ${isLoading ? 'animate-spin' : ''}`} />
|
||||
</button>
|
||||
<button
|
||||
onClick={openInNewTab}
|
||||
className="p-2 text-slate-500 hover:text-slate-700 hover:bg-slate-100 rounded-lg transition-colors"
|
||||
title="In neuem Tab oeffnen"
|
||||
>
|
||||
<ExternalLink className="w-4 h-4" />
|
||||
</button>
|
||||
<button
|
||||
onClick={toggleFullscreen}
|
||||
className="p-2 text-slate-500 hover:text-slate-700 hover:bg-slate-100 rounded-lg transition-colors"
|
||||
title="Vollbild"
|
||||
>
|
||||
<Maximize2 className="w-4 h-4" />
|
||||
</button>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{/* Documentation Iframe */}
|
||||
<div className="relative bg-white border border-slate-200 rounded-xl overflow-hidden" style={{ height: 'calc(100vh - 350px)', minHeight: '500px' }}>
|
||||
{isLoading && (
|
||||
<div className="absolute inset-0 bg-white flex items-center justify-center z-10">
|
||||
<div className="flex flex-col items-center gap-3">
|
||||
<div className="w-8 h-8 border-2 border-slate-300 border-t-slate-600 rounded-full animate-spin" />
|
||||
<span className="text-sm text-slate-500">Dokumentation wird geladen...</span>
|
||||
</div>
|
||||
</div>
|
||||
)}
|
||||
<iframe
|
||||
key={currentPath}
|
||||
src={`${docsUrl}/${currentPath}`}
|
||||
className="w-full h-full"
|
||||
title="BreakPilot Compliance Documentation"
|
||||
onLoad={handleIframeLoad}
|
||||
/>
|
||||
</div>
|
||||
|
||||
{/* Info Box */}
|
||||
<div className="bg-slate-50 border border-slate-200 rounded-xl p-4">
|
||||
<div className="flex items-start gap-3">
|
||||
<div className="p-2 bg-slate-200 rounded-lg">
|
||||
<ArrowRight className="w-4 h-4 text-slate-600" />
|
||||
</div>
|
||||
<div>
|
||||
<h4 className="font-medium text-slate-800">Dokumentation bearbeiten</h4>
|
||||
<p className="text-sm text-slate-600 mt-1">
|
||||
Die Dokumentation befindet sich im Repository unter <code className="text-xs bg-slate-200 px-1.5 py-0.5 rounded">docs-src/</code>.
|
||||
Nach Aenderungen muss der Docs-Container neu gebaut werden:
|
||||
</p>
|
||||
<div className="mt-2 text-xs text-slate-500 font-mono bg-slate-100 p-2 rounded">
|
||||
docker compose --profile docs build docs && docker compose --profile docs up -d docs
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
@@ -8,6 +8,15 @@ import type {
|
||||
CatalogFieldSchema,
|
||||
} from '@/lib/sdk/catalog-manager/types'
|
||||
|
||||
// Resolve localized text objects to German string for display
|
||||
function resolveDisplayValue(value: unknown): unknown {
|
||||
if (value === null || value === undefined) return value
|
||||
if (typeof value === 'object' && !Array.isArray(value) && 'de' in (value as Record<string, unknown>)) {
|
||||
return String((value as Record<string, string>).de || '')
|
||||
}
|
||||
return value
|
||||
}
|
||||
|
||||
interface CatalogEntryFormProps {
|
||||
catalog: CatalogMeta
|
||||
entry?: CatalogEntry | null
|
||||
@@ -39,7 +48,7 @@ export default function CatalogEntryForm({
|
||||
if (isEditMode && entry) {
|
||||
const initialData: Record<string, unknown> = {}
|
||||
for (const field of catalog.fields) {
|
||||
initialData[field.key] = entry.data?.[field.key] ?? getDefaultValue(field)
|
||||
initialData[field.key] = resolveDisplayValue(entry.data?.[field.key]) ?? getDefaultValue(field)
|
||||
}
|
||||
setFormData(initialData)
|
||||
} else {
|
||||
|
||||
@@ -66,7 +66,7 @@ interface CategoryCardProps {
|
||||
export function CategoryCard({ category, showModuleCount = true }: CategoryCardProps) {
|
||||
return (
|
||||
<Link
|
||||
href={`/${category.id}`}
|
||||
href={category.id === 'compliance-sdk' ? '/sdk' : `/${category.id}`}
|
||||
className="block p-6 rounded-xl border-2 transition-all hover:shadow-lg bg-white"
|
||||
style={{
|
||||
borderColor: `${category.color}40`,
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
* Extracted from admin-v2, keeping only compliance-relevant modules.
|
||||
*/
|
||||
|
||||
export type CategoryId = 'compliance-sdk'
|
||||
export type CategoryId = 'compliance-sdk' | 'development'
|
||||
|
||||
export interface NavModule {
|
||||
id: string
|
||||
@@ -15,8 +15,8 @@ export interface NavModule {
|
||||
purpose: string
|
||||
audience: string[]
|
||||
gdprArticles?: string[]
|
||||
oldAdminPath?: string // Reference to old admin for migration
|
||||
subgroup?: string // Optional subgroup for visual grouping in sidebar
|
||||
oldAdminPath?: string
|
||||
subgroup?: string
|
||||
}
|
||||
|
||||
export interface NavCategory {
|
||||
@@ -51,6 +51,27 @@ export const navigation: NavCategory[] = [
|
||||
},
|
||||
],
|
||||
},
|
||||
// =========================================================================
|
||||
// Development - Entwickler-Tools und Dokumentation
|
||||
// =========================================================================
|
||||
{
|
||||
id: 'development',
|
||||
name: 'Entwicklung',
|
||||
icon: 'code',
|
||||
color: '#0ea5e9', // Sky-500
|
||||
colorClass: 'development',
|
||||
description: 'Dokumentation & Entwickler-Tools',
|
||||
modules: [
|
||||
{
|
||||
id: 'docs',
|
||||
name: 'Dokumentation',
|
||||
href: '/development/docs',
|
||||
description: 'MkDocs Projekt-Dokumentation',
|
||||
purpose: 'Technische Dokumentation der Compliance-Plattform mit Architektur, API-Referenz und Entwickler-Guides.',
|
||||
audience: ['Entwickler', 'Architekten'],
|
||||
},
|
||||
],
|
||||
},
|
||||
]
|
||||
|
||||
// Meta modules (always visible)
|
||||
|
||||
@@ -298,9 +298,78 @@ export const CATALOG_REGISTRY: Record<CatalogId, CatalogMeta> = {
|
||||
{ key: 'id', label: 'ID', type: 'text', required: true },
|
||||
{ key: 'name', label: 'Name', type: 'text', required: true },
|
||||
{ key: 'description', label: 'Beschreibung', type: 'textarea', required: true },
|
||||
{ key: 'serviceCategory', label: 'Kategorie', type: 'text', required: true },
|
||||
{ key: 'serviceCategory', label: 'Dienstleistungskategorie', type: 'select', required: true, options: [
|
||||
{ value: 'HOSTING', label: 'Hosting' },
|
||||
{ value: 'CLOUD_INFRASTRUCTURE', label: 'Cloud-Infrastruktur' },
|
||||
{ value: 'ANALYTICS', label: 'Analyse' },
|
||||
{ value: 'CRM', label: 'CRM' },
|
||||
{ value: 'ERP', label: 'ERP' },
|
||||
{ value: 'HR_SOFTWARE', label: 'HR-Software' },
|
||||
{ value: 'PAYMENT', label: 'Zahlungsdienstleister' },
|
||||
{ value: 'EMAIL', label: 'E-Mail' },
|
||||
{ value: 'MARKETING', label: 'Marketing' },
|
||||
{ value: 'SUPPORT', label: 'Support' },
|
||||
{ value: 'SECURITY', label: 'Sicherheit' },
|
||||
{ value: 'COMMUNICATION', label: 'Kommunikation' },
|
||||
{ value: 'STORAGE', label: 'Speicher' },
|
||||
{ value: 'BACKUP', label: 'Backup' },
|
||||
{ value: 'CDN', label: 'CDN' },
|
||||
{ value: 'ACCOUNTING', label: 'Buchhaltung' },
|
||||
{ value: 'CONSULTING', label: 'Beratung' },
|
||||
{ value: 'OTHER', label: 'Sonstige' },
|
||||
]},
|
||||
{ key: 'suggestedRole', label: 'Vorgeschlagene Rolle', type: 'select', required: false, options: [
|
||||
{ value: 'PROCESSOR', label: 'Auftragsverarbeiter' },
|
||||
{ value: 'JOINT_CONTROLLER', label: 'Gemeinsam Verantwortlicher' },
|
||||
{ value: 'CONTROLLER', label: 'Eigenstaendiger Verantwortlicher' },
|
||||
{ value: 'SUB_PROCESSOR', label: 'Unterauftragnehmer' },
|
||||
{ value: 'THIRD_PARTY', label: 'Dritter' },
|
||||
]},
|
||||
{ key: 'suggestedDataAccess', label: 'Datenzugriff', type: 'select', required: false, options: [
|
||||
{ value: 'NONE', label: 'Kein Zugriff' },
|
||||
{ value: 'POTENTIAL', label: 'Potenzieller Zugriff' },
|
||||
{ value: 'ADMINISTRATIVE', label: 'Administrativer Zugriff' },
|
||||
{ value: 'CONTENT', label: 'Inhaltlicher Zugriff' },
|
||||
]},
|
||||
{ key: 'suggestedTransferMechanisms', label: 'Transfer-Mechanismen', type: 'multiselect', required: false, options: [
|
||||
{ value: 'ADEQUACY_DECISION', label: 'Angemessenheitsbeschluss' },
|
||||
{ value: 'SCC_CONTROLLER', label: 'SCC Controller-to-Controller' },
|
||||
{ value: 'SCC_PROCESSOR', label: 'SCC Controller-to-Processor' },
|
||||
{ value: 'BCR', label: 'Binding Corporate Rules' },
|
||||
{ value: 'DEROGATION_CONSENT', label: 'Einwilligung' },
|
||||
{ value: 'DEROGATION_CONTRACT', label: 'Vertragserfuellung' },
|
||||
{ value: 'CERTIFICATION', label: 'Zertifizierung' },
|
||||
{ value: 'CODE_OF_CONDUCT', label: 'Verhaltensregeln' },
|
||||
]},
|
||||
{ key: 'suggestedContractTypes', label: 'Vertragstypen', type: 'multiselect', required: false, options: [
|
||||
{ value: 'AVV', label: 'AVV (Auftragsverarbeitung)' },
|
||||
{ value: 'MSA', label: 'MSA (Master Service)' },
|
||||
{ value: 'SLA', label: 'SLA (Service Level)' },
|
||||
{ value: 'SCC', label: 'SCC (Standardvertragsklauseln)' },
|
||||
{ value: 'NDA', label: 'NDA (Geheimhaltung)' },
|
||||
{ value: 'TOM_ANNEX', label: 'TOM-Anlage' },
|
||||
{ value: 'CERTIFICATION', label: 'Zertifikat' },
|
||||
{ value: 'SUB_PROCESSOR_LIST', label: 'Unterauftragnehmer-Liste' },
|
||||
]},
|
||||
{ key: 'typicalDataCategories', label: 'Typische Datenkategorien', type: 'multiselect', required: false, options: [
|
||||
{ value: 'NAME', label: 'Name' },
|
||||
{ value: 'CONTACT', label: 'Kontaktdaten' },
|
||||
{ value: 'ADDRESS', label: 'Adressdaten' },
|
||||
{ value: 'DOB', label: 'Geburtsdatum' },
|
||||
{ value: 'BANK_ACCOUNT', label: 'Bankverbindung' },
|
||||
{ value: 'PAYMENT_DATA', label: 'Zahlungsdaten' },
|
||||
{ value: 'EMPLOYMENT_DATA', label: 'Beschaeftigungsdaten' },
|
||||
{ value: 'SALARY_DATA', label: 'Gehaltsdaten' },
|
||||
{ value: 'HEALTH_DATA', label: 'Gesundheitsdaten' },
|
||||
{ value: 'IP_ADDRESS', label: 'IP-Adresse' },
|
||||
{ value: 'USAGE_DATA', label: 'Nutzungsdaten' },
|
||||
{ value: 'LOCATION_DATA', label: 'Standortdaten' },
|
||||
{ value: 'COMMUNICATION_DATA', label: 'Kommunikationsdaten' },
|
||||
]},
|
||||
{ key: 'typicalCertifications', label: 'Typische Zertifizierungen', type: 'tags', required: false, placeholder: 'z.B. ISO 27001, SOC 2, C5' },
|
||||
{ key: 'commonProviders', label: 'Typische Anbieter', type: 'tags', required: false, placeholder: 'z.B. AWS, Azure, GCP' },
|
||||
],
|
||||
searchableFields: ['id', 'name', 'description', 'serviceCategory'],
|
||||
searchableFields: ['id', 'name', 'description', 'serviceCategory', 'suggestedRole', 'commonProviders'],
|
||||
},
|
||||
|
||||
'country-risk-profiles': {
|
||||
|
||||
@@ -205,3 +205,24 @@ services:
|
||||
restart: unless-stopped
|
||||
networks:
|
||||
- breakpilot-network
|
||||
|
||||
# =========================================================
|
||||
# DOCUMENTATION
|
||||
# =========================================================
|
||||
docs:
|
||||
build:
|
||||
context: .
|
||||
dockerfile: docs-src/Dockerfile
|
||||
container_name: bp-compliance-docs
|
||||
profiles: [docs]
|
||||
platform: linux/arm64
|
||||
ports:
|
||||
- "8011:80"
|
||||
healthcheck:
|
||||
test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1:80/"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
restart: unless-stopped
|
||||
networks:
|
||||
- breakpilot-network
|
||||
|
||||
48
docs-src/Dockerfile
Normal file
48
docs-src/Dockerfile
Normal file
@@ -0,0 +1,48 @@
|
||||
# ============================================
|
||||
# BreakPilot Compliance Dokumentation - MkDocs Build
|
||||
# Multi-stage build fuer minimale Image-Groesse
|
||||
# ============================================
|
||||
|
||||
# Stage 1: Build MkDocs Site
|
||||
FROM python:3.11-slim AS builder
|
||||
|
||||
WORKDIR /docs
|
||||
|
||||
RUN pip install --no-cache-dir \
|
||||
mkdocs==1.6.1 \
|
||||
mkdocs-material==9.5.47 \
|
||||
pymdown-extensions==10.12
|
||||
|
||||
COPY mkdocs.yml /docs/
|
||||
COPY docs-src/ /docs/docs-src/
|
||||
|
||||
RUN mkdocs build
|
||||
|
||||
# Stage 2: Serve with Nginx
|
||||
FROM nginx:alpine
|
||||
|
||||
COPY --from=builder /docs/docs-site /usr/share/nginx/html
|
||||
|
||||
RUN echo 'server { \
|
||||
listen 80; \
|
||||
server_name localhost; \
|
||||
root /usr/share/nginx/html; \
|
||||
index index.html; \
|
||||
location / { \
|
||||
try_files $uri $uri/ /index.html; \
|
||||
} \
|
||||
gzip on; \
|
||||
gzip_types text/plain text/css application/json application/javascript text/xml application/xml; \
|
||||
gzip_min_length 1000; \
|
||||
location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ { \
|
||||
expires 1y; \
|
||||
add_header Cache-Control "public, immutable"; \
|
||||
} \
|
||||
}' > /etc/nginx/conf.d/default.conf
|
||||
|
||||
EXPOSE 80
|
||||
|
||||
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
|
||||
CMD wget --no-verbose --tries=1 --spider http://localhost/ || exit 1
|
||||
|
||||
CMD ["nginx", "-g", "daemon off;"]
|
||||
402
docs-src/development/ci-cd-pipeline.md
Normal file
402
docs-src/development/ci-cd-pipeline.md
Normal file
@@ -0,0 +1,402 @@
|
||||
# CI/CD Pipeline
|
||||
|
||||
Übersicht über den Deployment-Prozess für Breakpilot.
|
||||
|
||||
## Übersicht
|
||||
|
||||
| Komponente | Build-Tool | Deployment |
|
||||
|------------|------------|------------|
|
||||
| Frontend (Next.js) | Docker | Mac Mini |
|
||||
| Backend (FastAPI) | Docker | Mac Mini |
|
||||
| Go Services | Docker (Multi-stage) | Mac Mini |
|
||||
| Documentation | MkDocs | Docker (Nginx) |
|
||||
|
||||
## Deployment-Architektur
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Entwickler-MacBook │
|
||||
│ │
|
||||
│ breakpilot-pwa/ │
|
||||
│ ├── studio-v2/ (Next.js Frontend) │
|
||||
│ ├── admin-v2/ (Next.js Admin) │
|
||||
│ ├── backend/ (Python FastAPI) │
|
||||
│ ├── consent-service/ (Go Service) │
|
||||
│ ├── klausur-service/ (Python FastAPI) │
|
||||
│ ├── voice-service/ (Python FastAPI) │
|
||||
│ ├── ai-compliance-sdk/ (Go Service) │
|
||||
│ └── docs-src/ (MkDocs) │
|
||||
│ │
|
||||
│ $ ./sync-and-deploy.sh │
|
||||
└───────────────────────────────┬─────────────────────────────────┘
|
||||
│
|
||||
│ rsync + SSH
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Mac Mini Server │
|
||||
│ │
|
||||
│ Docker Compose │
|
||||
│ ├── website (Port 3000) │
|
||||
│ ├── studio-v2 (Port 3001) │
|
||||
│ ├── admin-v2 (Port 3002) │
|
||||
│ ├── backend (Port 8000) │
|
||||
│ ├── consent-service (Port 8081) │
|
||||
│ ├── klausur-service (Port 8086) │
|
||||
│ ├── voice-service (Port 8082) │
|
||||
│ ├── ai-compliance-sdk (Port 8090) │
|
||||
│ ├── docs (Port 8009) │
|
||||
│ ├── postgres │
|
||||
│ ├── valkey (Redis) │
|
||||
│ ├── qdrant │
|
||||
│ └── minio │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Sync & Deploy Workflow
|
||||
|
||||
### 1. Dateien synchronisieren
|
||||
|
||||
```bash
|
||||
# Sync aller relevanten Verzeichnisse zum Mac Mini
|
||||
rsync -avz --delete \
|
||||
--exclude 'node_modules' \
|
||||
--exclude '.next' \
|
||||
--exclude '.git' \
|
||||
--exclude '__pycache__' \
|
||||
--exclude 'venv' \
|
||||
--exclude '.pytest_cache' \
|
||||
/Users/benjaminadmin/Projekte/breakpilot-pwa/ \
|
||||
macmini:/Users/benjaminadmin/Projekte/breakpilot-pwa/
|
||||
```
|
||||
|
||||
### 2. Container bauen
|
||||
|
||||
```bash
|
||||
# Einzelnen Service bauen
|
||||
ssh macmini "/usr/local/bin/docker compose \
|
||||
-f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml \
|
||||
build --no-cache <service-name>"
|
||||
|
||||
# Beispiele:
|
||||
# studio-v2, admin-v2, website, backend, klausur-service, docs
|
||||
```
|
||||
|
||||
### 3. Container deployen
|
||||
|
||||
```bash
|
||||
# Container neu starten
|
||||
ssh macmini "/usr/local/bin/docker compose \
|
||||
-f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml \
|
||||
up -d <service-name>"
|
||||
```
|
||||
|
||||
### 4. Logs prüfen
|
||||
|
||||
```bash
|
||||
# Container-Logs anzeigen
|
||||
ssh macmini "/usr/local/bin/docker compose \
|
||||
-f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml \
|
||||
logs -f <service-name>"
|
||||
```
|
||||
|
||||
## Service-spezifische Deployments
|
||||
|
||||
### Next.js Frontend (studio-v2, admin-v2, website)
|
||||
|
||||
```bash
|
||||
# 1. Sync
|
||||
rsync -avz --delete \
|
||||
--exclude 'node_modules' --exclude '.next' --exclude '.git' \
|
||||
/Users/benjaminadmin/Projekte/breakpilot-pwa/studio-v2/ \
|
||||
macmini:/Users/benjaminadmin/Projekte/breakpilot-pwa/studio-v2/
|
||||
|
||||
# 2. Build & Deploy
|
||||
ssh macmini "/usr/local/bin/docker compose \
|
||||
-f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml \
|
||||
build --no-cache studio-v2 && \
|
||||
/usr/local/bin/docker compose \
|
||||
-f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml \
|
||||
up -d studio-v2"
|
||||
```
|
||||
|
||||
### Python Services (backend, klausur-service, voice-service)
|
||||
|
||||
```bash
|
||||
# Build mit requirements.txt
|
||||
ssh macmini "/usr/local/bin/docker compose \
|
||||
-f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml \
|
||||
build klausur-service && \
|
||||
/usr/local/bin/docker compose \
|
||||
-f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml \
|
||||
up -d klausur-service"
|
||||
```
|
||||
|
||||
### Go Services (consent-service, ai-compliance-sdk)
|
||||
|
||||
```bash
|
||||
# Multi-stage Build (Go → Alpine)
|
||||
ssh macmini "/usr/local/bin/docker compose \
|
||||
-f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml \
|
||||
build --no-cache consent-service && \
|
||||
/usr/local/bin/docker compose \
|
||||
-f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml \
|
||||
up -d consent-service"
|
||||
```
|
||||
|
||||
### MkDocs Dokumentation
|
||||
|
||||
```bash
|
||||
# Build & Deploy
|
||||
ssh macmini "/usr/local/bin/docker compose \
|
||||
-f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml \
|
||||
build --no-cache docs && \
|
||||
/usr/local/bin/docker compose \
|
||||
-f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml \
|
||||
up -d docs"
|
||||
|
||||
# Verfügbar unter: http://macmini:8009
|
||||
```
|
||||
|
||||
## Health Checks
|
||||
|
||||
### Service-Status prüfen
|
||||
|
||||
```bash
|
||||
# Alle Container-Status
|
||||
ssh macmini "docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'"
|
||||
|
||||
# Health-Endpoints prüfen
|
||||
curl -s http://macmini:8000/health
|
||||
curl -s http://macmini:8081/health
|
||||
curl -s http://macmini:8086/health
|
||||
curl -s http://macmini:8090/health
|
||||
```
|
||||
|
||||
### Logs analysieren
|
||||
|
||||
```bash
|
||||
# Letzte 100 Zeilen
|
||||
ssh macmini "docker logs --tail 100 breakpilot-pwa-backend-1"
|
||||
|
||||
# Live-Logs folgen
|
||||
ssh macmini "docker logs -f breakpilot-pwa-backend-1"
|
||||
```
|
||||
|
||||
## Rollback
|
||||
|
||||
### Container auf vorherige Version zurücksetzen
|
||||
|
||||
```bash
|
||||
# 1. Aktuelles Image taggen
|
||||
ssh macmini "docker tag breakpilot-pwa-backend:latest breakpilot-pwa-backend:backup"
|
||||
|
||||
# 2. Altes Image deployen
|
||||
ssh macmini "/usr/local/bin/docker compose \
|
||||
-f /Users/benjaminadmin/Projekte/breakpilot-pwa/docker-compose.yml \
|
||||
up -d backend"
|
||||
|
||||
# 3. Bei Problemen: Backup wiederherstellen
|
||||
ssh macmini "docker tag breakpilot-pwa-backend:backup breakpilot-pwa-backend:latest"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Container startet nicht
|
||||
|
||||
```bash
|
||||
# 1. Logs prüfen
|
||||
ssh macmini "docker logs breakpilot-pwa-<service>-1"
|
||||
|
||||
# 2. Container manuell starten für Debug-Output
|
||||
ssh macmini "docker compose -f .../docker-compose.yml run --rm <service>"
|
||||
|
||||
# 3. In Container einloggen
|
||||
ssh macmini "docker exec -it breakpilot-pwa-<service>-1 /bin/sh"
|
||||
```
|
||||
|
||||
### Port bereits belegt
|
||||
|
||||
```bash
|
||||
# Port-Belegung prüfen
|
||||
ssh macmini "lsof -i :8000"
|
||||
|
||||
# Container mit dem Port finden
|
||||
ssh macmini "docker ps --filter publish=8000"
|
||||
```
|
||||
|
||||
### Build-Fehler
|
||||
|
||||
```bash
|
||||
# Cache komplett leeren
|
||||
ssh macmini "docker builder prune -a"
|
||||
|
||||
# Ohne Cache bauen
|
||||
ssh macmini "docker compose build --no-cache <service>"
|
||||
```
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Resource-Nutzung
|
||||
|
||||
```bash
|
||||
# CPU/Memory aller Container
|
||||
ssh macmini "docker stats --no-stream"
|
||||
|
||||
# Disk-Nutzung
|
||||
ssh macmini "docker system df"
|
||||
```
|
||||
|
||||
### Cleanup
|
||||
|
||||
```bash
|
||||
# Ungenutzte Images/Container entfernen
|
||||
ssh macmini "docker system prune -a --volumes"
|
||||
|
||||
# Nur dangling Images
|
||||
ssh macmini "docker image prune"
|
||||
```
|
||||
|
||||
## Umgebungsvariablen
|
||||
|
||||
Umgebungsvariablen werden über `.env` Dateien und docker-compose.yml verwaltet:
|
||||
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
services:
|
||||
backend:
|
||||
environment:
|
||||
- DATABASE_URL=postgresql://...
|
||||
- REDIS_URL=redis://valkey:6379
|
||||
- SECRET_KEY=${SECRET_KEY}
|
||||
```
|
||||
|
||||
**Wichtig**: Sensible Werte niemals in Git committen. Stattdessen:
|
||||
- `.env` Datei auf dem Server pflegen
|
||||
- Secrets über HashiCorp Vault (siehe unten)
|
||||
|
||||
## Woodpecker CI - Automatisierte OAuth Integration
|
||||
|
||||
### Überblick
|
||||
|
||||
Die OAuth-Integration zwischen Woodpecker CI und Gitea ist **vollständig automatisiert**. Credentials werden in HashiCorp Vault gespeichert und bei Bedarf automatisch regeneriert.
|
||||
|
||||
!!! info "Warum automatisiert?"
|
||||
Diese Automatisierung ist eine DevSecOps Best Practice:
|
||||
|
||||
- **Infrastructure-as-Code**: Alles ist reproduzierbar
|
||||
- **Disaster Recovery**: Verlorene Credentials können automatisch regeneriert werden
|
||||
- **Security**: Secrets werden zentral in Vault verwaltet
|
||||
- **Onboarding**: Neue Entwickler müssen nichts manuell konfigurieren
|
||||
|
||||
### Architektur
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Mac Mini Server │
|
||||
│ │
|
||||
│ ┌───────────────┐ OAuth 2.0 ┌───────────────┐ │
|
||||
│ │ Gitea │ ←─────────────────────────→│ Woodpecker │ │
|
||||
│ │ (Port 3003) │ Client ID + Secret │ (Port 8090) │ │
|
||||
│ └───────────────┘ └───────────────┘ │
|
||||
│ │ │ │
|
||||
│ │ OAuth App │ Env Vars│
|
||||
│ │ (DB: oauth2_application) │ │
|
||||
│ │ │ │
|
||||
│ ▼ ▼ │
|
||||
│ ┌───────────────────────────────────────────────────────────┐ │
|
||||
│ │ HashiCorp Vault (Port 8200) │ │
|
||||
│ │ │ │
|
||||
│ │ secret/cicd/woodpecker: │ │
|
||||
│ │ - gitea_client_id │ │
|
||||
│ │ - gitea_client_secret │ │
|
||||
│ │ │ │
|
||||
│ │ secret/cicd/api-tokens: │ │
|
||||
│ │ - gitea_token (für API-Zugriff) │ │
|
||||
│ │ - woodpecker_token (für Pipeline-Trigger) │ │
|
||||
│ └───────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Credentials-Speicherorte
|
||||
|
||||
| Ort | Pfad | Inhalt |
|
||||
|-----|------|--------|
|
||||
| **HashiCorp Vault** | `secret/cicd/woodpecker` | Client ID + Secret (Quelle der Wahrheit) |
|
||||
| **.env Datei** | `WOODPECKER_GITEA_CLIENT/SECRET` | Für Docker Compose (aus Vault geladen) |
|
||||
| **Gitea PostgreSQL** | `oauth2_application` Tabelle | OAuth App Registration (gehashtes Secret) |
|
||||
|
||||
### Troubleshooting: OAuth Fehler
|
||||
|
||||
Falls der Fehler "Client ID not registered" oder "user does not exist [uid: 0]" auftritt:
|
||||
|
||||
```bash
|
||||
# Option 1: Automatisches Regenerieren (empfohlen)
|
||||
./scripts/sync-woodpecker-credentials.sh --regenerate
|
||||
|
||||
# Option 2: Manuelles Vorgehen
|
||||
# 1. Credentials aus Vault laden
|
||||
vault kv get secret/cicd/woodpecker
|
||||
|
||||
# 2. .env aktualisieren
|
||||
WOODPECKER_GITEA_CLIENT=<client_id>
|
||||
WOODPECKER_GITEA_SECRET=<client_secret>
|
||||
|
||||
# 3. Zu Mac Mini synchronisieren
|
||||
rsync .env macmini:~/Projekte/breakpilot-pwa/
|
||||
|
||||
# 4. Woodpecker neu starten
|
||||
ssh macmini "cd ~/Projekte/breakpilot-pwa && \
|
||||
docker compose up -d --force-recreate woodpecker-server"
|
||||
```
|
||||
|
||||
### Das Sync-Script
|
||||
|
||||
Das Script `scripts/sync-woodpecker-credentials.sh` automatisiert den gesamten Prozess:
|
||||
|
||||
```bash
|
||||
# Credentials aus Vault laden und .env aktualisieren
|
||||
./scripts/sync-woodpecker-credentials.sh
|
||||
|
||||
# Neue Credentials generieren (OAuth App in Gitea + Vault + .env)
|
||||
./scripts/sync-woodpecker-credentials.sh --regenerate
|
||||
```
|
||||
|
||||
Was das Script macht:
|
||||
|
||||
1. **Liest** die aktuellen Credentials aus Vault
|
||||
2. **Aktualisiert** die .env Datei automatisch
|
||||
3. **Bei `--regenerate`**:
|
||||
- Löscht alte OAuth Apps in Gitea
|
||||
- Erstellt neue OAuth App mit neuem Client ID/Secret
|
||||
- Speichert Credentials in Vault
|
||||
- Aktualisiert .env
|
||||
|
||||
### Vault-Zugriff
|
||||
|
||||
```bash
|
||||
# Vault Token (Development)
|
||||
export VAULT_TOKEN=breakpilot-dev-token
|
||||
|
||||
# Credentials lesen
|
||||
docker exec -e VAULT_TOKEN=$VAULT_TOKEN breakpilot-pwa-vault \
|
||||
vault kv get secret/cicd/woodpecker
|
||||
|
||||
# Credentials setzen
|
||||
docker exec -e VAULT_TOKEN=$VAULT_TOKEN breakpilot-pwa-vault \
|
||||
vault kv put secret/cicd/woodpecker \
|
||||
gitea_client_id="..." \
|
||||
gitea_client_secret="..."
|
||||
```
|
||||
|
||||
### Services neustarten nach Credentials-Änderung
|
||||
|
||||
```bash
|
||||
# Wichtig: --force-recreate um neue Env Vars zu laden
|
||||
cd /Users/benjaminadmin/Projekte/breakpilot-pwa
|
||||
docker compose up -d --force-recreate woodpecker-server
|
||||
|
||||
# Logs prüfen
|
||||
docker logs breakpilot-pwa-woodpecker-server --tail 50
|
||||
```
|
||||
159
docs-src/development/documentation.md
Normal file
159
docs-src/development/documentation.md
Normal file
@@ -0,0 +1,159 @@
|
||||
# Dokumentations-Regeln
|
||||
|
||||
## Automatische Dokumentations-Aktualisierung
|
||||
|
||||
**WICHTIG:** Bei JEDER Code-Aenderung muss die entsprechende Dokumentation aktualisiert werden!
|
||||
|
||||
## Wann Dokumentation aktualisieren?
|
||||
|
||||
### API-Aenderungen
|
||||
|
||||
Wenn du einen Endpoint aenderst, hinzufuegst oder entfernst:
|
||||
|
||||
- Aktualisiere die [Backend API Dokumentation](../api/backend-api.md)
|
||||
- Aktualisiere Service-spezifische API-Docs
|
||||
|
||||
### Neue Funktionen/Klassen
|
||||
|
||||
Wenn du neue Funktionen, Klassen oder Module erstellst:
|
||||
|
||||
- Aktualisiere die entsprechende Service-Dokumentation
|
||||
- Fuege Code-Beispiele hinzu
|
||||
|
||||
### Architektur-Aenderungen
|
||||
|
||||
Wenn du die Systemarchitektur aenderst:
|
||||
|
||||
- Aktualisiere die [System-Architektur](../architecture/system-architecture.md)
|
||||
- Aktualisiere Datenmodell-Dokumentation bei DB-Aenderungen
|
||||
|
||||
### Neue Konfigurationsoptionen
|
||||
|
||||
Wenn du neue Umgebungsvariablen oder Konfigurationen hinzufuegst:
|
||||
|
||||
- Aktualisiere die entsprechende README
|
||||
- Fuege zur [Umgebungs-Setup](../getting-started/environment-setup.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
|
||||
|
||||
**Rueckgabe:** Beschreibung
|
||||
```
|
||||
|
||||
## Checkliste nach Code-Aenderungen
|
||||
|
||||
Vor dem Abschluss einer Aufgabe pruefen:
|
||||
|
||||
- [ ] Wurden neue API-Endpoints hinzugefuegt? → API-Docs aktualisieren
|
||||
- [ ] Wurden Datenmodelle geaendert? → Architektur-Docs aktualisieren
|
||||
- [ ] Wurden neue Konfigurationen hinzugefuegt? → README aktualisieren
|
||||
- [ ] Wurden neue Abhaengigkeiten hinzugefuegt? → requirements.txt/go.mod UND Docs
|
||||
- [ ] Wurde die Architektur geaendert? → architecture/ aktualisieren
|
||||
|
||||
## Beispiel: Vollstaendige Dokumentation einer neuen Funktion
|
||||
|
||||
Wenn du z.B. `GetUserStats()` im Go Service hinzufuegst:
|
||||
|
||||
1. **Code schreiben** in `internal/services/stats_service.go`
|
||||
2. **API-Doc aktualisieren** in der API-Dokumentation
|
||||
3. **Service-Doc aktualisieren** in der Service-README
|
||||
4. **Test schreiben** (siehe [Testing](./testing.md))
|
||||
|
||||
## Dokumentations-Struktur
|
||||
|
||||
Die zentrale Dokumentation befindet sich unter `docs-src/`:
|
||||
|
||||
```
|
||||
docs-src/
|
||||
├── index.md # Startseite
|
||||
├── getting-started/ # Erste Schritte
|
||||
│ ├── environment-setup.md
|
||||
│ └── mac-mini-setup.md
|
||||
├── architecture/ # Architektur-Dokumentation
|
||||
│ ├── system-architecture.md
|
||||
│ ├── auth-system.md
|
||||
│ └── ...
|
||||
├── api/ # API-Dokumentation
|
||||
│ └── backend-api.md
|
||||
├── services/ # Service-Dokumentation
|
||||
│ ├── klausur-service/
|
||||
│ ├── agent-core/
|
||||
│ └── ...
|
||||
├── development/ # Entwickler-Guides
|
||||
│ ├── testing.md
|
||||
│ └── documentation.md
|
||||
└── guides/ # Weitere Anleitungen
|
||||
```
|
||||
|
||||
## MkDocs Konventionen
|
||||
|
||||
Diese Dokumentation wird mit MkDocs + Material Theme generiert:
|
||||
|
||||
- **Admonitions** fuer Hinweise:
|
||||
```markdown
|
||||
!!! note "Hinweis"
|
||||
Wichtige Information hier.
|
||||
|
||||
!!! warning "Warnung"
|
||||
Vorsicht bei dieser Aktion.
|
||||
```
|
||||
|
||||
- **Code-Tabs** fuer mehrere Sprachen:
|
||||
```markdown
|
||||
=== "Python"
|
||||
```python
|
||||
print("Hello")
|
||||
```
|
||||
|
||||
=== "Go"
|
||||
```go
|
||||
fmt.Println("Hello")
|
||||
```
|
||||
```
|
||||
|
||||
- **Mermaid-Diagramme** fuer Visualisierungen:
|
||||
```markdown
|
||||
```mermaid
|
||||
graph LR
|
||||
A --> B --> C
|
||||
```
|
||||
```
|
||||
211
docs-src/development/testing.md
Normal file
211
docs-src/development/testing.md
Normal file
@@ -0,0 +1,211 @@
|
||||
# Test-Regeln
|
||||
|
||||
## Automatische Test-Erweiterung
|
||||
|
||||
**WICHTIG:** Bei JEDER Code-Aenderung muessen entsprechende Tests erstellt oder aktualisiert werden!
|
||||
|
||||
## Wann Tests schreiben?
|
||||
|
||||
### IMMER wenn du:
|
||||
|
||||
1. **Neue Funktionen** erstellst → Unit Test
|
||||
2. **Neue API-Endpoints** hinzufuegst → Handler Test
|
||||
3. **Bugs fixst** → Regression Test (der Bug sollte nie wieder auftreten)
|
||||
4. **Bestehenden Code aenderst** → 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 fuer consent_client.py
|
||||
└── test_gdpr_api.py ← Tests fuer 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 (Hoechste Prioritaet)
|
||||
|
||||
- Testen einzelne Funktionen/Methoden
|
||||
- Keine externen Abhaengigkeiten (Mocks verwenden)
|
||||
- Schnell ausfuehrbar
|
||||
|
||||
### 2. Integration Tests
|
||||
|
||||
- Testen Zusammenspiel mehrerer Komponenten
|
||||
- Koennen echte DB verwenden (Test-DB)
|
||||
|
||||
### 3. Security Tests
|
||||
|
||||
- Auth/JWT Validierung
|
||||
- Passwort-Hashing
|
||||
- Berechtigungspruefung
|
||||
|
||||
## Checkliste vor Abschluss
|
||||
|
||||
Vor dem Abschluss einer Aufgabe:
|
||||
|
||||
- [ ] Gibt es Tests fuer alle neuen Funktionen?
|
||||
- [ ] Gibt es Tests fuer alle Edge Cases?
|
||||
- [ ] Gibt es Tests fuer Fehlerfaelle?
|
||||
- [ ] Laufen alle bestehenden Tests noch? (`go test ./...` / `pytest`)
|
||||
- [ ] Ist die Test-Coverage angemessen?
|
||||
|
||||
## Tests ausfuehren
|
||||
|
||||
```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: Vollstaendiger Test-Workflow
|
||||
|
||||
Wenn du z.B. eine neue `GetUserStats()` Funktion im Go Service hinzufuegst:
|
||||
|
||||
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 ausfuehren**: `go test -v ./internal/services/...`
|
||||
4. **Dokumentation aktualisieren** (siehe [Dokumentation](./documentation.md))
|
||||
25
docs-src/index.md
Normal file
25
docs-src/index.md
Normal file
@@ -0,0 +1,25 @@
|
||||
# BreakPilot Compliance - Dokumentation
|
||||
|
||||
Willkommen zur Dokumentation der **BreakPilot Compliance SDK Platform**.
|
||||
|
||||
## Module
|
||||
|
||||
- **AI Compliance SDK**: DSGVO-konforme KI-Nutzung
|
||||
- **Backend Compliance**: Compliance APIs
|
||||
- **Developer Portal**: API-Dokumentation
|
||||
|
||||
## SDK-Module
|
||||
|
||||
- TOM (Technisch-Organisatorische Massnahmen)
|
||||
- DSFA (Datenschutz-Folgenabschaetzung)
|
||||
- VVT (Verzeichnis von Verarbeitungstaetigkeiten)
|
||||
- Loeschfristen
|
||||
- AI Act Compliance
|
||||
- Consent Management
|
||||
- DSR (Betroffenenrechte)
|
||||
|
||||
## Entwicklung
|
||||
|
||||
- [Testing](development/testing.md)
|
||||
- [Dokumentation](development/documentation.md)
|
||||
- [CI/CD Pipeline](development/ci-cd-pipeline.md)
|
||||
947
docs-src/services/ai-compliance-sdk/ARCHITECTURE.md
Normal file
947
docs-src/services/ai-compliance-sdk/ARCHITECTURE.md
Normal file
@@ -0,0 +1,947 @@
|
||||
# UCCA - Use-Case Compliance & Feasibility Advisor
|
||||
|
||||
## Systemarchitektur
|
||||
|
||||
### 1. Übersicht
|
||||
|
||||
Das UCCA-System ist ein **deterministisches Compliance-Bewertungssystem** für KI-Anwendungsfälle. Es kombiniert regelbasierte Evaluation mit optionaler LLM-Erklärung und semantischer Rechtstextsuche.
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ UCCA System │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ Frontend │───>│ SDK API │───>│ PostgreSQL │ │
|
||||
│ │ (Next.js) │ │ (Go) │ │ Database │ │
|
||||
│ └──────────────┘ └──────┬───────┘ └──────────────┘ │
|
||||
│ │ │
|
||||
│ ┌────────────────────┼────────────────────┐ │
|
||||
│ │ │ │ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ Policy │ │ Escalation │ │ Legal RAG │ │
|
||||
│ │ Engine │ │ Workflow │ │ (Qdrant) │ │
|
||||
│ │ (45 Regeln) │ │ (E0-E3) │ │ 2,274 Chunks │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
│ │ │ │ │
|
||||
│ └────────────────────┴────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────┐ │
|
||||
│ │ LLM Provider │ │
|
||||
│ │ (Ollama/API) │ │
|
||||
│ └──────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 2. Kernprinzip
|
||||
|
||||
> **"LLM ist NICHT die Quelle der Wahrheit. Wahrheit = Regeln + Evidenz. LLM = Übersetzer + Subsumptionshelfer"**
|
||||
|
||||
Das System folgt einem strikten **Human-in-the-Loop** Ansatz:
|
||||
|
||||
1. **Deterministische Regeln** treffen alle Compliance-Entscheidungen
|
||||
2. **LLM** erklärt nur Ergebnisse, überschreibt nie BLOCK-Entscheidungen
|
||||
3. **Menschen** (DSB, Legal) treffen finale Entscheidungen bei kritischen Fällen
|
||||
|
||||
---
|
||||
|
||||
## 3. Komponenten
|
||||
|
||||
### 3.1 Policy Engine (`internal/ucca/rules.go`)
|
||||
|
||||
Die Policy Engine evaluiert Use-Cases gegen ~45 deterministische Regeln.
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Policy Engine │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ UseCaseIntake ──────────────────────────────────────────────> │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Regelkategorien (A-J) │ │
|
||||
│ ├─────────────────────────────────────────────────────────────┤ │
|
||||
│ │ A. Datenklassifikation │ R-001 bis R-006 │ 6 Regeln │ │
|
||||
│ │ B. Zweck & Kontext │ R-010 bis R-013 │ 4 Regeln │ │
|
||||
│ │ C. Automatisierung │ R-020 bis R-025 │ 6 Regeln │ │
|
||||
│ │ D. Training vs Nutzung │ R-030 bis R-035 │ 6 Regeln │ │
|
||||
│ │ E. Speicherung │ R-040 bis R-042 │ 3 Regeln │ │
|
||||
│ │ F. Hosting │ R-050 bis R-052 │ 3 Regeln │ │
|
||||
│ │ G. Transparenz │ R-060 bis R-062 │ 3 Regeln │ │
|
||||
│ │ H. Domain-spezifisch │ R-070 bis R-074 │ 5 Regeln │ │
|
||||
│ │ I. Aggregation │ R-090 bis R-092 │ 3 Regeln │ │
|
||||
│ │ J. Erklärung │ R-100 │ 1 Regel │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ AssessmentResult │
|
||||
│ ├── feasibility: YES | CONDITIONAL | NO │
|
||||
│ ├── risk_score: 0-100 │
|
||||
│ ├── risk_level: MINIMAL | LOW | MEDIUM | HIGH | CRITICAL │
|
||||
│ ├── triggered_rules: []TriggeredRule │
|
||||
│ ├── required_controls: []RequiredControl │
|
||||
│ ├── recommended_architecture: []PatternRecommendation │
|
||||
│ └── forbidden_patterns: []ForbiddenPattern │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Regel-Severities:**
|
||||
- `INFO`: Informativ, kein Risiko-Impact
|
||||
- `WARN`: Warnung, erhöht Risk Score
|
||||
- `BLOCK`: Kritisch, führt zu `feasibility=NO`
|
||||
|
||||
### 3.2 Escalation Workflow (`internal/ucca/escalation_*.go`)
|
||||
|
||||
Das Eskalationssystem routet kritische Assessments zur menschlichen Prüfung.
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Escalation Workflow │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ AssessmentResult ─────────────────────────────────────────────> │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Escalation Level Determination │ │
|
||||
│ ├─────────────────────────────────────────────────────────────┤ │
|
||||
│ │ │ │
|
||||
│ │ E0: Nur INFO-Regeln, Risk < 20 │ │
|
||||
│ │ → Auto-Approve, keine menschliche Prüfung │ │
|
||||
│ │ │ │
|
||||
│ │ E1: WARN-Regeln, Risk 20-39 │ │
|
||||
│ │ → Team-Lead Review (SLA: 24h) │ │
|
||||
│ │ │ │
|
||||
│ │ E2: Art.9 Daten ODER Risk 40-59 ODER DSFA empfohlen │ │
|
||||
│ │ → DSB Consultation (SLA: 8h) │ │
|
||||
│ │ │ │
|
||||
│ │ E3: BLOCK-Regel ODER Risk ≥60 ODER Art.22 Risiko │ │
|
||||
│ │ → DSB + Legal Review (SLA: 4h) │ │
|
||||
│ │ │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ DSB Pool Assignment │ │
|
||||
│ ├─────────────────────────────────────────────────────────────┤ │
|
||||
│ │ Role │ Level │ Max Concurrent │ Auto-Assign │ │
|
||||
│ │ ──────────────┼───────┼────────────────┼────────────────── │ │
|
||||
│ │ team_lead │ E1 │ 10 │ Round-Robin │ │
|
||||
│ │ dsb │ E2,E3 │ 5 │ Workload-Based │ │
|
||||
│ │ legal │ E3 │ 3 │ Workload-Based │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ Escalation Status Flow: │
|
||||
│ │
|
||||
│ pending → assigned → in_review → approved/rejected/returned │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 3.3 Legal RAG (`internal/llm/legal_rag.go`)
|
||||
|
||||
Semantische Suche in 19 EU-Regulierungen für kontextbasierte Erklärungen.
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Legal RAG System │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Explain Request ──────────────────────────────────────────────> │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Qdrant Vector DB │ │
|
||||
│ │ Collection: bp_legal_corpus │ │
|
||||
│ │ 2,274 Chunks, 1024-dim BGE-M3 │ │
|
||||
│ ├─────────────────────────────────────────────────────────────┤ │
|
||||
│ │ │ │
|
||||
│ │ EU-Verordnungen: │ │
|
||||
│ │ ├── DSGVO (128) ├── AI Act (96) ├── NIS2 (128) │ │
|
||||
│ │ ├── CRA (256) ├── Data Act (256) ├── DSA (256) │ │
|
||||
│ │ ├── DGA (32) ├── EUCSA (32) ├── DPF (714) │ │
|
||||
│ │ └── ... │ │
|
||||
│ │ │ │
|
||||
│ │ Deutsche Gesetze: │ │
|
||||
│ │ ├── TDDDG (1) ├── SCC (32) ├── ... │ │
|
||||
│ │ │ │
|
||||
│ │ BSI-Standards: │ │
|
||||
│ │ ├── TR-03161-1 (6) ├── TR-03161-2 (6) ├── TR-03161-3 │ │
|
||||
│ │ │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ │ Hybrid Search (Dense + Sparse) │
|
||||
│ │ Re-Ranking (Cross-Encoder) │
|
||||
│ ▼ │
|
||||
│ Top-K Relevant Passages ─────────────────────────────────────> │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ LLM Explanation │ │
|
||||
│ │ Provider: Ollama (local) / Anthropic (fallback) │ │
|
||||
│ │ Prompt: Assessment + Legal Context → Erklärung │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Datenfluss
|
||||
|
||||
### 4.1 Assessment-Erstellung
|
||||
|
||||
```
|
||||
User Input (Frontend)
|
||||
│
|
||||
▼
|
||||
POST /sdk/v1/ucca/assess
|
||||
│
|
||||
├──────────────────────────────────────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
┌──────────────┐ ┌──────────────┐
|
||||
│ Policy │ │ Escalation │
|
||||
│ Engine │ │ Trigger │
|
||||
│ Evaluation │ │ Check │
|
||||
└──────┬───────┘ └──────┬───────┘
|
||||
│ │
|
||||
│ AssessmentResult │ EscalationLevel
|
||||
│ │
|
||||
▼ ▼
|
||||
┌──────────────────────────────────────────────────────┐
|
||||
│ PostgreSQL │
|
||||
│ ├── ucca_assessments (Assessment + Result) │
|
||||
│ └── ucca_escalations (wenn Level > E0) │
|
||||
└──────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ If Level > E0
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ DSB Pool │
|
||||
│ Auto-Assign │
|
||||
└──────────────┘
|
||||
│
|
||||
▼
|
||||
Notification (E-Mail/Webhook)
|
||||
```
|
||||
|
||||
### 4.2 Erklärung mit Legal RAG
|
||||
|
||||
```
|
||||
POST /sdk/v1/ucca/assessments/:id/explain
|
||||
│
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ Load │
|
||||
│ Assessment │
|
||||
└──────┬───────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────┐ Query Vector ┌──────────────┐
|
||||
│ Extract │ ──────────────────>│ Qdrant │
|
||||
│ Keywords │ │ bp_legal_ │
|
||||
│ from Rules │<───────────────────│ corpus │
|
||||
└──────┬───────┘ Top-K Docs └──────────────┘
|
||||
│
|
||||
│ Assessment + Legal Context
|
||||
▼
|
||||
┌──────────────┐
|
||||
│ LLM │
|
||||
│ Provider │
|
||||
│ Registry │
|
||||
└──────┬───────┘
|
||||
│
|
||||
▼
|
||||
Explanation (DE) + Legal References
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Entscheidungsdiagramm
|
||||
|
||||
### 5.1 Feasibility-Entscheidung
|
||||
|
||||
```
|
||||
UseCaseIntake
|
||||
│
|
||||
▼
|
||||
┌─────────────────────┐
|
||||
│ Hat BLOCK-Regeln? │
|
||||
└──────────┬──────────┘
|
||||
│ │
|
||||
Ja Nein
|
||||
│ │
|
||||
▼ ▼
|
||||
┌───────────┐ ┌─────────────────────┐
|
||||
│ NO │ │ Hat WARN-Regeln? │
|
||||
│ (blocked) │ └──────────┬──────────┘
|
||||
└───────────┘ │ │
|
||||
Ja Nein
|
||||
│ │
|
||||
▼ ▼
|
||||
┌───────────┐ ┌───────────┐
|
||||
│CONDITIONAL│ │ YES │
|
||||
│(mit │ │(grünes │
|
||||
│Auflagen) │ │Licht) │
|
||||
└───────────┘ └───────────┘
|
||||
```
|
||||
|
||||
### 5.2 Escalation-Level-Entscheidung
|
||||
|
||||
```
|
||||
AssessmentResult
|
||||
│
|
||||
▼
|
||||
┌─────────────────────┐
|
||||
│ BLOCK-Regel oder │
|
||||
│ Art.22 Risiko? │
|
||||
└──────────┬──────────┘
|
||||
│ │
|
||||
Ja Nein
|
||||
│ │
|
||||
▼ │
|
||||
┌───────────┐ │
|
||||
│ E3 │ │
|
||||
│ DSB+Legal │ │
|
||||
└───────────┘ ▼
|
||||
┌─────────────────────┐
|
||||
│ Risk ≥40 oder │
|
||||
│ Art.9 Daten oder │
|
||||
│ DSFA empfohlen? │
|
||||
└──────────┬──────────┘
|
||||
│ │
|
||||
Ja Nein
|
||||
│ │
|
||||
▼ │
|
||||
┌───────────┐ │
|
||||
│ E2 │ │
|
||||
│ DSB │ │
|
||||
└───────────┘ ▼
|
||||
┌─────────────────────┐
|
||||
│ Risk ≥20 oder │
|
||||
│ WARN-Regeln? │
|
||||
└──────────┬──────────┘
|
||||
│ │
|
||||
Ja Nein
|
||||
│ │
|
||||
▼ ▼
|
||||
┌───────────┐ ┌───────────┐
|
||||
│ E1 │ │ E0 │
|
||||
│ Team-Lead │ │ Auto-OK │
|
||||
└───────────┘ └───────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Datenbank-Schema
|
||||
|
||||
### 6.1 ucca_assessments
|
||||
|
||||
```sql
|
||||
CREATE TABLE ucca_assessments (
|
||||
id UUID PRIMARY KEY,
|
||||
tenant_id UUID NOT NULL,
|
||||
namespace_id UUID,
|
||||
title VARCHAR(500),
|
||||
policy_version VARCHAR(50) NOT NULL,
|
||||
status VARCHAR(50) DEFAULT 'completed',
|
||||
|
||||
-- Input
|
||||
intake JSONB NOT NULL,
|
||||
use_case_text_stored BOOLEAN DEFAULT FALSE,
|
||||
use_case_text_hash VARCHAR(64),
|
||||
domain VARCHAR(50),
|
||||
|
||||
-- Result
|
||||
feasibility VARCHAR(20) NOT NULL,
|
||||
risk_level VARCHAR(20) NOT NULL,
|
||||
risk_score INT NOT NULL DEFAULT 0,
|
||||
triggered_rules JSONB DEFAULT '[]',
|
||||
required_controls JSONB DEFAULT '[]',
|
||||
recommended_architecture JSONB DEFAULT '[]',
|
||||
forbidden_patterns JSONB DEFAULT '[]',
|
||||
example_matches JSONB DEFAULT '[]',
|
||||
|
||||
-- Flags
|
||||
dsfa_recommended BOOLEAN DEFAULT FALSE,
|
||||
art22_risk BOOLEAN DEFAULT FALSE,
|
||||
training_allowed VARCHAR(50),
|
||||
|
||||
-- Explanation
|
||||
explanation_text TEXT,
|
||||
explanation_generated_at TIMESTAMPTZ,
|
||||
explanation_model VARCHAR(100),
|
||||
|
||||
-- Audit
|
||||
created_at TIMESTAMPTZ DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ DEFAULT NOW(),
|
||||
created_by UUID NOT NULL
|
||||
);
|
||||
```
|
||||
|
||||
### 6.2 ucca_escalations
|
||||
|
||||
```sql
|
||||
CREATE TABLE ucca_escalations (
|
||||
id UUID PRIMARY KEY,
|
||||
tenant_id UUID NOT NULL,
|
||||
assessment_id UUID NOT NULL REFERENCES ucca_assessments(id),
|
||||
|
||||
-- Level & Status
|
||||
escalation_level VARCHAR(10) NOT NULL,
|
||||
escalation_reason TEXT,
|
||||
status VARCHAR(50) NOT NULL DEFAULT 'pending',
|
||||
|
||||
-- Assignment
|
||||
assigned_to UUID,
|
||||
assigned_role VARCHAR(50),
|
||||
assigned_at TIMESTAMPTZ,
|
||||
|
||||
-- Review
|
||||
reviewer_id UUID,
|
||||
reviewer_notes TEXT,
|
||||
reviewed_at TIMESTAMPTZ,
|
||||
|
||||
-- Decision
|
||||
decision VARCHAR(50),
|
||||
decision_notes TEXT,
|
||||
decision_at TIMESTAMPTZ,
|
||||
conditions JSONB DEFAULT '[]',
|
||||
|
||||
-- SLA
|
||||
due_date TIMESTAMPTZ,
|
||||
notification_sent BOOLEAN DEFAULT FALSE,
|
||||
notification_sent_at TIMESTAMPTZ,
|
||||
|
||||
-- Audit
|
||||
created_at TIMESTAMPTZ DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ DEFAULT NOW()
|
||||
);
|
||||
```
|
||||
|
||||
### 6.3 ucca_dsb_pool
|
||||
|
||||
```sql
|
||||
CREATE TABLE ucca_dsb_pool (
|
||||
id UUID PRIMARY KEY,
|
||||
tenant_id UUID NOT NULL,
|
||||
user_id UUID NOT NULL,
|
||||
user_name VARCHAR(255) NOT NULL,
|
||||
user_email VARCHAR(255) NOT NULL,
|
||||
role VARCHAR(50) NOT NULL,
|
||||
is_active BOOLEAN DEFAULT TRUE,
|
||||
max_concurrent_reviews INT DEFAULT 10,
|
||||
current_reviews INT DEFAULT 0,
|
||||
created_at TIMESTAMPTZ DEFAULT NOW(),
|
||||
updated_at TIMESTAMPTZ DEFAULT NOW()
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. API-Endpunkte
|
||||
|
||||
### 7.1 Assessment
|
||||
|
||||
| Method | Endpoint | Beschreibung |
|
||||
|--------|----------|--------------|
|
||||
| POST | `/sdk/v1/ucca/assess` | Assessment erstellen |
|
||||
| GET | `/sdk/v1/ucca/assessments` | Assessments auflisten |
|
||||
| GET | `/sdk/v1/ucca/assessments/:id` | Assessment abrufen |
|
||||
| DELETE | `/sdk/v1/ucca/assessments/:id` | Assessment löschen |
|
||||
| POST | `/sdk/v1/ucca/assessments/:id/explain` | LLM-Erklärung generieren |
|
||||
| GET | `/sdk/v1/ucca/export/:id` | Assessment exportieren |
|
||||
|
||||
### 7.2 Kataloge
|
||||
|
||||
| Method | Endpoint | Beschreibung |
|
||||
|--------|----------|--------------|
|
||||
| GET | `/sdk/v1/ucca/patterns` | Architektur-Patterns |
|
||||
| GET | `/sdk/v1/ucca/examples` | Didaktische Beispiele |
|
||||
| GET | `/sdk/v1/ucca/rules` | Alle Regeln |
|
||||
| GET | `/sdk/v1/ucca/controls` | Required Controls |
|
||||
| GET | `/sdk/v1/ucca/problem-solutions` | Problem-Lösungen |
|
||||
|
||||
### 7.3 Eskalation
|
||||
|
||||
| Method | Endpoint | Beschreibung |
|
||||
|--------|----------|--------------|
|
||||
| GET | `/sdk/v1/ucca/escalations` | Eskalationen auflisten |
|
||||
| GET | `/sdk/v1/ucca/escalations/:id` | Eskalation abrufen |
|
||||
| POST | `/sdk/v1/ucca/escalations` | Manuelle Eskalation |
|
||||
| POST | `/sdk/v1/ucca/escalations/:id/assign` | Zuweisen |
|
||||
| POST | `/sdk/v1/ucca/escalations/:id/review` | Review starten |
|
||||
| POST | `/sdk/v1/ucca/escalations/:id/decide` | Entscheidung treffen |
|
||||
| GET | `/sdk/v1/ucca/escalations/stats` | Statistiken |
|
||||
|
||||
### 7.4 DSB Pool
|
||||
|
||||
| Method | Endpoint | Beschreibung |
|
||||
|--------|----------|--------------|
|
||||
| GET | `/sdk/v1/ucca/dsb-pool` | Pool-Mitglieder auflisten |
|
||||
| POST | `/sdk/v1/ucca/dsb-pool` | Mitglied hinzufügen |
|
||||
|
||||
---
|
||||
|
||||
## 8. Sicherheit
|
||||
|
||||
### 8.1 Authentifizierung
|
||||
|
||||
- JWT-basierte Authentifizierung
|
||||
- Header: `X-User-ID`, `X-Tenant-ID`
|
||||
- Multi-Tenant-Isolation
|
||||
|
||||
### 8.2 Autorisierung
|
||||
|
||||
- RBAC (Role-Based Access Control)
|
||||
- Permissions: `ucca:assess`, `ucca:review`, `ucca:admin`
|
||||
- Namespace-Level Isolation
|
||||
|
||||
### 8.3 Datenschutz
|
||||
|
||||
- Use-Case-Text optional (Opt-in)
|
||||
- SHA-256 Hash statt Klartext
|
||||
- Audit-Trail für alle Operationen
|
||||
- Legal RAG: `training_allowed: false`
|
||||
|
||||
---
|
||||
|
||||
## 9. Deployment
|
||||
|
||||
### 9.1 Container
|
||||
|
||||
```yaml
|
||||
ai-compliance-sdk:
|
||||
build: ./ai-compliance-sdk
|
||||
ports:
|
||||
- "8090:8090"
|
||||
environment:
|
||||
- DATABASE_URL=postgres://...
|
||||
- OLLAMA_URL=http://ollama:11434
|
||||
- QDRANT_URL=http://qdrant:6333
|
||||
depends_on:
|
||||
- postgres
|
||||
- qdrant
|
||||
```
|
||||
|
||||
### 9.2 Abhängigkeiten
|
||||
|
||||
- PostgreSQL 15+
|
||||
- Qdrant 1.12+
|
||||
- Embedding Service (BGE-M3)
|
||||
- Ollama (optional, für LLM)
|
||||
|
||||
---
|
||||
|
||||
## 10. Monitoring
|
||||
|
||||
### 10.1 Health Check
|
||||
|
||||
```
|
||||
GET /sdk/v1/health
|
||||
→ {"status": "ok"}
|
||||
```
|
||||
|
||||
### 10.2 Metriken
|
||||
|
||||
- Assessment-Durchsatz
|
||||
- Escalation-SLA-Compliance
|
||||
- LLM-Latenz
|
||||
- RAG-Trefferqualität
|
||||
|
||||
---
|
||||
|
||||
## 11. Wizard & Legal Assistant
|
||||
|
||||
### 11.1 Wizard-Architektur
|
||||
|
||||
Der UCCA-Wizard führt Benutzer durch 9 Schritte zur Erfassung aller relevanten Compliance-Fakten.
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ UCCA Wizard v1.1 │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Step 1: Grundlegende Informationen │
|
||||
│ Step 2: Datenarten (Personal Data, Art. 9, etc.) │
|
||||
│ Step 3: Verarbeitungszweck (Profiling, Scoring) │
|
||||
│ Step 4: Hosting & Provider │
|
||||
│ Step 5: Internationaler Datentransfer (SCC, TIA) │
|
||||
│ Step 6: KI-Modell und Training │
|
||||
│ Step 7: Verträge & Compliance (AVV, DSFA) │
|
||||
│ Step 8: Automatisierung & Human Oversight │
|
||||
│ Step 9: Standards & Normen (für Maschinenbauer) ← NEU │
|
||||
│ │
|
||||
│ Features: │
|
||||
│ ├── Adaptive Subflows (visible_if Conditions) │
|
||||
│ ├── Simple/Expert Mode Toggle │
|
||||
│ ├── Legal Assistant Chat pro Step │
|
||||
│ └── simple_explanation für Nicht-Juristen │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 11.2 Legal Assistant (Wizard Chat)
|
||||
|
||||
Integrierter Rechtsassistent für Echtzeit-Hilfe bei Wizard-Fragen.
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Legal Assistant Flow │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ User Question ─────────────────────────────────────────────────>│
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────────┐ │
|
||||
│ │ Build RAG Query │ │
|
||||
│ │ + Step Context │ │
|
||||
│ └────────┬─────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────────┐ Search ┌──────────────────┐ │
|
||||
│ │ Legal RAG │ ────────────>│ Qdrant │ │
|
||||
│ │ Client │ │ bp_legal_corpus │ │
|
||||
│ │ │<────────────│ + SCC Corpus │ │
|
||||
│ └────────┬─────────┘ Top-5 └──────────────────┘ │
|
||||
│ │ │
|
||||
│ │ Question + Legal Context │
|
||||
│ ▼ │
|
||||
│ ┌──────────────────┐ │
|
||||
│ │ Internal 32B LLM │ │
|
||||
│ │ (Ollama) │ │
|
||||
│ │ temp=0.3 │ │
|
||||
│ └────────┬─────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ Answer + Sources + Related Fields │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**API-Endpunkte:**
|
||||
|
||||
| Method | Endpoint | Beschreibung |
|
||||
|--------|----------|--------------|
|
||||
| GET | `/sdk/v1/ucca/wizard/schema` | Wizard-Schema abrufen |
|
||||
| POST | `/sdk/v1/ucca/wizard/ask` | Frage an Legal Assistant |
|
||||
|
||||
---
|
||||
|
||||
## 12. License Policy Engine (Standards Compliance)
|
||||
|
||||
### 12.1 Übersicht
|
||||
|
||||
Die License Policy Engine verwaltet die Lizenz-/Urheberrechts-Compliance für Standards und Normen (DIN, ISO, VDI, etc.).
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ License Policy Engine │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ LicensedContentFacts ─────────────────────────────────────────>│
|
||||
│ │ │
|
||||
│ │ ├── present: bool │
|
||||
│ │ ├── publisher: DIN_MEDIA | VDI | ISO | ... │
|
||||
│ │ ├── license_type: SINGLE | NETWORK | ENTERPRISE | AI │
|
||||
│ │ ├── ai_use_permitted: YES | NO | UNKNOWN │
|
||||
│ │ ├── operation_mode: LINK | NOTES | FULLTEXT | TRAINING │
|
||||
│ │ └── proof_uploaded: bool │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐│
|
||||
│ │ Operation Mode Evaluation ││
|
||||
│ ├─────────────────────────────────────────────────────────────┤│
|
||||
│ │ ││
|
||||
│ │ LINK_ONLY ──────────── Always Allowed ───────────> OK ││
|
||||
│ │ NOTES_ONLY ─────────── Usually Allowed ──────────> OK ││
|
||||
│ │ FULLTEXT_RAG ────┬──── ai_use=YES + proof ───────> OK ││
|
||||
│ │ └──── else ─────────────────────> BLOCK ││
|
||||
│ │ TRAINING ────────┬──── AI_LICENSE + proof ───────> OK ││
|
||||
│ │ └──── else ─────────────────────> BLOCK ││
|
||||
│ │ ││
|
||||
│ └─────────────────────────────────────────────────────────────┘│
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ LicensePolicyResult │
|
||||
│ ├── allowed: bool │
|
||||
│ ├── effective_mode: string (may be downgraded) │
|
||||
│ ├── gaps: []LicenseGap │
|
||||
│ ├── required_controls: []LicenseControl │
|
||||
│ ├── stop_line: *StopLine (if hard blocked) │
|
||||
│ └── output_restrictions: *OutputRestrictions │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 12.2 Betriebs-Modi (Operation Modes)
|
||||
|
||||
| Modus | Beschreibung | Lizenz-Anforderung | Ingest | Output |
|
||||
|-------|--------------|-------------------|--------|--------|
|
||||
| **LINK_ONLY** | Nur Verweise & Checklisten | Keine | Metadata only | Keine Zitate |
|
||||
| **NOTES_ONLY** | Kundeneigene Zusammenfassungen | Standard | Notes only | Paraphrasen |
|
||||
| **EXCERPT_ONLY** | Kurze Zitate (Zitatrecht) | Standard + Zitatrecht | Notes | Max 150 Zeichen |
|
||||
| **FULLTEXT_RAG** | Volltext indexiert | AI-Lizenz + Proof | Fulltext | Max 500 Zeichen |
|
||||
| **TRAINING** | Modell-Training | AI-Training-Lizenz | Fulltext | N/A |
|
||||
|
||||
### 12.3 Publisher-spezifische Regeln
|
||||
|
||||
**DIN Media (ehem. Beuth):**
|
||||
- AI-Nutzung aktuell verboten (ohne explizite Genehmigung)
|
||||
- AI-Lizenzmodell geplant ab Q4/2025
|
||||
- Crawler/Scraper verboten (AGB)
|
||||
- TDM-Vorbehalt nach §44b UrhG
|
||||
|
||||
### 12.4 Stop-Lines (Hard Deny)
|
||||
|
||||
```
|
||||
STOP_DIN_FULLTEXT_AI_NOT_ALLOWED
|
||||
WENN: publisher=DIN_MEDIA AND operation_mode in [FULLTEXT_RAG, TRAINING]
|
||||
AND ai_use_permitted in [NO, UNKNOWN]
|
||||
DANN: BLOCKIERT
|
||||
FALLBACK: LINK_ONLY
|
||||
|
||||
STOP_TRAINING_WITHOUT_PROOF
|
||||
WENN: operation_mode=TRAINING AND proof_uploaded=false
|
||||
DANN: BLOCKIERT
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 13. SCC & Transfer Impact Assessment
|
||||
|
||||
### 13.1 Drittlandtransfer-Bewertung
|
||||
|
||||
Das System unterstützt die vollständige Bewertung internationaler Datentransfers.
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ SCC/Transfer Assessment Flow │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ hosting.region ─────────────────────────────────────────────── │
|
||||
│ │ │
|
||||
│ ├── EU/EWR ────────────────────────────────> OK (no SCC) │
|
||||
│ │ │
|
||||
│ ├── Adequacy Country (UK, CH, JP) ─────────> OK (no SCC) │
|
||||
│ │ │
|
||||
│ └── Third Country (US, etc.) ──────────────────────────── │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐│
|
||||
│ │ USA: DPF-Zertifizierung prüfen ││
|
||||
│ │ ├── Zertifiziert ───> OK (SCC empfohlen als Backup) ││
|
||||
│ │ └── Nicht zertifiziert ───> SCC + TIA erforderlich ││
|
||||
│ └─────────────────────────────────────────────────────────┘│
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────┐│
|
||||
│ │ Transfer Impact Assessment (TIA) ││
|
||||
│ │ ├── Adequate ─────────────> Transfer OK ││
|
||||
│ │ ├── Adequate + Measures ──> + Technical Supplementary ││
|
||||
│ │ ├── Inadequate ───────────> Fix required ││
|
||||
│ │ └── Not Feasible ─────────> Transfer NOT allowed ││
|
||||
│ └─────────────────────────────────────────────────────────┘│
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 13.2 SCC-Versionen
|
||||
|
||||
- Neue SCC (EU 2021/914) - **erforderlich** seit 27.12.2022
|
||||
- Alte SCC (vor 2021) - **nicht mehr gültig**
|
||||
|
||||
---
|
||||
|
||||
## 14. Controls Catalog
|
||||
|
||||
### 14.1 Übersicht
|
||||
|
||||
Der Controls Catalog enthält ~30 Maßnahmenbausteine mit detaillierten Handlungsanweisungen.
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Controls Catalog v1.0 │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Kategorien: │
|
||||
│ ├── DSGVO (Rechtsgrundlagen, Betroffenenrechte, Dokumentation) │
|
||||
│ ├── AI_Act (Transparenz, HITL, Risikoeinstufung) │
|
||||
│ ├── Technical (Verschlüsselung, Anonymisierung, PII-Gateway) │
|
||||
│ └── Contractual (AVV, SCC, TIA) │
|
||||
│ │
|
||||
│ Struktur pro Control: │
|
||||
│ ├── id: CTRL-xxx │
|
||||
│ ├── title: Kurztitel │
|
||||
│ ├── when_applicable: Wann erforderlich? │
|
||||
│ ├── what_to_do: Konkrete Handlungsschritte │
|
||||
│ ├── evidence_needed: Erforderliche Nachweise │
|
||||
│ ├── effort: low | medium | high │
|
||||
│ └── gdpr_ref: Rechtsgrundlage │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 14.2 Beispiel-Controls
|
||||
|
||||
| ID | Titel | Kategorie |
|
||||
|----|-------|-----------|
|
||||
| CTRL-CONSENT-EXPLICIT | Ausdrückliche Einwilligung | DSGVO |
|
||||
| CTRL-AI-TRANSPARENCY | KI-Transparenz-Hinweis | AI_Act |
|
||||
| CTRL-DSFA | Datenschutz-Folgenabschätzung | DSGVO |
|
||||
| CTRL-SCC | Standardvertragsklauseln | Contractual |
|
||||
| CTRL-TIA | Transfer Impact Assessment | Contractual |
|
||||
| CTRL-LICENSE-PROOF | Lizenz-/Rechte-Nachweis | License |
|
||||
| CTRL-LINK-ONLY-MODE | Evidence Navigator | License |
|
||||
| CTRL-PII-GATEWAY | PII-Redaction Gateway | Technical |
|
||||
|
||||
---
|
||||
|
||||
## 15. Policy-Dateien
|
||||
|
||||
### 15.1 Dateistruktur
|
||||
|
||||
```
|
||||
policies/
|
||||
├── ucca_policy_v1.yaml # Haupt-Policy (Regeln, Controls)
|
||||
├── controls_catalog.yaml # Detaillierter Maßnahmenkatalog
|
||||
├── gap_mapping.yaml # Facts → Gaps → Controls
|
||||
├── wizard_schema_v1.yaml # Wizard-Fragen (9 Steps)
|
||||
├── scc_legal_corpus.yaml # SCC/Transfer Rechtstexte
|
||||
└── licensed_content_policy.yaml # Normen-Lizenz-Compliance (NEU)
|
||||
```
|
||||
|
||||
### 15.2 Versions-Management
|
||||
|
||||
- Jedes Assessment speichert die `policy_version`
|
||||
- Regeländerungen erzeugen neue Version
|
||||
- Audit-Trail zeigt welche Policy-Version verwendet wurde
|
||||
|
||||
---
|
||||
|
||||
## 16. Generic Obligations Framework
|
||||
|
||||
### 16.1 Übersicht
|
||||
|
||||
Das Generic Obligations Framework ermöglicht die automatische Ableitung regulatorischer Pflichten aus mehreren Verordnungen basierend auf Unternehmensfakten.
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Generic Obligations Framework │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ UnifiedFacts ───────────────────────────────────────────────── │
|
||||
│ │ │
|
||||
│ │ ├── organization: EmployeeCount, Revenue, Country │
|
||||
│ │ ├── sector: PrimarySector, IsKRITIS, SpecialServices │
|
||||
│ │ ├── data_protection: ProcessesPersonalData │
|
||||
│ │ └── ai_usage: UsesAI, HighRiskCategories, IsGPAI │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐│
|
||||
│ │ Obligations Registry ││
|
||||
│ │ (Module Registration & Evaluation) ││
|
||||
│ └──────────────────────────┬──────────────────────────────────┘│
|
||||
│ │ │
|
||||
│ ┌───────────────────┼───────────────────┐ │
|
||||
│ │ │ │ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
|
||||
│ │ NIS2 │ │ DSGVO │ │ AI Act │ │
|
||||
│ │ Module │ │ Module │ │ Module │ │
|
||||
│ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ │
|
||||
│ │ │ │ │
|
||||
│ └───────────────────┴───────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐│
|
||||
│ │ ManagementObligationsOverview ││
|
||||
│ │ ├── ApplicableRegulations[] ││
|
||||
│ │ ├── Obligations[] (sortiert nach Priorität) ││
|
||||
│ │ ├── RequiredControls[] ││
|
||||
│ │ ├── IncidentDeadlines[] ││
|
||||
│ │ ├── SanctionsSummary ││
|
||||
│ │ └── ExecutiveSummary ││
|
||||
│ └─────────────────────────────────────────────────────────────┘│
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 16.2 Regulation Modules
|
||||
|
||||
Jede Regulierung wird als eigenständiges Modul implementiert:
|
||||
|
||||
**Implementierte Module:**
|
||||
|
||||
| Modul | ID | Datei | Pflichten | Kontrollen |
|
||||
|-------|-----|-------|-----------|------------|
|
||||
| NIS2 | `nis2` | `nis2_module.go` | ~15 | ~8 |
|
||||
| DSGVO | `dsgvo` | `dsgvo_module.go` | ~12 | ~6 |
|
||||
| AI Act | `ai_act` | `ai_act_module.go` | ~15 | ~6 |
|
||||
|
||||
---
|
||||
|
||||
## 17. Obligations API-Endpunkte
|
||||
|
||||
### 17.1 Assessment
|
||||
|
||||
| Method | Endpoint | Beschreibung |
|
||||
|--------|----------|--------------|
|
||||
| POST | `/sdk/v1/ucca/obligations/assess` | Pflichten-Assessment erstellen |
|
||||
| GET | `/sdk/v1/ucca/obligations/:id` | Assessment abrufen |
|
||||
| GET | `/sdk/v1/ucca/obligations` | Assessments auflisten |
|
||||
|
||||
### 17.2 Export
|
||||
|
||||
| Method | Endpoint | Beschreibung |
|
||||
|--------|----------|--------------|
|
||||
| POST | `/sdk/v1/ucca/obligations/export/memo` | Memo exportieren (gespeichert) |
|
||||
| POST | `/sdk/v1/ucca/obligations/export/direct` | Direkt-Export ohne Speicherung |
|
||||
|
||||
### 17.3 Regulations
|
||||
|
||||
| Method | Endpoint | Beschreibung |
|
||||
|--------|----------|--------------|
|
||||
| GET | `/sdk/v1/ucca/regulations` | Liste aller Regulierungsmodule |
|
||||
| GET | `/sdk/v1/ucca/regulations/:id/decision-tree` | Decision Tree für Regulierung |
|
||||
|
||||
---
|
||||
|
||||
## 18. Dateien des Obligations Framework
|
||||
|
||||
### 18.1 Backend (Go)
|
||||
|
||||
```
|
||||
internal/ucca/
|
||||
├── obligations_framework.go # Interfaces, Typen, Konstanten
|
||||
├── obligations_registry.go # Modul-Registry, EvaluateAll()
|
||||
├── nis2_module.go # NIS2 Decision Tree + Pflichten
|
||||
├── nis2_module_test.go # NIS2 Tests
|
||||
├── dsgvo_module.go # DSGVO Pflichten
|
||||
├── dsgvo_module_test.go # DSGVO Tests
|
||||
├── ai_act_module.go # AI Act Risk Classification
|
||||
├── ai_act_module_test.go # AI Act Tests
|
||||
├── pdf_export.go # PDF/Markdown Export
|
||||
└── pdf_export_test.go # Export Tests
|
||||
```
|
||||
|
||||
### 18.2 Policy-Dateien (YAML)
|
||||
|
||||
```
|
||||
policies/obligations/
|
||||
├── nis2_obligations.yaml # ~15 NIS2-Pflichten
|
||||
├── dsgvo_obligations.yaml # ~12 DSGVO-Pflichten
|
||||
└── ai_act_obligations.yaml # ~15 AI Act-Pflichten
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*Dokumentation erstellt: 2026-01-29*
|
||||
*Version: 2.1.0*
|
||||
387
docs-src/services/ai-compliance-sdk/AUDITOR_DOCUMENTATION.md
Normal file
387
docs-src/services/ai-compliance-sdk/AUDITOR_DOCUMENTATION.md
Normal file
@@ -0,0 +1,387 @@
|
||||
# UCCA - Dokumentation für externe Auditoren
|
||||
|
||||
## Systemdokumentation nach Art. 30 DSGVO
|
||||
|
||||
**Verantwortlicher:** [Name des Unternehmens]
|
||||
**Datenschutzbeauftragter:** [Kontakt]
|
||||
**Dokumentationsstand:** 2026-01-29
|
||||
**Version:** 1.0.0
|
||||
|
||||
---
|
||||
|
||||
## 1. Zweck und Funktionsweise des Systems
|
||||
|
||||
### 1.1 Systembezeichnung
|
||||
|
||||
**UCCA - Use-Case Compliance & Feasibility Advisor**
|
||||
|
||||
### 1.2 Zweckbeschreibung
|
||||
|
||||
Das UCCA-System ist ein **Compliance-Prüfwerkzeug**, das Organisationen bei der Bewertung geplanter KI-Anwendungsfälle hinsichtlich ihrer datenschutzrechtlichen Zulässigkeit unterstützt.
|
||||
|
||||
**Kernfunktionen:**
|
||||
- Automatisierte Vorprüfung von KI-Anwendungsfällen gegen EU-Regulierungen
|
||||
- Identifikation erforderlicher technischer und organisatorischer Maßnahmen
|
||||
- Eskalation kritischer Fälle zur menschlichen Prüfung
|
||||
- Dokumentation und Nachvollziehbarkeit aller Prüfentscheidungen
|
||||
|
||||
### 1.3 Rechtsgrundlage
|
||||
|
||||
Die Verarbeitung erfolgt auf Basis von:
|
||||
- **Art. 6 Abs. 1 lit. c DSGVO** - Erfüllung rechtlicher Verpflichtungen
|
||||
- **Art. 6 Abs. 1 lit. f DSGVO** - Berechtigte Interessen (Compliance-Management)
|
||||
|
||||
---
|
||||
|
||||
## 2. Verarbeitete Datenkategorien
|
||||
|
||||
### 2.1 Eingabedaten (Use-Case-Beschreibungen)
|
||||
|
||||
| Datenkategorie | Beschreibung | Speicherung |
|
||||
|----------------|--------------|-------------|
|
||||
| Use-Case-Text | Freitextbeschreibung des geplanten Anwendungsfalls | Optional (Opt-in), ansonsten nur Hash |
|
||||
| Domain | Branchenkategorie (z.B. "education", "healthcare") | Ja |
|
||||
| Datentyp-Flags | Angaben zu verarbeiteten Datenarten | Ja |
|
||||
| Automatisierungsgrad | assistiv/teil-/vollautomatisch | Ja |
|
||||
| Hosting-Informationen | Region, Provider | Ja |
|
||||
|
||||
**Wichtig:** Der System speichert standardmäßig **keine Freitexte**, sondern nur:
|
||||
- SHA-256 Hash des Textes (zur Deduplizierung)
|
||||
- Strukturierte Metadaten (Checkboxen, Dropdowns)
|
||||
|
||||
### 2.2 Bewertungsergebnisse
|
||||
|
||||
| Datenkategorie | Beschreibung | Aufbewahrung |
|
||||
|----------------|--------------|--------------|
|
||||
| Risk Score | Numerischer Wert 0-100 | Dauerhaft |
|
||||
| Triggered Rules | Ausgelöste Compliance-Regeln | Dauerhaft |
|
||||
| Required Controls | Empfohlene Maßnahmen | Dauerhaft |
|
||||
| Explanation | KI-generierte Erklärung | Dauerhaft |
|
||||
|
||||
### 2.3 Audit-Trail-Daten
|
||||
|
||||
| Datenkategorie | Beschreibung | Aufbewahrung |
|
||||
|----------------|--------------|--------------|
|
||||
| Benutzer-ID | UUID des ausführenden Benutzers | 10 Jahre |
|
||||
| Timestamp | Zeitpunkt der Aktion | 10 Jahre |
|
||||
| Aktionstyp | created/reviewed/decided | 10 Jahre |
|
||||
| Entscheidungsnotizen | Begründungen bei Eskalationen | 10 Jahre |
|
||||
|
||||
---
|
||||
|
||||
## 3. Entscheidungslogik und Automatisierung
|
||||
|
||||
### 3.1 Regelbasierte Bewertung (Deterministische Logik)
|
||||
|
||||
Das System verwendet **ausschließlich deterministische Regeln** für Compliance-Entscheidungen. Diese Regeln sind:
|
||||
|
||||
1. **Transparent** - Alle Regeln sind im Quellcode einsehbar
|
||||
2. **Nachvollziehbar** - Jede ausgelöste Regel wird dokumentiert
|
||||
3. **Überprüfbar** - Regellogik basiert auf konkreten DSGVO-Artikeln
|
||||
|
||||
**Beispiel-Regel R-F001:**
|
||||
```
|
||||
WENN:
|
||||
- Domain = "education" UND
|
||||
- Automation = "fully_automated" UND
|
||||
- Output enthält "rankings_or_scores"
|
||||
DANN:
|
||||
- Severity = BLOCK
|
||||
- DSGVO-Referenz = Art. 22 Abs. 1
|
||||
- Begründung = "Vollautomatisierte Bewertung von Schülern ohne menschliche Überprüfung"
|
||||
```
|
||||
|
||||
### 3.2 Keine autonomen KI-Entscheidungen
|
||||
|
||||
**Das System trifft KEINE autonomen KI-Entscheidungen bezüglich:**
|
||||
- Zulässigkeit eines Anwendungsfalls (immer regelbasiert)
|
||||
- Freigabe oder Ablehnung (immer durch Mensch)
|
||||
- Rechtliche Bewertungen (immer durch DSB/Legal)
|
||||
|
||||
**KI wird ausschließlich verwendet für:**
|
||||
- Erklärung bereits getroffener Regelentscheidungen
|
||||
- Zusammenfassung von Rechtstexten
|
||||
- Sprachliche Formulierung von Hinweisen
|
||||
|
||||
### 3.3 Human-in-the-Loop
|
||||
|
||||
Bei allen kritischen Entscheidungen ist ein **menschlicher Prüfer** eingebunden:
|
||||
|
||||
| Eskalationsstufe | Auslöser | Prüfer | SLA |
|
||||
|------------------|----------|--------|-----|
|
||||
| E0 | Nur informative Regeln | Automatisch | - |
|
||||
| E1 | Warnungen, geringes Risiko | Team-Lead | 24h |
|
||||
| E2 | Art. 9-Daten, DSFA empfohlen | DSB | 8h |
|
||||
| E3 | BLOCK-Regeln, hohes Risiko | DSB + Legal | 4h |
|
||||
|
||||
**BLOCK-Entscheidungen können NICHT durch KI überschrieben werden.**
|
||||
|
||||
---
|
||||
|
||||
## 4. Technische und organisatorische Maßnahmen (Art. 32 DSGVO)
|
||||
|
||||
### 4.1 Vertraulichkeit
|
||||
|
||||
| Maßnahme | Umsetzung |
|
||||
|----------|-----------|
|
||||
| Zugriffskontrolle | RBAC mit Tenant-Isolation |
|
||||
| Verschlüsselung in Transit | TLS 1.3 |
|
||||
| Verschlüsselung at Rest | AES-256 (PostgreSQL, Qdrant) |
|
||||
| Authentifizierung | JWT-basiert, Token-Expiry |
|
||||
|
||||
### 4.2 Integrität
|
||||
|
||||
| Maßnahme | Umsetzung |
|
||||
|----------|-----------|
|
||||
| Audit-Trail | Unveränderlicher Verlauf aller Aktionen |
|
||||
| Versionierung | Policy-Version in jedem Assessment |
|
||||
| Input-Validierung | Schema-Validierung aller API-Eingaben |
|
||||
|
||||
### 4.3 Verfügbarkeit
|
||||
|
||||
| Maßnahme | Umsetzung |
|
||||
|----------|-----------|
|
||||
| Backup | Tägliche PostgreSQL-Backups |
|
||||
| Redundanz | Container-Orchestrierung mit Auto-Restart |
|
||||
| Monitoring | Health-Checks, SLA-Überwachung |
|
||||
|
||||
### 4.4 Belastbarkeit
|
||||
|
||||
| Maßnahme | Umsetzung |
|
||||
|----------|-----------|
|
||||
| Rate Limiting | API-Anfragenbegrenzung |
|
||||
| Graceful Degradation | LLM-Fallback bei Ausfall |
|
||||
| Ressourcenlimits | Container-Memory-Limits |
|
||||
|
||||
---
|
||||
|
||||
## 5. Datenschutz-Folgenabschätzung (Art. 35 DSGVO)
|
||||
|
||||
### 5.1 Risikobewertung
|
||||
|
||||
| Risiko | Bewertung | Mitigierung |
|
||||
|--------|-----------|-------------|
|
||||
| Fehleinschätzung durch KI | Mittel | Deterministische Regeln, Human Review |
|
||||
| Datenverlust | Niedrig | Backup, Verschlüsselung |
|
||||
| Unbefugter Zugriff | Niedrig | RBAC, Audit-Trail |
|
||||
| Bias in Regellogik | Niedrig | Transparente Regeln, Review-Prozess |
|
||||
|
||||
### 5.2 DSFA-Trigger im System
|
||||
|
||||
Das System erkennt automatisch, wann eine DSFA erforderlich ist:
|
||||
- Verarbeitung besonderer Kategorien (Art. 9 DSGVO)
|
||||
- Systematische Bewertung natürlicher Personen
|
||||
- Neue Technologien mit hohem Risiko
|
||||
|
||||
---
|
||||
|
||||
## 6. Betroffenenrechte (Art. 15-22 DSGVO)
|
||||
|
||||
### 6.1 Auskunftsrecht (Art. 15)
|
||||
|
||||
Betroffene können Auskunft erhalten über:
|
||||
- Gespeicherte Assessments mit ihren Daten
|
||||
- Audit-Trail ihrer Interaktionen
|
||||
- Regelbasierte Entscheidungsbegründungen
|
||||
|
||||
### 6.2 Recht auf Berichtigung (Art. 16)
|
||||
|
||||
Betroffene können die Korrektur fehlerhafter Eingabedaten verlangen.
|
||||
|
||||
### 6.3 Recht auf Löschung (Art. 17)
|
||||
|
||||
Assessments können gelöscht werden, sofern:
|
||||
- Keine gesetzlichen Aufbewahrungspflichten bestehen
|
||||
- Keine laufenden Eskalationsverfahren existieren
|
||||
|
||||
### 6.4 Recht auf Einschränkung (Art. 18)
|
||||
|
||||
Die Verarbeitung kann eingeschränkt werden durch:
|
||||
- Archivierung statt Löschung
|
||||
- Sperrung des Datensatzes
|
||||
|
||||
### 6.5 Automatisierte Entscheidungen (Art. 22)
|
||||
|
||||
**Das System trifft keine automatisierten Einzelentscheidungen** im Sinne von Art. 22 DSGVO, da:
|
||||
|
||||
1. Regelauswertung ist **keine rechtlich bindende Entscheidung**
|
||||
2. Alle kritischen Fälle werden **menschlich geprüft** (E1-E3)
|
||||
3. BLOCK-Entscheidungen erfordern **immer menschliche Freigabe**
|
||||
4. Betroffene haben **Anfechtungsmöglichkeit** über Eskalation
|
||||
|
||||
---
|
||||
|
||||
## 7. Auftragsverarbeitung
|
||||
|
||||
### 7.1 Unterauftragnehmer
|
||||
|
||||
| Dienst | Anbieter | Standort | Zweck |
|
||||
|--------|----------|----------|-------|
|
||||
| Embedding-Service | Lokal (Self-Hosted) | EU | Vektorisierung |
|
||||
| Vector-DB (Qdrant) | Lokal (Self-Hosted) | EU | Ähnlichkeitssuche |
|
||||
| LLM (Ollama) | Lokal (Self-Hosted) | EU | Erklärungsgenerierung |
|
||||
|
||||
**Hinweis:** Das System kann vollständig on-premise betrieben werden ohne externe Dienste.
|
||||
|
||||
### 7.2 Internationale Transfers
|
||||
|
||||
Bei Nutzung von Cloud-LLM-Anbietern:
|
||||
- Anthropic Claude: US (DPF-zertifiziert)
|
||||
- OpenAI: US (DPF-zertifiziert)
|
||||
|
||||
**Empfehlung:** Nutzung des lokalen Ollama-Providers für sensible Daten.
|
||||
|
||||
---
|
||||
|
||||
## 8. Audit-Trail und Nachvollziehbarkeit
|
||||
|
||||
### 8.1 Protokollierte Ereignisse
|
||||
|
||||
| Ereignis | Protokollierte Daten |
|
||||
|----------|---------------------|
|
||||
| Assessment erstellt | Benutzer, Timestamp, Intake-Hash, Ergebnis |
|
||||
| Eskalation erstellt | Level, Grund, SLA |
|
||||
| Zuweisung | Benutzer, Rolle |
|
||||
| Review gestartet | Benutzer, Timestamp |
|
||||
| Entscheidung | Benutzer, Entscheidung, Begründung |
|
||||
|
||||
### 8.2 Aufbewahrungsfristen
|
||||
|
||||
| Datenart | Aufbewahrung | Rechtsgrundlage |
|
||||
|----------|--------------|-----------------|
|
||||
| Assessments | 10 Jahre | § 147 AO |
|
||||
| Audit-Trail | 10 Jahre | § 147 AO |
|
||||
| Eskalationen | 10 Jahre | § 147 AO |
|
||||
| Löschprotokolle | 3 Jahre | Art. 17 DSGVO |
|
||||
|
||||
---
|
||||
|
||||
## 9. Lizenzierte Inhalte & Normen-Compliance (§44b UrhG)
|
||||
|
||||
### 9.1 Zweck
|
||||
|
||||
Das System enthält einen spezialisierten **License Policy Engine** zur Compliance-Prüfung bei der Verarbeitung urheberrechtlich geschützter Inhalte, insbesondere:
|
||||
|
||||
- **DIN-Normen** (DIN Media / Beuth Verlag)
|
||||
- **VDI-Richtlinien**
|
||||
- **ISO/IEC-Standards**
|
||||
- **VDE-Normen**
|
||||
|
||||
### 9.2 Rechtlicher Hintergrund
|
||||
|
||||
**§44b UrhG - Text und Data Mining:**
|
||||
> "Die Vervielfältigung von rechtmäßig zugänglichen Werken für das Text und Data Mining ist zulässig."
|
||||
|
||||
**ABER:** Rechteinhaber können TDM gem. §44b Abs. 3 UrhG vorbehalten:
|
||||
- **DIN Media:** Expliziter Vorbehalt in AGB – keine KI/TDM-Nutzung ohne Sonderlizenz
|
||||
- **Geplante KI-Lizenzmodelle:** Ab Q4/2025 (DIN Media)
|
||||
|
||||
### 9.3 Operationsmodi im System
|
||||
|
||||
| Modus | Beschreibung | Lizenzanforderung |
|
||||
|-------|--------------|-------------------|
|
||||
| `LINK_ONLY` | Nur Verlinkung zum Original | Keine |
|
||||
| `NOTES_ONLY` | Eigene Notizen/Zusammenfassungen | Keine (§51 UrhG) |
|
||||
| `EXCERPT_ONLY` | Kurze Zitate (<100 Wörter) | Standard-Lizenz |
|
||||
| `FULLTEXT_RAG` | Volltextsuche mit Embedding | Explizite KI-Lizenz |
|
||||
| `TRAINING` | Modell-Training | Enterprise-Lizenz + Vertrag |
|
||||
|
||||
### 9.4 Stop-Lines (Automatische Sperren)
|
||||
|
||||
Das System **blockiert automatisch** folgende Kombinationen:
|
||||
|
||||
| Stop-Line ID | Bedingung | Aktion |
|
||||
|--------------|-----------|--------|
|
||||
| `STOP_DIN_FULLTEXT_AI_NOT_ALLOWED` | DIN Media + FULLTEXT_RAG + keine KI-Lizenz | Ablehnung |
|
||||
| `STOP_LICENSE_UNKNOWN_FULLTEXT` | Lizenz unbekannt + FULLTEXT_RAG | Warnung + Eskalation |
|
||||
| `STOP_TRAINING_WITHOUT_ENTERPRISE` | Beliebig + TRAINING + keine Enterprise-Lizenz | Ablehnung |
|
||||
|
||||
### 9.5 License Policy Engine - Entscheidungslogik
|
||||
|
||||
```
|
||||
INPUT:
|
||||
├── licensed_content.present = true
|
||||
├── licensed_content.publisher = "DIN_MEDIA"
|
||||
├── licensed_content.license_type = "SINGLE_WORKSTATION"
|
||||
├── licensed_content.ai_use_permitted = "NO"
|
||||
└── licensed_content.operation_mode = "FULLTEXT_RAG"
|
||||
|
||||
REGEL-EVALUATION:
|
||||
├── Prüfe Publisher-spezifische Regeln
|
||||
├── Prüfe Lizenztyp vs. gewünschter Modus
|
||||
├── Prüfe AI-Use-Flag
|
||||
└── Bestimme maximal zulässigen Modus
|
||||
|
||||
OUTPUT:
|
||||
├── allowed: false
|
||||
├── max_allowed_mode: "NOTES_ONLY"
|
||||
├── required_controls: ["CTRL-LICENSE-PROOF", "CTRL-NO-CRAWLING-DIN"]
|
||||
├── gaps: ["GAP_DIN_MEDIA_WITHOUT_AI_LICENSE"]
|
||||
├── stop_lines: ["STOP_DIN_FULLTEXT_AI_NOT_ALLOWED"]
|
||||
└── explanation: "DIN Media verbietet KI-Nutzung ohne explizite Lizenz..."
|
||||
```
|
||||
|
||||
### 9.6 Erforderliche Controls bei lizenzierten Inhalten
|
||||
|
||||
| Control ID | Beschreibung | Evidence |
|
||||
|------------|--------------|----------|
|
||||
| `CTRL-LICENSE-PROOF` | Lizenznachweis dokumentieren | Lizenzvertrag, Rechnung |
|
||||
| `CTRL-LICENSE-GATED-INGEST` | Technische Sperre vor Ingest | Konfiguration, Logs |
|
||||
| `CTRL-NO-CRAWLING-DIN` | Kein automatisches Crawling | System-Konfiguration |
|
||||
| `CTRL-OUTPUT-GUARD` | Ausgabe-Beschränkung (Zitatlimit) | API-Logs |
|
||||
|
||||
### 9.7 Audit-relevante Protokollierung
|
||||
|
||||
Bei jeder Verarbeitung lizenzierter Inhalte wird dokumentiert:
|
||||
|
||||
| Feld | Beschreibung | Aufbewahrung |
|
||||
|------|--------------|--------------|
|
||||
| `license_check_timestamp` | Zeitpunkt der Prüfung | 10 Jahre |
|
||||
| `license_decision` | Ergebnis (allowed/denied) | 10 Jahre |
|
||||
| `license_proof_hash` | Hash des Lizenznachweises | 10 Jahre |
|
||||
| `operation_mode_requested` | Angefragter Modus | 10 Jahre |
|
||||
| `operation_mode_granted` | Erlaubter Modus | 10 Jahre |
|
||||
| `publisher` | Rechteinhaber | 10 Jahre |
|
||||
|
||||
### 9.8 On-Premise-Deployment für sensible Normen
|
||||
|
||||
Für Unternehmen mit strengen Compliance-Anforderungen:
|
||||
|
||||
| Komponente | Deployment | Isolation |
|
||||
|------------|------------|-----------|
|
||||
| Normen-Datenbank | Lokaler Mac Studio | Air-gapped |
|
||||
| Embedding-Service | Lokal (bge-m3) | Keine Cloud |
|
||||
| Vector-DB (Qdrant) | Lokaler Container | Tenant-Isolation |
|
||||
| LLM (Ollama) | Lokal (Qwen2.5-Coder) | Keine API-Calls |
|
||||
|
||||
---
|
||||
|
||||
## 10. Kontakt und Verantwortlichkeiten
|
||||
|
||||
### 10.1 Verantwortlicher
|
||||
|
||||
[Name und Adresse des Unternehmens]
|
||||
|
||||
### 10.2 Datenschutzbeauftragter
|
||||
|
||||
Name: [Name]
|
||||
E-Mail: [E-Mail]
|
||||
Telefon: [Telefon]
|
||||
|
||||
### 10.3 Technischer Ansprechpartner
|
||||
|
||||
Name: [Name]
|
||||
E-Mail: [E-Mail]
|
||||
|
||||
---
|
||||
|
||||
## 11. Änderungshistorie
|
||||
|
||||
| Version | Datum | Änderung | Autor |
|
||||
|---------|-------|----------|-------|
|
||||
| 1.1.0 | 2026-01-29 | License Policy Engine & Standards-Compliance (§44b UrhG) | [Autor] |
|
||||
| 1.0.0 | 2026-01-29 | Erstversion | [Autor] |
|
||||
|
||||
---
|
||||
|
||||
*Diese Dokumentation erfüllt die Anforderungen nach Art. 30 DSGVO (Verzeichnis von Verarbeitungstätigkeiten) und dient als Grundlage für Audits nach Art. 32 DSGVO (Sicherheit der Verarbeitung).*
|
||||
746
docs-src/services/ai-compliance-sdk/DEVELOPER.md
Normal file
746
docs-src/services/ai-compliance-sdk/DEVELOPER.md
Normal file
@@ -0,0 +1,746 @@
|
||||
# AI Compliance SDK - Entwickler-Dokumentation
|
||||
|
||||
## Inhaltsverzeichnis
|
||||
|
||||
1. [Schnellstart](#1-schnellstart)
|
||||
2. [Architektur-Übersicht](#2-architektur-übersicht)
|
||||
3. [Policy Engine](#3-policy-engine)
|
||||
4. [License Policy Engine](#4-license-policy-engine)
|
||||
5. [Legal RAG Integration](#5-legal-rag-integration)
|
||||
6. [Wizard & Legal Assistant](#6-wizard--legal-assistant)
|
||||
7. [Eskalations-System](#7-eskalations-system)
|
||||
8. [API-Endpoints](#8-api-endpoints)
|
||||
9. [Policy-Dateien](#9-policy-dateien)
|
||||
10. [Tests ausführen](#10-tests-ausführen)
|
||||
|
||||
---
|
||||
|
||||
## 1. Schnellstart
|
||||
|
||||
### Voraussetzungen
|
||||
|
||||
- Go 1.21+
|
||||
- PostgreSQL (für Eskalations-Store)
|
||||
- Qdrant (für Legal RAG)
|
||||
- Ollama oder Anthropic API Key (für LLM)
|
||||
|
||||
### Build & Run
|
||||
|
||||
```bash
|
||||
# Build
|
||||
cd ai-compliance-sdk
|
||||
go build -o server ./cmd/server
|
||||
|
||||
# Run
|
||||
./server --config config.yaml
|
||||
|
||||
# Alternativ: mit Docker
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### Erste Anfrage
|
||||
|
||||
```bash
|
||||
# UCCA Assessment erstellen
|
||||
curl -X POST http://localhost:8080/sdk/v1/ucca/assess \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"use_case_text": "Chatbot für Kundenservice mit FAQ-Suche",
|
||||
"domain": "utilities",
|
||||
"data_types": {
|
||||
"personal_data": false,
|
||||
"public_data": true
|
||||
},
|
||||
"automation": "assistive",
|
||||
"model_usage": {
|
||||
"rag": true
|
||||
},
|
||||
"hosting": {
|
||||
"region": "eu"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Architektur-Übersicht
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ API Layer (Gin) │
|
||||
│ internal/api/handlers/ │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
|
||||
│ │ UCCA │ │ License │ │ Eskalation │ │
|
||||
│ │ Handler │ │ Handler │ │ Handler │ │
|
||||
│ └──────┬──────┘ └──────┬──────┘ └───────────┬─────────────┘ │
|
||||
│ │ │ │ │
|
||||
├─────────┼────────────────┼──────────────────────┼────────────────┤
|
||||
│ ▼ ▼ ▼ │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
|
||||
│ │ Policy │ │ License │ │ Escalation │ │
|
||||
│ │ Engine │ │ Policy │ │ Store │ │
|
||||
│ │ │ │ Engine │ │ │ │
|
||||
│ └──────┬──────┘ └──────┬──────┘ └───────────┬─────────────┘ │
|
||||
│ │ │ │ │
|
||||
│ └────────┬───────┴──────────────────────┘ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────┐ │
|
||||
│ │ Legal RAG System │ │
|
||||
│ │ (Qdrant + LLM Integration) │ │
|
||||
│ └─────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Kernprinzip
|
||||
|
||||
**LLM ist NICHT die Quelle der Wahrheit!**
|
||||
|
||||
| Komponente | Entscheidet | LLM-Nutzung |
|
||||
|------------|-------------|-------------|
|
||||
| Policy Engine | Feasibility, Risk Level | Nein |
|
||||
| License Engine | Operation Mode, Stop-Lines | Nein |
|
||||
| Gap Mapping | Facts → Gaps → Controls | Nein |
|
||||
| Legal RAG | Erklärung generieren | Ja (nur Output) |
|
||||
|
||||
---
|
||||
|
||||
## 3. Policy Engine
|
||||
|
||||
### Übersicht
|
||||
|
||||
Die Policy Engine (`internal/ucca/policy_engine.go`) evaluiert Use Cases gegen deterministische Regeln.
|
||||
|
||||
### Verwendung
|
||||
|
||||
```go
|
||||
import "ai-compliance-sdk/internal/ucca"
|
||||
|
||||
// Engine erstellen
|
||||
engine, err := ucca.NewPolicyEngineFromPath("policies/ucca_policy_v1.yaml")
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
// Intake erstellen
|
||||
intake := &ucca.UseCaseIntake{
|
||||
UseCaseText: "Chatbot für Kundenservice",
|
||||
Domain: ucca.DomainUtilities,
|
||||
DataTypes: ucca.DataTypes{
|
||||
PersonalData: false,
|
||||
PublicData: true,
|
||||
},
|
||||
Automation: ucca.AutomationAssistive,
|
||||
ModelUsage: ucca.ModelUsage{
|
||||
RAG: true,
|
||||
},
|
||||
Hosting: ucca.Hosting{
|
||||
Region: "eu",
|
||||
},
|
||||
}
|
||||
|
||||
// Evaluieren
|
||||
result := engine.Evaluate(intake)
|
||||
|
||||
// Ergebnis auswerten
|
||||
fmt.Println("Feasibility:", result.Feasibility) // YES, NO, CONDITIONAL
|
||||
fmt.Println("Risk Level:", result.RiskLevel) // MINIMAL, LOW, MEDIUM, HIGH
|
||||
fmt.Println("Risk Score:", result.RiskScore) // 0-100
|
||||
```
|
||||
|
||||
### Ergebnis-Struktur
|
||||
|
||||
```go
|
||||
type EvaluationResult struct {
|
||||
Feasibility Feasibility // YES, NO, CONDITIONAL
|
||||
RiskLevel RiskLevel // MINIMAL, LOW, MEDIUM, HIGH
|
||||
RiskScore int // 0-100
|
||||
TriggeredRules []TriggeredRule // Ausgelöste Regeln
|
||||
RequiredControls []Control // Erforderliche Maßnahmen
|
||||
RecommendedArchitecture []Pattern // Empfohlene Patterns
|
||||
DSFARecommended bool // DSFA erforderlich?
|
||||
Art22Risk bool // Art. 22 Risiko?
|
||||
TrainingAllowed TrainingAllowed // YES, NO, CONDITIONAL
|
||||
PolicyVersion string // Version der Policy
|
||||
}
|
||||
```
|
||||
|
||||
### Regeln hinzufügen
|
||||
|
||||
Neue Regeln werden in `policies/ucca_policy_v1.yaml` definiert:
|
||||
|
||||
```yaml
|
||||
rules:
|
||||
- id: R-CUSTOM-001
|
||||
code: R-CUSTOM-001
|
||||
category: custom
|
||||
title: Custom Rule
|
||||
title_de: Benutzerdefinierte Regel
|
||||
description: Custom rule description
|
||||
severity: WARN # INFO, WARN, BLOCK
|
||||
gdpr_ref: "Art. 6 DSGVO"
|
||||
condition:
|
||||
all_of:
|
||||
- field: domain
|
||||
equals: custom_domain
|
||||
- field: data_types.personal_data
|
||||
equals: true
|
||||
controls:
|
||||
- C_CUSTOM_CONTROL
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. License Policy Engine
|
||||
|
||||
### Übersicht
|
||||
|
||||
Die License Policy Engine (`internal/ucca/license_policy.go`) prüft die Lizenz-Compliance für Standards und Normen.
|
||||
|
||||
### Operationsmodi
|
||||
|
||||
| Modus | Beschreibung | Lizenzanforderung |
|
||||
|-------|--------------|-------------------|
|
||||
| `LINK_ONLY` | Nur Verweise | Keine |
|
||||
| `NOTES_ONLY` | Eigene Notizen | Keine |
|
||||
| `EXCERPT_ONLY` | Kurzzitate (<150 Zeichen) | Standard-Lizenz |
|
||||
| `FULLTEXT_RAG` | Volltext-Embedding | Explizite KI-Lizenz |
|
||||
| `TRAINING` | Modell-Training | Enterprise + Vertrag |
|
||||
|
||||
### Verwendung
|
||||
|
||||
```go
|
||||
import "ai-compliance-sdk/internal/ucca"
|
||||
|
||||
engine := ucca.NewLicensePolicyEngine()
|
||||
|
||||
facts := &ucca.LicensedContentFacts{
|
||||
Present: true,
|
||||
Publisher: "DIN_MEDIA",
|
||||
LicenseType: "SINGLE_WORKSTATION",
|
||||
AIUsePermitted: "NO",
|
||||
ProofUploaded: false,
|
||||
OperationMode: "FULLTEXT_RAG",
|
||||
}
|
||||
|
||||
result := engine.Evaluate(facts)
|
||||
|
||||
if !result.Allowed {
|
||||
fmt.Println("Blockiert:", result.StopLine.Message)
|
||||
fmt.Println("Effektiver Modus:", result.EffectiveMode)
|
||||
}
|
||||
```
|
||||
|
||||
### Ingest-Entscheidung
|
||||
|
||||
```go
|
||||
// Prüfen ob Volltext-Ingest erlaubt ist
|
||||
canIngest := engine.CanIngestFulltext(facts)
|
||||
|
||||
// Oder detaillierte Entscheidung
|
||||
decision := engine.DecideIngest(facts)
|
||||
fmt.Println("Fulltext:", decision.AllowFulltext)
|
||||
fmt.Println("Notes:", decision.AllowNotes)
|
||||
fmt.Println("Metadata:", decision.AllowMetadata)
|
||||
```
|
||||
|
||||
### Audit-Logging
|
||||
|
||||
```go
|
||||
// Audit-Entry erstellen
|
||||
entry := engine.FormatAuditEntry("tenant-123", "doc-456", facts, result)
|
||||
|
||||
// Human-readable Summary
|
||||
summary := engine.FormatHumanReadableSummary(result)
|
||||
fmt.Println(summary)
|
||||
```
|
||||
|
||||
### Publisher-spezifische Regeln
|
||||
|
||||
DIN Media hat explizite Restriktionen:
|
||||
|
||||
```go
|
||||
// DIN Media blockiert FULLTEXT_RAG ohne AI-Lizenz
|
||||
if facts.Publisher == "DIN_MEDIA" && facts.AIUsePermitted != "YES" {
|
||||
// → STOP_DIN_FULLTEXT_AI_NOT_ALLOWED
|
||||
// → Downgrade auf LINK_ONLY
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Legal RAG Integration
|
||||
|
||||
### Übersicht
|
||||
|
||||
Das Legal RAG System (`internal/ucca/legal_rag.go`) generiert Erklärungen mit rechtlichem Kontext.
|
||||
|
||||
### Verwendung
|
||||
|
||||
```go
|
||||
import "ai-compliance-sdk/internal/ucca"
|
||||
|
||||
rag := ucca.NewLegalRAGService(qdrantClient, llmClient, "bp_legal_corpus")
|
||||
|
||||
// Erklärung generieren
|
||||
explanation, err := rag.Explain(ctx, result, intake)
|
||||
if err != nil {
|
||||
log.Error(err)
|
||||
}
|
||||
|
||||
fmt.Println("Erklärung:", explanation.Text)
|
||||
fmt.Println("Rechtsquellen:", explanation.Sources)
|
||||
```
|
||||
|
||||
### Rechtsquellen im RAG
|
||||
|
||||
| Quelle | Chunks | Beschreibung |
|
||||
|--------|--------|--------------|
|
||||
| DSGVO | 128 | EU Datenschutz-Grundverordnung |
|
||||
| AI Act | 96 | EU AI-Verordnung |
|
||||
| NIS2 | 128 | Netzwerk-Informationssicherheit |
|
||||
| SCC | 32 | Standardvertragsklauseln |
|
||||
| DPF | 714 | Data Privacy Framework |
|
||||
|
||||
---
|
||||
|
||||
## 6. Wizard & Legal Assistant
|
||||
|
||||
### Wizard-Schema
|
||||
|
||||
Das Wizard-Schema (`policies/wizard_schema_v1.yaml`) definiert die Fragen für das Frontend.
|
||||
|
||||
### Legal Assistant verwenden
|
||||
|
||||
```go
|
||||
// Wizard-Frage an Legal Assistant stellen
|
||||
type WizardAskRequest struct {
|
||||
Question string `json:"question"`
|
||||
StepNumber int `json:"step_number"`
|
||||
FieldID string `json:"field_id,omitempty"`
|
||||
CurrentData map[string]interface{} `json:"current_data,omitempty"`
|
||||
}
|
||||
|
||||
// POST /sdk/v1/ucca/wizard/ask
|
||||
```
|
||||
|
||||
### Beispiel API-Call
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/sdk/v1/ucca/wizard/ask \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"question": "Was sind personenbezogene Daten?",
|
||||
"step_number": 2,
|
||||
"field_id": "data_types.personal_data"
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Eskalations-System
|
||||
|
||||
### Eskalationsstufen
|
||||
|
||||
| Level | Auslöser | Prüfer | SLA |
|
||||
|-------|----------|--------|-----|
|
||||
| E0 | Nur INFO | Automatisch | - |
|
||||
| E1 | WARN, geringes Risiko | Team-Lead | 24h |
|
||||
| E2 | Art. 9, DSFA empfohlen | DSB | 8h |
|
||||
| E3 | BLOCK, hohes Risiko | DSB + Legal | 4h |
|
||||
|
||||
### Eskalation erstellen
|
||||
|
||||
```go
|
||||
import "ai-compliance-sdk/internal/ucca"
|
||||
|
||||
store := ucca.NewEscalationStore(db)
|
||||
|
||||
escalation := &ucca.Escalation{
|
||||
AssessmentID: "assess-123",
|
||||
Level: ucca.EscalationE2,
|
||||
TriggerReason: "Art. 9 Daten betroffen",
|
||||
RequiredReviews: 1,
|
||||
}
|
||||
|
||||
err := store.CreateEscalation(ctx, escalation)
|
||||
```
|
||||
|
||||
### SLA-Monitor
|
||||
|
||||
```go
|
||||
monitor := ucca.NewSLAMonitor(store, notificationService)
|
||||
|
||||
// Im Hintergrund starten
|
||||
go monitor.Start(ctx)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. API-Endpoints
|
||||
|
||||
### UCCA Endpoints
|
||||
|
||||
| Method | Endpoint | Beschreibung |
|
||||
|--------|----------|--------------|
|
||||
| POST | `/sdk/v1/ucca/assess` | Assessment erstellen |
|
||||
| GET | `/sdk/v1/ucca/assess/:id` | Assessment abrufen |
|
||||
| POST | `/sdk/v1/ucca/explain` | Erklärung generieren |
|
||||
| GET | `/sdk/v1/ucca/wizard/schema` | Wizard-Schema abrufen |
|
||||
| POST | `/sdk/v1/ucca/wizard/ask` | Legal Assistant fragen |
|
||||
|
||||
### License Endpoints
|
||||
|
||||
| Method | Endpoint | Beschreibung |
|
||||
|--------|----------|--------------|
|
||||
| POST | `/sdk/v1/license/evaluate` | Lizenz-Prüfung |
|
||||
| POST | `/sdk/v1/license/decide-ingest` | Ingest-Entscheidung |
|
||||
|
||||
### Eskalations-Endpoints
|
||||
|
||||
| Method | Endpoint | Beschreibung |
|
||||
|--------|----------|--------------|
|
||||
| GET | `/sdk/v1/escalations` | Offene Eskalationen |
|
||||
| GET | `/sdk/v1/escalations/:id` | Eskalation abrufen |
|
||||
| POST | `/sdk/v1/escalations/:id/decide` | Entscheidung treffen |
|
||||
|
||||
---
|
||||
|
||||
## 9. Policy-Dateien
|
||||
|
||||
### Dateistruktur
|
||||
|
||||
```
|
||||
policies/
|
||||
├── ucca_policy_v1.yaml # Haupt-Policy (Regeln, Controls, Patterns)
|
||||
├── wizard_schema_v1.yaml # Wizard-Fragen und Legal Assistant
|
||||
├── controls_catalog.yaml # Detaillierte Control-Beschreibungen
|
||||
├── gap_mapping.yaml # Facts → Gaps → Controls
|
||||
├── licensed_content_policy.yaml # Standards/Normen Compliance
|
||||
└── scc_legal_corpus.yaml # SCC Rechtsquellen
|
||||
```
|
||||
|
||||
### Policy-Version
|
||||
|
||||
Jede Policy hat eine Version:
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
version: "1.0.0"
|
||||
effective_date: "2025-01-01"
|
||||
author: "Compliance Team"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Tests ausführen
|
||||
|
||||
### Alle Tests
|
||||
|
||||
```bash
|
||||
cd ai-compliance-sdk
|
||||
go test -v ./...
|
||||
```
|
||||
|
||||
### Spezifische Tests
|
||||
|
||||
```bash
|
||||
# Policy Engine Tests
|
||||
go test -v ./internal/ucca/policy_engine_test.go
|
||||
|
||||
# License Policy Tests
|
||||
go test -v ./internal/ucca/license_policy_test.go
|
||||
|
||||
# Eskalation Tests
|
||||
go test -v ./internal/ucca/escalation_test.go
|
||||
```
|
||||
|
||||
### Test-Coverage
|
||||
|
||||
```bash
|
||||
go test -cover ./...
|
||||
|
||||
# HTML-Report
|
||||
go test -coverprofile=coverage.out ./...
|
||||
go tool cover -html=coverage.out
|
||||
```
|
||||
|
||||
### Beispiel: Neuen Test hinzufügen
|
||||
|
||||
```go
|
||||
func TestMyNewFeature(t *testing.T) {
|
||||
engine := NewLicensePolicyEngine()
|
||||
|
||||
facts := &LicensedContentFacts{
|
||||
Present: true,
|
||||
Publisher: "DIN_MEDIA",
|
||||
OperationMode: "FULLTEXT_RAG",
|
||||
}
|
||||
|
||||
result := engine.Evaluate(facts)
|
||||
|
||||
if result.Allowed {
|
||||
t.Error("Expected blocked for DIN_MEDIA FULLTEXT_RAG")
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Generic Obligations Framework
|
||||
|
||||
### Übersicht
|
||||
|
||||
Das Obligations Framework ermöglicht die automatische Ableitung regulatorischer Pflichten aus NIS2, DSGVO und AI Act.
|
||||
|
||||
### Verwendung
|
||||
|
||||
```go
|
||||
import "ai-compliance-sdk/internal/ucca"
|
||||
|
||||
// Registry erstellen (lädt alle Module)
|
||||
registry := ucca.NewObligationsRegistry()
|
||||
|
||||
// UnifiedFacts aufbauen
|
||||
facts := &ucca.UnifiedFacts{
|
||||
Organization: ucca.OrganizationFacts{
|
||||
EmployeeCount: 150,
|
||||
AnnualRevenue: 30000000,
|
||||
Country: "DE",
|
||||
EUMember: true,
|
||||
},
|
||||
Sector: ucca.SectorFacts{
|
||||
PrimarySector: "digital_infrastructure",
|
||||
SpecialServices: []string{"cloud", "msp"},
|
||||
IsKRITIS: false,
|
||||
},
|
||||
DataProtection: ucca.DataProtectionFacts{
|
||||
ProcessesPersonalData: true,
|
||||
},
|
||||
AIUsage: ucca.AIUsageFacts{
|
||||
UsesAI: true,
|
||||
HighRiskCategories: []string{"employment"},
|
||||
IsGPAIProvider: false,
|
||||
},
|
||||
}
|
||||
|
||||
// Alle anwendbaren Pflichten evaluieren
|
||||
overview := registry.EvaluateAll(facts, "Muster GmbH")
|
||||
|
||||
// Ergebnis auswerten
|
||||
fmt.Println("Anwendbare Regulierungen:", len(overview.ApplicableRegulations))
|
||||
fmt.Println("Gesamtzahl Pflichten:", len(overview.Obligations))
|
||||
fmt.Println("Kritische Pflichten:", overview.ExecutiveSummary.CriticalObligations)
|
||||
```
|
||||
|
||||
### Neues Regulierungsmodul erstellen
|
||||
|
||||
```go
|
||||
// 1. Module-Interface implementieren
|
||||
type MyRegulationModule struct {
|
||||
obligations []ucca.Obligation
|
||||
controls []ucca.ObligationControl
|
||||
incidentDeadlines []ucca.IncidentDeadline
|
||||
}
|
||||
|
||||
func (m *MyRegulationModule) ID() string { return "my_regulation" }
|
||||
func (m *MyRegulationModule) Name() string { return "My Regulation" }
|
||||
|
||||
func (m *MyRegulationModule) IsApplicable(facts *ucca.UnifiedFacts) bool {
|
||||
// Prüflogik implementieren
|
||||
return facts.Organization.Country == "DE"
|
||||
}
|
||||
|
||||
func (m *MyRegulationModule) DeriveObligations(facts *ucca.UnifiedFacts) []ucca.Obligation {
|
||||
// Pflichten basierend auf Facts ableiten
|
||||
return m.obligations
|
||||
}
|
||||
|
||||
// 2. In Registry registrieren
|
||||
func NewMyRegulationModule() (*MyRegulationModule, error) {
|
||||
m := &MyRegulationModule{}
|
||||
// YAML laden oder hardcoded Pflichten definieren
|
||||
return m, nil
|
||||
}
|
||||
|
||||
// In obligations_registry.go:
|
||||
// r.Register(NewMyRegulationModule())
|
||||
```
|
||||
|
||||
### YAML-basierte Pflichten
|
||||
|
||||
```yaml
|
||||
# policies/obligations/my_regulation_obligations.yaml
|
||||
regulation: my_regulation
|
||||
name: "My Regulation"
|
||||
|
||||
obligations:
|
||||
- id: "MYREG-OBL-001"
|
||||
title: "Compliance-Pflicht"
|
||||
description: "Beschreibung der Pflicht"
|
||||
applies_when: "classification != 'nicht_betroffen'"
|
||||
legal_basis:
|
||||
- norm: "§ 1 MyReg"
|
||||
category: "Governance"
|
||||
responsible: "Geschäftsführung"
|
||||
deadline:
|
||||
type: "relative"
|
||||
duration: "12 Monate"
|
||||
sanctions:
|
||||
max_fine: "1 Mio. EUR"
|
||||
priority: "high"
|
||||
|
||||
controls:
|
||||
- id: "MYREG-CTRL-001"
|
||||
name: "Kontrollmaßnahme"
|
||||
category: "Technical"
|
||||
when_applicable: "immer"
|
||||
what_to_do: "Maßnahme implementieren"
|
||||
evidence_needed:
|
||||
- "Dokumentation"
|
||||
```
|
||||
|
||||
### PDF Export
|
||||
|
||||
```go
|
||||
import "ai-compliance-sdk/internal/ucca"
|
||||
|
||||
// Exporter erstellen
|
||||
exporter := ucca.NewPDFExporter("de")
|
||||
|
||||
// PDF generieren
|
||||
response, err := exporter.ExportManagementMemo(overview)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
// base64-kodierter PDF-Inhalt
|
||||
fmt.Println("Content-Type:", response.ContentType) // application/pdf
|
||||
fmt.Println("Filename:", response.Filename)
|
||||
|
||||
// PDF speichern
|
||||
decoded, _ := base64.StdEncoding.DecodeString(response.Content)
|
||||
os.WriteFile("memo.pdf", decoded, 0644)
|
||||
|
||||
// Alternativ: Markdown
|
||||
mdResponse, err := exporter.ExportMarkdown(overview)
|
||||
fmt.Println(mdResponse.Content) // Markdown-Text
|
||||
```
|
||||
|
||||
### API-Endpoints
|
||||
|
||||
```bash
|
||||
# Assessment erstellen
|
||||
curl -X POST http://localhost:8090/sdk/v1/ucca/obligations/assess \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"facts": {
|
||||
"organization": {"employee_count": 150, "country": "DE"},
|
||||
"sector": {"primary_sector": "healthcare"},
|
||||
"data_protection": {"processes_personal_data": true},
|
||||
"ai_usage": {"uses_ai": false}
|
||||
},
|
||||
"organization_name": "Test GmbH"
|
||||
}'
|
||||
|
||||
# PDF Export (direkt)
|
||||
curl -X POST http://localhost:8090/sdk/v1/ucca/obligations/export/direct \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"overview": { ... },
|
||||
"format": "pdf",
|
||||
"language": "de"
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. Tests für Obligations Framework
|
||||
|
||||
```bash
|
||||
# Alle Obligations-Tests
|
||||
go test -v ./internal/ucca/..._module_test.go
|
||||
|
||||
# NIS2 Module Tests
|
||||
go test -v ./internal/ucca/nis2_module_test.go
|
||||
|
||||
# DSGVO Module Tests
|
||||
go test -v ./internal/ucca/dsgvo_module_test.go
|
||||
|
||||
# AI Act Module Tests
|
||||
go test -v ./internal/ucca/ai_act_module_test.go
|
||||
|
||||
# PDF Export Tests
|
||||
go test -v ./internal/ucca/pdf_export_test.go
|
||||
```
|
||||
|
||||
### Beispiel-Tests
|
||||
|
||||
```go
|
||||
func TestNIS2Module_LargeCompanyInAnnexISector(t *testing.T) {
|
||||
module, _ := ucca.NewNIS2Module()
|
||||
|
||||
facts := &ucca.UnifiedFacts{
|
||||
Organization: ucca.OrganizationFacts{
|
||||
EmployeeCount: 500,
|
||||
AnnualRevenue: 100000000,
|
||||
Country: "DE",
|
||||
},
|
||||
Sector: ucca.SectorFacts{
|
||||
PrimarySector: "energy",
|
||||
},
|
||||
}
|
||||
|
||||
if !module.IsApplicable(facts) {
|
||||
t.Error("Expected NIS2 to apply to large energy company")
|
||||
}
|
||||
|
||||
classification := module.Classify(facts)
|
||||
if classification != "besonders_wichtige_einrichtung" {
|
||||
t.Errorf("Expected 'besonders_wichtige_einrichtung', got '%s'", classification)
|
||||
}
|
||||
}
|
||||
|
||||
func TestAIActModule_HighRiskEmploymentAI(t *testing.T) {
|
||||
module, _ := ucca.NewAIActModule()
|
||||
|
||||
facts := &ucca.UnifiedFacts{
|
||||
AIUsage: ucca.AIUsageFacts{
|
||||
UsesAI: true,
|
||||
HighRiskCategories: []string{"employment"},
|
||||
},
|
||||
}
|
||||
|
||||
if !module.IsApplicable(facts) {
|
||||
t.Error("Expected AI Act to apply")
|
||||
}
|
||||
|
||||
riskLevel := module.ClassifyRisk(facts)
|
||||
if riskLevel != ucca.AIActHighRisk {
|
||||
t.Errorf("Expected 'high_risk', got '%s'", riskLevel)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Anhang: Wichtige Dateien
|
||||
|
||||
| Datei | Beschreibung |
|
||||
|-------|--------------|
|
||||
| `internal/ucca/policy_engine.go` | Haupt-Policy-Engine |
|
||||
| `internal/ucca/license_policy.go` | License Policy Engine |
|
||||
| `internal/ucca/obligations_framework.go` | Obligations Interfaces & Typen |
|
||||
| `internal/ucca/obligations_registry.go` | Modul-Registry |
|
||||
| `internal/ucca/nis2_module.go` | NIS2 Decision Tree |
|
||||
| `internal/ucca/dsgvo_module.go` | DSGVO Pflichten |
|
||||
| `internal/ucca/ai_act_module.go` | AI Act Risk Classification |
|
||||
| `internal/ucca/pdf_export.go` | PDF/Markdown Export |
|
||||
| `internal/api/handlers/obligations_handlers.go` | Obligations API |
|
||||
| `policies/obligations/*.yaml` | Pflichten-Kataloge |
|
||||
|
||||
---
|
||||
|
||||
*Dokumentationsstand: 2026-01-29*
|
||||
220
docs-src/services/ai-compliance-sdk/SBOM.md
Normal file
220
docs-src/services/ai-compliance-sdk/SBOM.md
Normal file
@@ -0,0 +1,220 @@
|
||||
# AI Compliance SDK - Software Bill of Materials (SBOM)
|
||||
|
||||
**Erstellt:** 2026-01-29
|
||||
**Go-Version:** 1.24.0
|
||||
|
||||
---
|
||||
|
||||
## Zusammenfassung
|
||||
|
||||
| Kategorie | Anzahl | Status |
|
||||
|-----------|--------|--------|
|
||||
| Direkte Abhängigkeiten | 7 | ✅ Alle kommerziell nutzbar |
|
||||
| Indirekte Abhängigkeiten | ~45 | ✅ Alle kommerziell nutzbar |
|
||||
| **Gesamt** | ~52 | ✅ **Alle Open Source, kommerziell nutzbar** |
|
||||
|
||||
---
|
||||
|
||||
## Direkte Abhängigkeiten
|
||||
|
||||
| Package | Version | Lizenz | Kommerziell nutzbar |
|
||||
|---------|---------|--------|---------------------|
|
||||
| `github.com/gin-gonic/gin` | v1.10.1 | **MIT** | ✅ Ja |
|
||||
| `github.com/gin-contrib/cors` | v1.7.6 | **MIT** | ✅ Ja |
|
||||
| `github.com/google/uuid` | v1.6.0 | **BSD-3-Clause** | ✅ Ja |
|
||||
| `github.com/jackc/pgx/v5` | v5.5.3 | **MIT** | ✅ Ja |
|
||||
| `github.com/joho/godotenv` | v1.5.1 | **MIT** | ✅ Ja |
|
||||
| `github.com/xuri/excelize/v2` | v2.9.1 | **BSD-3-Clause** | ✅ Ja |
|
||||
| `gopkg.in/yaml.v3` | v3.0.1 | **MIT / Apache-2.0** | ✅ Ja |
|
||||
|
||||
---
|
||||
|
||||
## Indirekte Abhängigkeiten (Transitive)
|
||||
|
||||
### JSON / Serialisierung
|
||||
|
||||
| Package | Version | Lizenz | Kommerziell nutzbar |
|
||||
|---------|---------|--------|---------------------|
|
||||
| `github.com/bytedance/sonic` | v1.13.3 | **Apache-2.0** | ✅ Ja |
|
||||
| `github.com/goccy/go-json` | v0.10.5 | **MIT** | ✅ Ja |
|
||||
| `github.com/json-iterator/go` | v1.1.12 | **MIT** | ✅ Ja |
|
||||
| `github.com/pelletier/go-toml/v2` | v2.2.4 | **MIT** | ✅ Ja |
|
||||
| `gopkg.in/yaml.v3` | v3.0.1 | **MIT / Apache-2.0** | ✅ Ja |
|
||||
| `github.com/ugorji/go/codec` | v1.3.0 | **MIT** | ✅ Ja |
|
||||
|
||||
### Web Framework (Gin-Ökosystem)
|
||||
|
||||
| Package | Version | Lizenz | Kommerziell nutzbar |
|
||||
|---------|---------|--------|---------------------|
|
||||
| `github.com/gin-contrib/sse` | v1.1.0 | **MIT** | ✅ Ja |
|
||||
| `github.com/go-playground/validator/v10` | v10.26.0 | **MIT** | ✅ Ja |
|
||||
| `github.com/go-playground/locales` | v0.14.1 | **MIT** | ✅ Ja |
|
||||
| `github.com/go-playground/universal-translator` | v0.18.1 | **MIT** | ✅ Ja |
|
||||
| `github.com/leodido/go-urn` | v1.4.0 | **MIT** | ✅ Ja |
|
||||
|
||||
### Datenbank (PostgreSQL)
|
||||
|
||||
| Package | Version | Lizenz | Kommerziell nutzbar |
|
||||
|---------|---------|--------|---------------------|
|
||||
| `github.com/jackc/pgpassfile` | v1.0.0 | **MIT** | ✅ Ja |
|
||||
| `github.com/jackc/pgservicefile` | v0.0.0-... | **MIT** | ✅ Ja |
|
||||
| `github.com/jackc/puddle/v2` | v2.2.1 | **MIT** | ✅ Ja |
|
||||
|
||||
### Excel-Verarbeitung
|
||||
|
||||
| Package | Version | Lizenz | Kommerziell nutzbar |
|
||||
|---------|---------|--------|---------------------|
|
||||
| `github.com/xuri/excelize/v2` | v2.9.1 | **BSD-3-Clause** | ✅ Ja |
|
||||
| `github.com/xuri/efp` | v0.0.1 | **BSD-3-Clause** | ✅ Ja |
|
||||
| `github.com/xuri/nfp` | v0.0.2-... | **BSD-3-Clause** | ✅ Ja |
|
||||
| `github.com/richardlehane/mscfb` | v1.0.4 | **Apache-2.0** | ✅ Ja |
|
||||
| `github.com/richardlehane/msoleps` | v1.0.4 | **Apache-2.0** | ✅ Ja |
|
||||
|
||||
### PDF-Generierung
|
||||
|
||||
| Package | Version | Lizenz | Kommerziell nutzbar |
|
||||
|---------|---------|--------|---------------------|
|
||||
| `github.com/jung-kurt/gofpdf` | v1.16.2 | **MIT** | ✅ Ja |
|
||||
|
||||
### Utilities
|
||||
|
||||
| Package | Version | Lizenz | Kommerziell nutzbar |
|
||||
|---------|---------|--------|---------------------|
|
||||
| `github.com/gabriel-vasile/mimetype` | v1.4.9 | **MIT** | ✅ Ja |
|
||||
| `github.com/mattn/go-isatty` | v0.0.20 | **MIT** | ✅ Ja |
|
||||
| `github.com/modern-go/concurrent` | v0.0.0-... | **Apache-2.0** | ✅ Ja |
|
||||
| `github.com/modern-go/reflect2` | v1.0.2 | **Apache-2.0** | ✅ Ja |
|
||||
| `github.com/klauspost/cpuid/v2` | v2.2.10 | **MIT** | ✅ Ja |
|
||||
| `github.com/tiendc/go-deepcopy` | v1.7.1 | **MIT** | ✅ Ja |
|
||||
| `github.com/twitchyliquid64/golang-asm` | v0.15.1 | **MIT** | ✅ Ja |
|
||||
| `github.com/cloudwego/base64x` | v0.1.5 | **Apache-2.0** | ✅ Ja |
|
||||
|
||||
### Go Standardbibliothek Erweiterungen
|
||||
|
||||
| Package | Version | Lizenz | Kommerziell nutzbar |
|
||||
|---------|---------|--------|---------------------|
|
||||
| `golang.org/x/arch` | v0.18.0 | **BSD-3-Clause** | ✅ Ja |
|
||||
| `golang.org/x/crypto` | v0.43.0 | **BSD-3-Clause** | ✅ Ja |
|
||||
| `golang.org/x/net` | v0.46.0 | **BSD-3-Clause** | ✅ Ja |
|
||||
| `golang.org/x/sync` | v0.17.0 | **BSD-3-Clause** | ✅ Ja |
|
||||
| `golang.org/x/sys` | v0.37.0 | **BSD-3-Clause** | ✅ Ja |
|
||||
| `golang.org/x/text` | v0.30.0 | **BSD-3-Clause** | ✅ Ja |
|
||||
|
||||
### Protokoll-Bibliotheken
|
||||
|
||||
| Package | Version | Lizenz | Kommerziell nutzbar |
|
||||
|---------|---------|--------|---------------------|
|
||||
| `google.golang.org/protobuf` | v1.36.6 | **BSD-3-Clause** | ✅ Ja |
|
||||
|
||||
---
|
||||
|
||||
## Lizenz-Übersicht
|
||||
|
||||
| Lizenz | Anzahl Packages | Kommerziell nutzbar | Copyleft |
|
||||
|--------|-----------------|---------------------|----------|
|
||||
| **MIT** | ~25 | ✅ Ja | ❌ Nein |
|
||||
| **Apache-2.0** | ~8 | ✅ Ja | ❌ Nein (schwach) |
|
||||
| **BSD-3-Clause** | ~12 | ✅ Ja | ❌ Nein |
|
||||
| **BSD-2-Clause** | 0 | ✅ Ja | ❌ Nein |
|
||||
|
||||
### Keine problematischen Lizenzen!
|
||||
|
||||
| Lizenz | Status |
|
||||
|--------|--------|
|
||||
| GPL-2.0 | ❌ **Nicht verwendet** |
|
||||
| GPL-3.0 | ❌ **Nicht verwendet** |
|
||||
| AGPL | ❌ **Nicht verwendet** |
|
||||
| LGPL | ❌ **Nicht verwendet** |
|
||||
| SSPL | ❌ **Nicht verwendet** |
|
||||
| Commons Clause | ❌ **Nicht verwendet** |
|
||||
|
||||
---
|
||||
|
||||
## Eigene Komponenten (Keine externen Abhängigkeiten)
|
||||
|
||||
Die folgenden Komponenten wurden im Rahmen des AI Compliance SDK entwickelt und haben **keine zusätzlichen Abhängigkeiten**:
|
||||
|
||||
| Komponente | Dateien | Externe Deps |
|
||||
|------------|---------|--------------|
|
||||
| Policy Engine | `internal/ucca/policy_engine.go` | Keine |
|
||||
| License Policy Engine | `internal/ucca/license_policy.go` | Keine |
|
||||
| Legal RAG | `internal/ucca/legal_rag.go` | Keine |
|
||||
| Escalation System | `internal/ucca/escalation_*.go` | Keine |
|
||||
| SLA Monitor | `internal/ucca/sla_monitor.go` | Keine |
|
||||
| UCCA Handlers | `internal/api/handlers/ucca_handlers.go` | Gin (MIT) |
|
||||
| **Obligations Framework** | `internal/ucca/obligations_framework.go` | Keine |
|
||||
| **Obligations Registry** | `internal/ucca/obligations_registry.go` | Keine |
|
||||
| **NIS2 Module** | `internal/ucca/nis2_module.go` | Keine |
|
||||
| **DSGVO Module** | `internal/ucca/dsgvo_module.go` | Keine |
|
||||
| **AI Act Module** | `internal/ucca/ai_act_module.go` | Keine |
|
||||
| **PDF Export** | `internal/ucca/pdf_export.go` | gofpdf (MIT) |
|
||||
| **Obligations Handlers** | `internal/api/handlers/obligations_handlers.go` | Gin (MIT) |
|
||||
| **Funding Models** | `internal/funding/models.go` | Keine |
|
||||
| **Funding Store** | `internal/funding/store.go`, `postgres_store.go` | pgx (MIT) |
|
||||
| **Funding Export** | `internal/funding/export.go` | gofpdf (MIT), excelize (BSD-3) |
|
||||
| **Funding Handlers** | `internal/api/handlers/funding_handlers.go` | Gin (MIT) |
|
||||
|
||||
### Policy-Dateien (Reine YAML/JSON)
|
||||
|
||||
| Datei | Format | Abhängigkeiten |
|
||||
|-------|--------|----------------|
|
||||
| `ucca_policy_v1.yaml` | YAML | Keine |
|
||||
| `wizard_schema_v1.yaml` | YAML | Keine |
|
||||
| `controls_catalog.yaml` | YAML | Keine |
|
||||
| `gap_mapping.yaml` | YAML | Keine |
|
||||
| `licensed_content_policy.yaml` | YAML | Keine |
|
||||
| `financial_regulations_policy.yaml` | YAML | Keine |
|
||||
| `financial_regulations_corpus.yaml` | YAML | Keine |
|
||||
| `scc_legal_corpus.yaml` | YAML | Keine |
|
||||
| **`obligations/nis2_obligations.yaml`** | YAML | Keine |
|
||||
| **`obligations/dsgvo_obligations.yaml`** | YAML | Keine |
|
||||
| **`obligations/ai_act_obligations.yaml`** | YAML | Keine |
|
||||
| **`funding/foerderantrag_wizard_v1.yaml`** | YAML | Keine |
|
||||
| **`funding/bundesland_profiles.yaml`** | YAML | Keine |
|
||||
|
||||
---
|
||||
|
||||
## Compliance-Erklärung
|
||||
|
||||
### Für kommerzielle Nutzung geeignet: ✅ JA
|
||||
|
||||
Alle verwendeten Abhängigkeiten verwenden **permissive Open-Source-Lizenzen**:
|
||||
|
||||
1. **MIT-Lizenz**: Erlaubt kommerzielle Nutzung, Modifikation, Distribution. Nur Lizenzhinweis erforderlich.
|
||||
|
||||
2. **Apache-2.0-Lizenz**: Erlaubt kommerzielle Nutzung, Modifikation, Distribution. Patentgewährung enthalten.
|
||||
|
||||
3. **BSD-3-Clause**: Erlaubt kommerzielle Nutzung, Modifikation, Distribution. Nur Lizenzhinweis erforderlich.
|
||||
|
||||
### Keine Copyleft-Lizenzen
|
||||
|
||||
Es werden **keine** Copyleft-Lizenzen (GPL, AGPL, LGPL) verwendet, die eine Offenlegung des eigenen Quellcodes erfordern würden.
|
||||
|
||||
### Empfohlene Maßnahmen
|
||||
|
||||
1. **NOTICE-Datei pflegen**: Alle Lizenztexte in einer NOTICE-Datei zusammenfassen
|
||||
2. **Regelmäßige Updates**: Abhängigkeiten auf bekannte Schwachstellen prüfen
|
||||
3. **License-Scanner**: Tool wie `go-licenses` oder `fossa` für automatisierte Prüfung
|
||||
|
||||
---
|
||||
|
||||
## Generierung des SBOM
|
||||
|
||||
```bash
|
||||
# SBOM im SPDX-Format generieren
|
||||
go install github.com/spdx/tools-golang/cmd/spdx-tvwriter@latest
|
||||
go mod download
|
||||
# Manuell: SPDX-Dokument erstellen
|
||||
|
||||
# Alternativ: CycloneDX Format
|
||||
go install github.com/CycloneDX/cyclonedx-gomod/cmd/cyclonedx-gomod@latest
|
||||
cyclonedx-gomod mod -output sbom.json
|
||||
|
||||
# Lizenz-Prüfung
|
||||
go install github.com/google/go-licenses@latest
|
||||
go-licenses csv github.com/breakpilot/ai-compliance-sdk/...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*Dokumentationsstand: 2026-01-29*
|
||||
97
docs-src/services/ai-compliance-sdk/index.md
Normal file
97
docs-src/services/ai-compliance-sdk/index.md
Normal file
@@ -0,0 +1,97 @@
|
||||
# AI Compliance SDK
|
||||
|
||||
Das AI Compliance SDK ist ein Go-basierter Service zur Compliance-Bewertung von KI-Anwendungsfällen.
|
||||
|
||||
## Übersicht
|
||||
|
||||
| Eigenschaft | Wert |
|
||||
|-------------|------|
|
||||
| **Port** | 8090 |
|
||||
| **Framework** | Go (Gin) |
|
||||
| **Datenbank** | PostgreSQL |
|
||||
| **Vector DB** | Qdrant (Legal RAG) |
|
||||
|
||||
## Kernkomponenten
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ UCCA System │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ Frontend │───>│ SDK API │───>│ PostgreSQL │ │
|
||||
│ │ (Next.js) │ │ (Go) │ │ Database │ │
|
||||
│ └──────────────┘ └──────┬───────┘ └──────────────┘ │
|
||||
│ │ │
|
||||
│ ┌────────────────────┼────────────────────┐ │
|
||||
│ │ │ │ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ Policy │ │ Escalation │ │ Legal RAG │ │
|
||||
│ │ Engine │ │ Workflow │ │ (Qdrant) │ │
|
||||
│ │ (45 Regeln) │ │ (E0-E3) │ │ 2,274 Chunks │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Features
|
||||
|
||||
- **UCCA (Use-Case Compliance Advisor)**: Deterministische Bewertung von KI-Anwendungsfällen
|
||||
- **Policy Engine**: 45 regelbasierte Compliance-Prüfungen
|
||||
- **License Policy Engine**: Standards/Normen-Compliance (DIN, ISO, VDI)
|
||||
- **Legal RAG**: Semantische Suche in EU-Verordnungen (DSGVO, AI Act, NIS2)
|
||||
- **Eskalations-Workflow**: E0-E3 Stufen mit Human-in-the-Loop
|
||||
- **Wizard & Legal Assistant**: Geführte Eingabe mit Rechtsassistent
|
||||
- **Generic Obligations Framework**: NIS2, DSGVO, AI Act Module
|
||||
|
||||
## Kernprinzip
|
||||
|
||||
> **"LLM ist NICHT die Quelle der Wahrheit. Wahrheit = Regeln + Evidenz. LLM = Übersetzer + Subsumptionshelfer"**
|
||||
|
||||
Das System folgt einem strikten **Human-in-the-Loop** Ansatz:
|
||||
|
||||
1. **Deterministische Regeln** treffen alle Compliance-Entscheidungen
|
||||
2. **LLM** erklärt nur Ergebnisse, überschreibt nie BLOCK-Entscheidungen
|
||||
3. **Menschen** (DSB, Legal) treffen finale Entscheidungen bei kritischen Fällen
|
||||
|
||||
## API-Endpunkte
|
||||
|
||||
### Assessment
|
||||
|
||||
| Method | Endpoint | Beschreibung |
|
||||
|--------|----------|--------------|
|
||||
| POST | `/sdk/v1/ucca/assess` | Assessment erstellen |
|
||||
| GET | `/sdk/v1/ucca/assessments` | Assessments auflisten |
|
||||
| GET | `/sdk/v1/ucca/assessments/:id` | Assessment abrufen |
|
||||
| POST | `/sdk/v1/ucca/assessments/:id/explain` | LLM-Erklärung generieren |
|
||||
|
||||
### Eskalation
|
||||
|
||||
| Method | Endpoint | Beschreibung |
|
||||
|--------|----------|--------------|
|
||||
| GET | `/sdk/v1/ucca/escalations` | Eskalationen auflisten |
|
||||
| POST | `/sdk/v1/ucca/escalations/:id/decide` | Entscheidung treffen |
|
||||
|
||||
### Obligations Framework
|
||||
|
||||
| Method | Endpoint | Beschreibung |
|
||||
|--------|----------|--------------|
|
||||
| POST | `/sdk/v1/ucca/obligations/assess` | Pflichten-Assessment |
|
||||
| POST | `/sdk/v1/ucca/obligations/export/memo` | PDF-Export |
|
||||
|
||||
## Weiterführende Dokumentation
|
||||
|
||||
- [Architektur](./ARCHITECTURE.md) - Detaillierte Systemarchitektur
|
||||
- [Entwickler-Guide](./DEVELOPER.md) - Entwickler-Dokumentation
|
||||
- [Auditor-Dokumentation](./AUDITOR_DOCUMENTATION.md) - Dokumentation für externe Auditoren
|
||||
|
||||
## Tests
|
||||
|
||||
```bash
|
||||
cd ai-compliance-sdk
|
||||
go test -v ./...
|
||||
|
||||
# Mit Coverage
|
||||
go test -cover ./...
|
||||
```
|
||||
68
mkdocs.yml
Normal file
68
mkdocs.yml
Normal file
@@ -0,0 +1,68 @@
|
||||
site_name: BreakPilot Compliance - Dokumentation
|
||||
site_url: https://macmini:8011
|
||||
docs_dir: docs-src
|
||||
site_dir: docs-site
|
||||
|
||||
theme:
|
||||
name: material
|
||||
language: de
|
||||
palette:
|
||||
- scheme: default
|
||||
primary: purple
|
||||
accent: purple
|
||||
toggle:
|
||||
icon: material/brightness-7
|
||||
name: Dark Mode
|
||||
- scheme: slate
|
||||
primary: purple
|
||||
accent: purple
|
||||
toggle:
|
||||
icon: material/brightness-4
|
||||
name: Light Mode
|
||||
features:
|
||||
- search.highlight
|
||||
- search.suggest
|
||||
- navigation.tabs
|
||||
- navigation.sections
|
||||
- navigation.expand
|
||||
- navigation.top
|
||||
- content.code.copy
|
||||
- toc.follow
|
||||
|
||||
plugins:
|
||||
- search:
|
||||
lang: de
|
||||
|
||||
markdown_extensions:
|
||||
- admonition
|
||||
- pymdownx.details
|
||||
- pymdownx.superfences:
|
||||
custom_fences:
|
||||
- name: mermaid
|
||||
class: mermaid
|
||||
format: !!python/name:pymdownx.superfences.fence_code_format
|
||||
- pymdownx.tabbed:
|
||||
alternate_style: true
|
||||
- pymdownx.highlight:
|
||||
anchor_linenums: true
|
||||
- pymdownx.inlinehilite
|
||||
- pymdownx.snippets
|
||||
- tables
|
||||
- attr_list
|
||||
- md_in_html
|
||||
- toc:
|
||||
permalink: true
|
||||
|
||||
nav:
|
||||
- Start: index.md
|
||||
- Services:
|
||||
- AI Compliance SDK:
|
||||
- Uebersicht: services/ai-compliance-sdk/index.md
|
||||
- Architektur: services/ai-compliance-sdk/ARCHITECTURE.md
|
||||
- Developer Guide: services/ai-compliance-sdk/DEVELOPER.md
|
||||
- Auditor Dokumentation: services/ai-compliance-sdk/AUDITOR_DOCUMENTATION.md
|
||||
- SBOM: services/ai-compliance-sdk/SBOM.md
|
||||
- Entwicklung:
|
||||
- Testing: development/testing.md
|
||||
- Dokumentation: development/documentation.md
|
||||
- CI/CD Pipeline: development/ci-cd-pipeline.md
|
||||
Reference in New Issue
Block a user