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
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)
|
||||
Reference in New Issue
Block a user