Add CLAUDE.md, MkDocs docs, .claude/rules
- CLAUDE.md: Comprehensive documentation for Lehrer KI platform - docs-src: Klausur, Voice, Agent-Core, KI-Pipeline docs - mkdocs.yml: Lehrer-specific nav with blue theme - docker-compose: Added docs service (port 8010, profile: docs) - .claude/rules: testing, docs, open-source, abiturkorrektur, vocab-worksheet, multi-agent, experimental-dashboard Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Benjamin Boenisch
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))
|
||||
Reference in New Issue
Block a user