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

feat(claude): Add comprehensive project context and development rules

Browse Source 
- CLAUDE.md: Complete project context with SSH connection, 49 services,
  all URLs (including SDK modules), tech stack, and core principles
- open-source-policy.md: License whitelist, SBOM workflow, dependency checks
- compliance-checklist.md: DSGVO/AI Act checklists, 5-question quick check
- debug-framework.md: 6-phase systematic debugging with Breakpilot-specific commands

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
BreakPilot Dev
2026-02-08 23:38:37 -08:00
parent 1e68ccd4d0
commit f28244753f
4 changed files with 853 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

376
.claude/CLAUDE.md Normal file
View File

@@ -0,0 +1,376 @@
# BreakPilot PWA - Projekt-Kontext für Claude
## SSH-Verbindung (WICHTIG - IMMER ZUERST LESEN)
```bash
# Verbindung zum Mac Mini im lokalen Netzwerk
ssh macmini
# Projektverzeichnis
cd /Users/benjaminadmin/Projekte/breakpilot-pwa
# Oder direkt:
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-pwa && <befehl>"
```
**Hostname:** `macmini` (im lokalen Netzwerk via Bonjour)
**User:** `benjaminadmin`
**Projekt:** `/Users/benjaminadmin/Projekte/breakpilot-pwa`
---
## Kernprinzipien (IMMER BEACHTEN)
### 1. Open Source Policy
- **NUR Open Source mit kommerziell nutzbarer Lizenz verwenden**
- Erlaubte Lizenzen: MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, MPL-2.0, LGPL
- **VERBOTEN:** GPL (außer LGPL), AGPL, proprietäre Software, "free for non-commercial use"
- **Bei jeder neuen Dependency:** SBOM aktualisieren unter https://macmini:3002/infrastructure/sbom
### 2. Testing & Dokumentation
- **Tests sind Pflicht:** Unit Tests, Integration Tests für jede Änderung
- **Dokumentation aktualisieren:** https://macmini:3002/development/docs (MKDocs)
- Siehe `@.claude/rules/testing.md` und `@.claude/rules/documentation.md`
### 3. Architektur & Visualisierung aktualisieren
Nach größeren Änderungen diese Dashboards aktualisieren:
- **Architektur:** https://macmini:3002/architecture
- **Screenflows:** https://macmini:3002/development/screen-flow
- **Dashboard:** https://macmini:3002/dashboard
- **Security Tools:** https://macmini:3002/infrastructure/security
### 4. CI/CD Pipeline
Alle Security-Tools müssen nach der Pipeline durchlaufen:
- Trivy (Container-Scanning)
- Semgrep (SAST)
- Gitleaks (Secret-Detection)
- SBOM-Generierung
---
## Projektübersicht
**Projektname:** BreakPilot PWA
**Typ:** DSGVO-konforme EdTech-Plattform für den DACH-Raum
**Architektur:** Microservices mit Docker Compose
**Plattform:** Mac Mini M2 (Apple Silicon / ARM64)
---
## Haupt-URLs (HTTPS via Nginx)
| URL | Service | Beschreibung |
|-----|---------|--------------|
| https://macmini/ | Studio v2 | Lehrer-/Schüler-Interface |
| https://macmini:3000/ | Website | Öffentliche Website |
| https://macmini:3002/ | Admin v2 | **Admin-Dashboard (Hauptzugang)** |
| https://macmini:8000/ | Backend API | FastAPI Backend |
| https://macmini:8086/ | Klausur Service | Prüfungs-/Klausurservice |
| https://macmini:8443/ | Jitsi Meet | Videokonferenzen |
| wss://macmini:8091/ | Voice Service | Spracheingabe WebSocket |
### AI Compliance SDK (DSGVO-Tools)
| URL | Modul | Beschreibung |
|-----|-------|--------------|
| https://macmini:3002/sdk | SDK Admin | Haupt-SDK mit allen Modulen |
| https://macmini:3002/sdk/tom | TOM | Technisch-Organisatorische Maßnahmen |
| https://macmini:3002/sdk/dsfa | DSFA | Datenschutz-Folgenabschätzung |
| https://macmini:3002/sdk/vvt | VVT | Verzeichnis von Verarbeitungstätigkeiten |
| https://macmini:3002/sdk/loeschfristen | Löschfristen | Löschfristen-Verwaltung |
| https://macmini:3002/developers | Developer Portal | API-Dokumentation für Kunden |
| https://macmini:8093/ | SDK API | Backend-API für SDK |
### Interne Dienste
| URL | Service |
|-----|---------|
| http://macmini:8200/ | Vault UI (Secrets) |
| http://macmini:8025/ | Mailpit (E-Mail Dev) |
| http://macmini:9001/ | MinIO Console (S3) |
| http://macmini:3003/ | Gitea (Git-Server) |
| http://macmini:8090/ | Woodpecker CI |
| http://macmini:8089/ | Camunda (BPMN) |
| http://macmini:8009/ | MkDocs (Projekt-Doku) |
### Studio URLs
| URL | Beschreibung |
|-----|--------------|
| https://macmini/korrektur | Lehrer-Korrekturplattform |
| https://macmini:8000/app | Dashboard (alte Version) |
---
| http://macmini:8200/ | Vault UI (Secrets) |
| http://macmini:8025/ | Mailpit (E-Mail Dev) |
| http://macmini:9001/ | MinIO Console (S3) |
| http://macmini:3003/ | Gitea (Git-Server) |
| http://macmini:8090/ | Woodpecker CI |
| http://macmini:8089/ | Camunda (BPMN) |
---
## Services (49 Container)
### Kern-Applikationen
| Service | Tech | Port | Beschreibung |
|---------|------|------|--------------|
| `studio-v2` | Next.js | 443 | Lehrer-/Schüler-Studio |
| `admin-v2` | Next.js | 3002 | Admin-Dashboard |
| `website` | Next.js | 3000 | Öffentliche Website |
| `backend` | Python/FastAPI | 8000 | API Backend |
| `consent-service` | Go/Gin | 8081 | Consent-Management |
### Bildungs-Services
| Service | Tech | Port | Beschreibung |
|---------|------|------|--------------|
| `klausur-service` | Python/FastAPI | 8086 | Prüfungen, OCR, RAG |
| `school-service` | Python | 8082 | Schulverwaltung |
| `edu-search-service` | Python | 8088 | Bildungssuche |
| `breakpilot-drive` | Node.js | 8087 | Dateiablage (IPFS) |
| `geo-service` | Python | 8084 | Geo-Daten (PostGIS) |
| `voice-service` | Python | 8091 | Spracheingabe |
### KI & Compliance
| Service | Tech | Port | Beschreibung |
|---------|------|------|--------------|
| `ai-compliance-sdk` | Python | 8093 | DSGVO-konforme KI-Nutzung |
| `embedding-service` | Python | 8083 | Text-Embeddings |
| `paddleocr-service` | Python | - | OCR für Dokumente |
| `transcription-worker` | Python | - | Audio-Transkription |
### Kommunikation
| Service | Tech | Port | Beschreibung |
|---------|------|------|--------------|
| `jitsi-web` | Jitsi | 8443 | Videokonferenzen |
| `jitsi-xmpp` | Prosody | - | XMPP Server |
| `jitsi-jicofo` | Jicofo | - | Konferenz-Fokus |
| `jitsi-jvb` | JVB | 8080 | Video Bridge |
| `jibri` | Jibri | - | Aufnahme/Streaming |
| `synapse` | Matrix | 8008 | Chat-Server |
### Datenbanken & Storage
| Service | Tech | Port | Beschreibung |
|---------|------|------|--------------|
| `postgres` | PostGIS 16 | 5432 | Hauptdatenbank |
| `valkey` | Valkey 8 | 6379 | Session-Cache (Redis-Fork) |
| `qdrant` | Qdrant | 6333/6334 | Vektordatenbank |
| `minio` | MinIO | 9000/9001 | S3-kompatibler Storage |
### Infrastructure & DevOps
| Service | Tech | Port | Beschreibung |
|---------|------|------|--------------|
| `nginx` | Nginx | 80/443 | Reverse Proxy + TLS |
| `vault` | HashiCorp Vault | 8200 | Secrets Management |
| `vault-agent` | Vault | - | Zertifikatserneuerung |
| `gitea` | Gitea | 3003 | Git-Server |
| `woodpecker-server` | Woodpecker | 8090 | CI/CD Server |
| `woodpecker-agent` | Woodpecker | - | CI/CD Agent |
| `night-scheduler` | Python/FastAPI | 8096 | Auto-Shutdown/Startup |
| `mailpit` | Mailpit | 8025/1025 | E-Mail (Dev) |
### ERP & Billing
| Service | Tech | Port | Beschreibung |
|---------|------|------|--------------|
| `erpnext-frontend` | ERPNext | 8009 | ERP Frontend |
| `erpnext-backend` | ERPNext | - | ERP Backend |
| `erpnext-db` | MariaDB | - | ERP Datenbank |
| `billing-service` | Python | - | Abrechnungsservice |
### DSMS (Data Sharing)
| Service | Tech | Port | Beschreibung |
|---------|------|------|--------------|
| `dsms-node` | Node.js | 4001/5001 | IPFS Node |
| `dsms-gateway` | Node.js | 8085 | IPFS Gateway |
### Prozesse
| Service | Tech | Port | Beschreibung |
|---------|------|------|--------------|
| `camunda` | Camunda | 8089 | BPMN Engine |
---
## Tech-Stack nach Sprache
### Go
- `consent-service`: Gin, GORM, JWT
### Python
- `backend`: FastAPI, SQLAlchemy, Pydantic
- `klausur-service`: FastAPI, PaddleOCR, RAG
- `ai-compliance-sdk`: FastAPI, Langfuse
- `embedding-service`: FastAPI, Sentence-Transformers
- `voice-service`: FastAPI, Whisper
- `geo-service`: FastAPI, PostGIS
- `school-service`: FastAPI
- `night-scheduler`: FastAPI
### TypeScript/Next.js
- `studio-v2`: Next.js 14, React, TailwindCSS
- `admin-v2`: Next.js 14, React, TailwindCSS, shadcn/ui
- `website`: Next.js 14
### Node.js
- `breakpilot-drive`: Express, IPFS
- `dsms-node`: IPFS
- `dsms-gateway`: Express
---
## Verzeichnisstruktur
```
breakpilot-pwa/
├── .claude/ # Claude-Konfiguration
│ ├── CLAUDE.md # Diese Datei
│ ├── rules/ # Automatische Regeln
│ │ ├── testing.md
│ │ ├── documentation.md
│ │ └── night-scheduler.md
│ └── settings.json
├── admin-v2/ # Admin Dashboard (Next.js)
├── studio-v2/ # Lehrer-/Schüler-Studio (Next.js)
├── website/ # Öffentliche Website (Next.js)
├── backend/ # Python Backend (FastAPI)
├── consent-service/ # Go Consent Service
├── klausur-service/ # Klausur/OCR Service
├── ai-compliance-sdk/ # KI-Compliance SDK
├── voice-service/ # Spracheingabe
├── geo-service/ # Geo-Daten
├── school-service/ # Schulverwaltung
├── edu-search-service/ # Bildungssuche
├── breakpilot-drive/ # Dateiablage
├── night-scheduler/ # Auto-Shutdown
├── nginx/ # Reverse Proxy Config
├── vault/ # Vault Config
├── docs-src/ # MKDocs Quellen
├── docs-site/ # MKDocs Build
├── docker-compose.yml # Haupt-Docker-Config
└── mkdocs.yml # MKDocs Config
```
---
## Dokumentation (MKDocs)
**Live-URL:** https://macmini:3002/development/docs
**Quellen:** `/docs-src/`
**Build:** `/docs-site/`
**Config:** `mkdocs.yml`
### Dokumentation bearbeiten
```bash
# MKDocs lokal starten (Live-Reload)
cd /Users/benjaminadmin/Projekte/breakpilot-pwa
mkdocs serve -a 0.0.0.0:8008
# Build
mkdocs build
```
### Struktur
- `docs-src/index.md` - Startseite
- `docs-src/architecture/` - Architektur-Docs
- `docs-src/services/` - Service-Dokumentation
- `docs-src/api/` - API-Dokumentation
- `docs-src/development/` - Entwickler-Guides
---
## Häufige Befehle
### Docker
```bash
# Alle Services starten
docker compose up -d
# Einzelnen Service neu bauen
docker compose build --no-cache <service-name>
docker compose up -d <service-name>
# Logs anzeigen
docker compose logs -f <service-name>
# Status aller Container
docker compose ps
```
### Tests
```bash
# Go Tests (Consent Service)
cd consent-service && go test -v ./...
# Python Tests
cd backend && source venv/bin/activate && pytest -v
# Mit Coverage
pytest --cov=. --cov-report=html
```
### Git (via Gitea)
```bash
# Remote ist localhost weil Gitea im Container läuft
git remote -v
# origin http://localhost:3003/pilotadmin/breakpilot-pwa.git
```
---
## Rollen & Berechtigungen
| Rolle | Beschreibung |
|-------|--------------|
| `user` | Normaler Benutzer (Schüler/Lehrer) |
| `admin` | Administrator |
| `data_protection_officer` | Datenschutzbeauftragter |
| `school_admin` | Schuladministrator |
---
## Compliance & Sicherheit
### DSGVO
- Consent-Management via `consent-service`
- Datenexport-Funktionen
- Löschkonzept implementiert
### AI Act
- `ai-compliance-sdk` für konforme KI-Nutzung
- Risikobewertung für KI-Funktionen
- Audit-Logging
### BSI
- BSI-TR-03161 Dokumentation vorhanden
- Security-Scanning in CI/CD
---
## Sensitive Dateien
**NIEMALS ändern oder committen:**
- `.env`, `.env.local`, `.env.backup`
- `secrets/`
- Vault-Tokens
- SSL-Zertifikate
---
## Ansprechpartner
- **Git-Server:** http://macmini:3003 (Gitea)
- **CI/CD:** http://macmini:8090 (Woodpecker)
- **Issue-Tracker:** Gitea Issues

141
.claude/rules/compliance-checklist.md Normal file
View 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.

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

237
.claude/skills/debug-framework.md Normal file
View File

@@ -0,0 +1,237 @@
# Systematisches Debug-Framework
## Trigger
Dieses Skill aktivieren bei:
- Fehlermeldungen / Exceptions
- Unerwartetes Verhalten
- Performance-Probleme
- "Es funktioniert nicht"
---
## Phase 1: Reproduzieren (5 min max)
### Ziel: Bug in einen Test verwandeln
```bash
# 1. Exakte Schritte dokumentieren
# 2. Fehlermeldung/Symptom notieren
# 3. Umgebung identifizieren
```
**Fragen:**
- [ ] Ist der Bug reproduzierbar?
- [ ] Tritt er nur in bestimmten Umgebungen auf?
- [ ] Seit wann tritt er auf? (letzter Deploy?)
### Breakpilot-spezifisch: Welcher Service?
```bash
# Container-Status prüfen
ssh macmini "docker compose ps | grep -E '(Exit|unhealthy)'"
# Logs der letzten 5 Minuten
ssh macmini "docker compose logs --since 5m <service-name>"
```
| Symptom | Wahrscheinlicher Service |
|---------|-------------------------|
| Login fehlgeschlagen | consent-service, backend |
| 502 Bad Gateway | nginx, upstream-service |
| Langsame Suche | qdrant, embedding-service |
| Upload-Fehler | minio, backend |
| OCR-Fehler | paddleocr-service, klausur-service |
---
## Phase 2: Hypothesen bilden (5 min max)
### 3-5 mögliche Ursachen auflisten
| # | Hypothese | Wahrscheinlichkeit | Test |
|---|-----------|-------------------|------|
| 1 | | Hoch/Mittel/Niedrig | |
| 2 | | | |
| 3 | | | |
### Häufige Ursachen bei Breakpilot
**Container/Docker:**
- Container nicht gestartet
- Volume-Mount-Problem
- Netzwerk zwischen Containern unterbrochen
- Resource-Limits erreicht
**Datenbank:**
- Connection Pool erschöpft
- Migration nicht ausgeführt
- Deadlock
**API/Backend:**
- JWT abgelaufen
- CORS-Fehler
- Rate-Limit erreicht
- Falscher Content-Type
**Frontend:**
- Cache-Problem (Safari!)
- Build nicht aktualisiert
- Umgebungsvariable fehlt
---
## Phase 3: Systematisch eliminieren (10 min max)
### Reihenfolge: Schnellste Tests zuerst
```bash
# 1. Ist der Service überhaupt erreichbar?
curl -s https://macmini:8000/health | jq
# 2. Container-Logs auf Fehler prüfen
ssh macmini "docker compose logs --tail 50 <service> 2>&1 | grep -iE '(error|exception|failed|traceback)'"
# 3. Datenbank-Verbindung testen
ssh macmini "docker exec breakpilot-pwa-postgres pg_isready"
# 4. Redis/Valkey erreichbar?
ssh macmini "docker exec breakpilot-pwa-valkey valkey-cli ping"
```
### Hypothese testen
Für jede Hypothese:
1. **Test definieren** (wie prüfen wir das?)
2. **Test ausführen**
3. **Ergebnis:** Bestätigt ✅ / Widerlegt ❌
---
## Phase 4: Root Cause identifizieren
### Nicht das Symptom behandeln!
**Schlecht:** "Ich starte den Container neu"
**Gut:** "Der Container crashed wegen OOM → Memory-Limit erhöhen"
### 5-Why-Methode
```
Problem: API gibt 500 zurück
↓ Warum?
Datenbank-Query failed
↓ Warum?
Connection Pool erschöpft
↓ Warum?
Connections werden nicht freigegeben
↓ Warum?
Exception vor connection.close()
↓ Warum?
Fehlendes try/finally
→ ROOT CAUSE: Fehlendes Resource-Cleanup
```
---
## Phase 5: Fix implementieren
### Checkliste vor dem Fix
- [ ] Root Cause verstanden (nicht nur Symptom)
- [ ] Fix adressiert Root Cause
- [ ] Keine Seiteneffekte erwartet
- [ ] Test geschrieben, der Regression verhindert
### Fix-Template
```python
# VORHER: Bug
def fetch_data():
conn = get_connection()
result = conn.query(...) # Exception hier → Leak!
conn.close()
return result
# NACHHER: Fix mit Erklärung
def fetch_data():
"""Fetch data with proper connection handling.
Fixed: Connection leak when query raises exception.
See: https://macmini:3003/.../issues/123
"""
conn = get_connection()
try:
result = conn.query(...)
return result
finally:
conn.close() # Immer ausgeführt
```
---
## Phase 6: Regression verhindern
### Test schreiben
```python
def test_connection_released_on_error():
"""Regression test for connection leak bug.
Issue: #123
Root cause: Missing finally block in fetch_data()
"""
initial_connections = get_pool_size()
with pytest.raises(DatabaseError):
fetch_data_with_bad_query()
# Connection should be returned to pool
assert get_pool_size() == initial_connections
```
### Dokumentieren
```bash
# Was haben wir gelernt?
# → docs-src/development/debugging-notes.md ergänzen
```
---
## Quick Reference: Breakpilot Debug Commands
```bash
# Alle Container-Status
ssh macmini "docker compose ps"
# Logs eines Services (live)
ssh macmini "docker compose logs -f <service>"
# In Container einloggen
ssh macmini "docker exec -it breakpilot-pwa-<service> sh"
# PostgreSQL Query
ssh macmini "docker exec breakpilot-pwa-postgres psql -U breakpilot -d breakpilot_db -c 'SELECT 1'"
# Netzwerk-Debug
ssh macmini "docker exec breakpilot-pwa-backend curl -s http://consent-service:8081/health"
# Resource-Nutzung
ssh macmini "docker stats --no-stream"
# Vault-Status
ssh macmini "docker exec breakpilot-pwa-vault vault status"
```
---
## Anti-Patterns vermeiden
| ❌ Nicht machen | ✅ Stattdessen |
|-----------------|----------------|
| Random Code ändern | Hypothese bilden, dann testen |
| console.log überall | Gezielt an verdächtigen Stellen |
| Container neustarten und hoffen | Root Cause finden |
| Stundenlang alleine debuggen | Nach 30 min Hilfe holen |
| Fix ohne Test | Immer Regression-Test schreiben |