Benjamin_Boenisch/breakpilot-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update CLAUDE.md, MkDocs, nginx docs proxy, .claude/rules

Browse Source 
- CLAUDE.md: Comprehensive documentation for core infrastructure
- docs-src: Cleaned 316MB junk, kept only markdown docs
- mkdocs.yml: Updated nav for core-only content
- nginx: Docs proxy targets split (3002->lehrer, 3007->compliance)
- docker-compose: Fixed docs port mapping (8009:80), added INSTALL_LOCK
- .claude/rules: testing, documentation, open-source-policy, night-scheduler

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Benjamin Boenisch
2026-02-12 00:49:21 +01:00
parent ad111d5e69
commit 2498b0eb1f
54 changed files with 953 additions and 19290 deletions
Download Patch File Download Diff File Expand all files Collapse all files

293
.claude/CLAUDE.md
View File

@@ -1,65 +1,272 @@
# BreakPilot Core — Shared Infrastructure
# BreakPilot Core - Shared Infrastructure
## 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-core
# Einzelbefehle (BEVORZUGT):
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-core && <cmd>"
```
## Projektübersicht
---
**breakpilot-core** ist das Infrastruktur-Projekt der BreakPilot-Plattform. Es stellt alle gemeinsamen Services bereit, die von **breakpilot-lehrer** und **breakpilot-compliance** genutzt werden.
## Projekt-Kontext
### Enthaltene Services (~28 Container)
**breakpilot-core** ist das Infrastruktur-Fundament der BreakPilot-Plattform. Es stellt alle gemeinsamen Services bereit, die von **breakpilot-lehrer** und **breakpilot-compliance** genutzt werden.
| Service | Port | Beschreibung |
|---------|------|--------------|
| nginx | 80/443 | Reverse Proxy (SSL) |
| postgres | 5432 | PostGIS 16 (3 Schemas: core, lehrer, compliance) |
| valkey | 6379 | Session-Cache |
| vault | 8200 | Secrets Management |
| qdrant | 6333 | Vektordatenbank |
| minio | 9000 | S3 Storage |
| backend-core | 8000 | Shared APIs (Auth, RBAC, Notifications) |
| rag-service | 8097 | RAG: Dokumente, Suche, Embeddings |
| embedding-service | 8087 | Text-Embeddings |
| consent-service | 8081 | Consent-Management |
| health-aggregator | 8099 | Health-Check aller Services |
| gitea | 3003 | Git-Server |
| woodpecker | 8090 | CI/CD |
| camunda | 8089 | BPMN |
| synapse | 8008 | Matrix Chat |
| jitsi | 8443 | Video |
| mailpit | 8025 | E-Mail (Dev) |
### 3-Projekt-Architektur
### Docker-Netzwerk
Alle 3 Projekte teilen sich das `breakpilot-network`:
```
breakpilot-core (dieses Repo — MUSS ZUERST starten)
├── breakpilot-lehrer (haengt von Core ab)
└── breakpilot-compliance (haengt von Core ab)
```
Alle 3 Projekte teilen sich ein Docker-Netzwerk:
```yaml
networks:
breakpilot-network:
driver: bridge
name: breakpilot-network
name: breakpilot-network # Fixer Name, kein Auto-Prefix!
```
### Start-Reihenfolge
---
## Haupt-URLs (via Nginx Reverse Proxy)
### Core-eigene Services
| URL | Service | Beschreibung |
|-----|---------|--------------|
| https://macmini:8000/ | backend-core | Shared APIs (Auth, RBAC, Notifications) |
| https://macmini:8097/ | rag-service | Semantische Suche, Dokument-Upload |
| https://macmini:8443/ | Jitsi Meet | Videokonferenzen |
| http://macmini:8099/ | health-aggregator | Health-Check aller Services |
### Interne Dienste (kein HTTPS)
| URL | Service | Beschreibung |
|-----|---------|--------------|
| http://macmini:3003/ | Gitea | Git-Server (User: pilotadmin) |
| http://macmini:8090/ | Woodpecker CI | CI/CD Server |
| http://macmini:8200/ | Vault | Secrets Management |
| http://macmini:8025/ | Mailpit | E-Mail (Dev) |
| http://macmini:9001/ | MinIO Console | S3 Storage UI |
| http://macmini:8096/ | Night Scheduler | Auto-Shutdown/Startup |
| http://macmini:8089/ | Camunda | BPMN Engine |
### Nginx-Proxy fuer Lehrer/Compliance (durchgereicht)
| URL | Projekt | Service |
|-----|---------|---------|
| https://macmini/ | Lehrer | Studio v2 |
| https://macmini:3000/ | Lehrer | Website |
| https://macmini:3002/ | Lehrer | Admin Lehrer |
| https://macmini:3007/ | Compliance | Admin Compliance |
| https://macmini:8001/ | Lehrer | Backend Lehrer |
| https://macmini:8002/ | Compliance | Backend Compliance |
| https://macmini:8086/ | Lehrer | Klausur-Service |
| https://macmini:8093/ | Compliance | AI Compliance SDK |
---
## Services (~28 Container)
### Infrastruktur
| Service | Tech | Port | Container |
|---------|------|------|-----------|
| nginx | Nginx | 80/443 + viele | bp-core-nginx |
| postgres | PostGIS 16 | 5432 | bp-core-postgres |
| valkey | Valkey 8 | 6379 | bp-core-valkey |
| vault | HashiCorp Vault | 8200 | bp-core-vault |
| vault-agent | Vault | - | bp-core-vault-agent |
| qdrant | Qdrant | 6333/6334 | bp-core-qdrant |
| minio | MinIO | 9000/9001 | bp-core-minio |
| mailpit | Mailpit | 8025/1025 | bp-core-mailpit |
### Shared Backend-Services
| Service | Tech | Port | Container |
|---------|------|------|-----------|
| backend-core | Python/FastAPI | 8000 | bp-core-backend |
| rag-service | Python/FastAPI | 8097 | bp-core-rag-service |
| embedding-service | Python/FastAPI | 8087 | bp-core-embedding-service |
| consent-service | Go/Gin | 8081 | bp-core-consent-service |
| billing-service | Go | 8083 | bp-core-billing-service |
| health-aggregator | Python/FastAPI | 8099 | bp-core-health |
| night-scheduler | Python/FastAPI | 8096 | bp-core-night-scheduler |
### Kommunikation
| Service | Tech | Container |
|---------|------|-----------|
| jitsi-web | Jitsi | bp-core-jitsi-web |
| jitsi-xmpp | Prosody | bp-core-jitsi-xmpp |
| jitsi-jicofo | Jicofo | bp-core-jitsi-jicofo |
| jitsi-jvb | JVB | bp-core-jitsi-jvb |
| synapse + synapse-db | Matrix | bp-core-synapse (Profil: chat) |
### DevOps
| Service | Tech | Port | Container |
|---------|------|------|-----------|
| gitea | Gitea | 3003 | bp-core-gitea |
| gitea-runner | Gitea Actions | - | bp-core-gitea-runner |
| woodpecker-server | Woodpecker | 8090 | bp-core-woodpecker-server |
| woodpecker-agent | Woodpecker | - | bp-core-woodpecker-agent |
| camunda | Camunda | 8089 | bp-core-camunda (Profil: bpmn) |
### Profile (nur bei Bedarf starten)
| Profil | Services | Start mit |
|--------|----------|-----------|
| chat | synapse, synapse-db | `--profile chat` |
| erp | erpnext-* (7 Container) | `--profile erp` |
| bpmn | camunda | `--profile bpmn` |
| docs | docs (MkDocs) | `--profile docs` |
| backup | pg-backup | `--profile backup` |
---
## Datenbank
### 3 Schemas (shared PostgreSQL)
| Schema | Projekt | Tabellen |
|--------|---------|----------|
| `core` | Core | users, sessions, auth, rbac, notifications, email_templates, billing |
| `lehrer` | Lehrer | classroom, units, klausuren, vocab, game, meetings, messenger |
| `compliance` | Compliance | compliance_*, dsr, gdpr, sdk_tenants, consent_admin |
```bash
# 1. Core MUSS zuerst starten
docker compose up -d
# 2. Dann Lehrer und Compliance (warten auf Core Health)
# DB-Zugang
ssh macmini "docker exec bp-core-postgres psql -U breakpilot -d breakpilot_db"
```
### DB-Schemas
- `core` — users, sessions, auth, rbac, notifications
- `lehrer` — classroom, units, klausuren, game
- `compliance` — compliance, dsr, gdpr, sdk
---
## Git Remotes
Immer zu BEIDEN pushen:
- `origin`: lokale Gitea (macmini:3003)
- `gitea`: gitea.meghsakha.com
## Verzeichnisstruktur
```
breakpilot-core/
├── .claude/
│ ├── CLAUDE.md # Diese Datei
│ └── rules/ # Automatische Regeln
├── backend-core/ # Python/FastAPI (Auth, RBAC, Notifications)
├── rag-service/ # Python/FastAPI (Qdrant, MinIO, Embeddings)
├── embedding-service/ # Python/FastAPI (Sentence-Transformers)
├── consent-service/ # Go/Gin (Consent-Management)
├── billing-service/ # Go (Abrechnungsservice)
├── night-scheduler/ # Python/FastAPI (Auto-Shutdown)
├── nginx/conf.d/ # Nginx Reverse Proxy Config
├── vault/ # Vault Config + TLS Certs
├── gitea/ # Gitea Config
├── docs-src/ # MkDocs Quellen
├── mkdocs.yml # MkDocs Config
├── scripts/ # Helper Scripts
└── docker-compose.yml # Haupt-Compose (28+ Services)
```
---
## Haeufige Befehle
### Docker
```bash
# Alle Core-Services starten
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-core && /usr/local/bin/docker compose up -d"
# Einzelnen Service neu bauen
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-core && /usr/local/bin/docker compose build --no-cache <service>"
# Logs
ssh macmini "/usr/local/bin/docker logs -f bp-core-<service>"
# Status
ssh macmini "/usr/local/bin/docker ps --filter name=bp-core"
```
**WICHTIG:** Docker-Pfad auf Mac Mini ist `/usr/local/bin/docker` (nicht im Standard-SSH-PATH).
### Alle 3 Projekte starten
```bash
# 1. Core (MUSS zuerst!)
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-core && /usr/local/bin/docker compose up -d"
# Warten auf Health:
ssh macmini "curl -sf http://127.0.0.1:8099/health"
# 2. Lehrer
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-lehrer && /usr/local/bin/docker compose up -d"
# 3. Compliance
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-compliance && /usr/local/bin/docker compose up -d"
```
### Git
```bash
# Zu BEIDEN Remotes pushen (PFLICHT!):
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-core && 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. Testing & Dokumentation
- Tests sind Pflicht bei jeder Aenderung
- MkDocs aktualisieren: `--profile docs` starten
### 3. Sensitive Dateien
**NIEMALS aendern oder committen:**
- `.env`, `.env.local`, Vault-Tokens, SSL-Zertifikate
- `*.pdf`, `*.docx`, kompilierte Binaries, grosse Medien
---
## Nginx Port-Zuordnung (Uebersicht)
| Port | Ziel-Container | Projekt |
|------|----------------|---------|
| 443 | bp-lehrer-studio-v2 | Lehrer |
| 3000 | bp-lehrer-website | Lehrer |
| 3002 | bp-lehrer-admin | Lehrer |
| 3006 | bp-compliance-developer-portal | Compliance |
| 3007 | bp-compliance-admin | Compliance |
| 8000 | bp-core-backend | Core |
| 8001 | bp-lehrer-backend | Lehrer |
| 8002 | bp-compliance-backend | Compliance |
| 8086 | bp-lehrer-klausur-service | Lehrer |
| 8087 | bp-core-embedding-service | Core |
| 8089 | bp-core-camunda | Core |
| 8091 | bp-lehrer-voice-service | Lehrer |
| 8093 | bp-compliance-ai-sdk | Compliance |
| 8097 | bp-core-rag-service | Core |
| 8443 | bp-core-jitsi-web | Core |

91
.claude/rules/documentation.md Normal file
View 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)

297
.claude/rules/night-scheduler.md Normal file
View File

@@ -0,0 +1,297 @@
# Night Scheduler - Entwicklerdokumentation
**Status:** Produktiv
**Letzte Aktualisierung:** 2026-02-09
**URL:** https://macmini:3002/infrastructure/night-mode
**API:** http://macmini:8096
---
## Uebersicht
Der Night Scheduler ermoeglicht die automatische Nachtabschaltung der Docker-Services:
- Zeitgesteuerte Abschaltung (Standard: 22:00)
- Zeitgesteuerter Start (Standard: 06:00)
- Manuelle Sofortaktionen (Start/Stop)
- Dashboard-UI zur Konfiguration
---
## Architektur
```
┌─────────────────────────────────────────────────────────────┐
│ Admin Dashboard (Port 3002) │
│ /infrastructure/night-mode │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ API Proxy: /api/admin/night-mode │
│ - GET: Status abrufen │
│ - POST: Konfiguration speichern │
│ - POST /execute: Sofortaktion (start/stop) │
│ - GET /services: Service-Liste │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ night-scheduler (Port 8096) │
│ - Python/FastAPI Container │
│ - Prueft jede Minute ob Aktion faellig │
│ - Fuehrt docker compose start/stop aus │
│ - Speichert Config in /config/night-mode.json │
└─────────────────────────────────────────────────────────────┘
```
---
## Dateien
| Pfad | Beschreibung |
|------|--------------|
| `night-scheduler/scheduler.py` | Python Scheduler mit FastAPI |
| `night-scheduler/Dockerfile` | Container mit Docker CLI |
| `night-scheduler/requirements.txt` | Dependencies |
| `night-scheduler/config/night-mode.json` | Konfigurationsdatei |
| `night-scheduler/tests/test_scheduler.py` | Unit Tests |
| `admin-v2/app/api/admin/night-mode/route.ts` | API Proxy |
| `admin-v2/app/api/admin/night-mode/execute/route.ts` | Execute Endpoint |
| `admin-v2/app/api/admin/night-mode/services/route.ts` | Services Endpoint |
| `admin-v2/app/(admin)/infrastructure/night-mode/page.tsx` | UI Seite |
---
## API Endpoints
### GET /api/night-mode
Status und Konfiguration abrufen.
**Response:**
```json
{
"config": {
"enabled": true,
"shutdown_time": "22:00",
"startup_time": "06:00",
"last_action": "startup",
"last_action_time": "2026-02-09T06:00:00",
"excluded_services": ["night-scheduler", "nginx"]
},
"current_time": "14:30:00",
"next_action": "shutdown",
"next_action_time": "22:00",
"time_until_next_action": "7h 30min",
"services_status": {
"backend": "running",
"postgres": "running"
}
}
```
### POST /api/night-mode
Konfiguration aktualisieren.
**Request:**
```json
{
"enabled": true,
"shutdown_time": "23:00",
"startup_time": "07:00",
"excluded_services": ["night-scheduler", "nginx", "vault"]
}
```
### POST /api/night-mode/execute
Sofortige Aktion ausfuehren.
**Request:**
```json
{
"action": "stop" // oder "start"
}
```
**Response:**
```json
{
"success": true,
"message": "Aktion 'stop' erfolgreich ausgefuehrt fuer 25 Services"
}
```
### GET /api/night-mode/services
Liste aller Services abrufen.
**Response:**
```json
{
"all_services": ["backend", "postgres", "valkey", ...],
"excluded_services": ["night-scheduler", "nginx"],
"status": {
"backend": "running",
"postgres": "running"
}
}
```
---
## Konfiguration
### Config-Format (night-mode.json)
```json
{
"enabled": true,
"shutdown_time": "22:00",
"startup_time": "06:00",
"last_action": "startup",
"last_action_time": "2026-02-09T06:00:00",
"excluded_services": ["night-scheduler", "nginx"]
}
```
### Umgebungsvariablen
| Variable | Default | Beschreibung |
|----------|---------|--------------|
| `COMPOSE_PROJECT_NAME` | `breakpilot-pwa` | Docker Compose Projektname |
---
## Ausgeschlossene Services
Diese Services werden NICHT gestoppt:
1. **night-scheduler** - Muss laufen, um Services zu starten
2. **nginx** - Optional, fuer HTTPS-Zugriff
Weitere Services koennen ueber die Konfiguration ausgeschlossen werden.
---
## Docker Compose Integration
```yaml
night-scheduler:
build: ./night-scheduler
container_name: breakpilot-pwa-night-scheduler
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- ./night-scheduler/config:/config
- ./docker-compose.yml:/app/docker-compose.yml:ro
environment:
- COMPOSE_PROJECT_NAME=breakpilot-pwa
ports:
- "8096:8096"
networks:
- breakpilot-pwa-network
restart: unless-stopped
```
---
## Tests ausfuehren
```bash
# Im Container
docker exec -it breakpilot-pwa-night-scheduler pytest -v
# Lokal (mit Dependencies)
cd night-scheduler
pip install -r requirements.txt
pytest -v tests/
```
---
## Deployment
```bash
# 1. Dateien synchronisieren
rsync -avz night-scheduler/ macmini:.../night-scheduler/
# 2. Container bauen
ssh macmini "docker compose -f .../docker-compose.yml build --no-cache night-scheduler"
# 3. Container starten
ssh macmini "docker compose -f .../docker-compose.yml up -d night-scheduler"
# 4. Testen
curl http://macmini:8096/health
curl http://macmini:8096/api/night-mode
```
---
## Troubleshooting
### Problem: Services werden nicht gestoppt/gestartet
1. Pruefen ob Docker Socket gemountet ist:
```bash
docker exec breakpilot-pwa-night-scheduler ls -la /var/run/docker.sock
```
2. Pruefen ob docker compose CLI verfuegbar ist:
```bash
docker exec breakpilot-pwa-night-scheduler docker compose version
```
3. Logs pruefen:
```bash
docker logs breakpilot-pwa-night-scheduler
```
### Problem: Konfiguration wird nicht gespeichert
1. Pruefen ob /config beschreibbar ist:
```bash
docker exec breakpilot-pwa-night-scheduler touch /config/test
```
2. Volume-Mount pruefen in docker-compose.yml
### Problem: API nicht erreichbar
1. Container-Status pruefen:
```bash
docker ps | grep night-scheduler
```
2. Health-Check pruefen:
```bash
curl http://localhost:8096/health
```
---
## Sicherheitshinweise
- Der Container benoetigt Zugriff auf den Docker Socket
- Nur interne Services koennen gestoppt/gestartet werden
- Keine Authentifizierung (internes Netzwerk)
- Keine sensitiven Daten in der Konfiguration
---
## Dependencies (SBOM)
| Package | Version | Lizenz |
|---------|---------|--------|
| FastAPI | 0.109.0 | MIT |
| Uvicorn | 0.27.0 | BSD-3-Clause |
| Pydantic | 2.5.3 | MIT |
| pytest | 8.0.0 | MIT |
| pytest-asyncio | 0.23.0 | Apache-2.0 |
| httpx | 0.26.0 | BSD-3-Clause |
---
## Aenderungshistorie
| Datum | Aenderung |
|-------|-----------|
| 2026-02-09 | Initiale Implementierung |

99
.claude/rules/open-source-policy.md Normal file
View 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
View 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)