From f28244753f8a3ff1acefcb9d6d4412a62663ed47 Mon Sep 17 00:00:00 2001 From: BreakPilot Dev Date: Sun, 8 Feb 2026 23:38:37 -0800 Subject: [PATCH] feat(claude): Add comprehensive project context and development rules - 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 --- .claude/CLAUDE.md | 376 ++++++++++++++++++++++++++ .claude/rules/compliance-checklist.md | 141 ++++++++++ .claude/rules/open-source-policy.md | 99 +++++++ .claude/skills/debug-framework.md | 237 ++++++++++++++++ 4 files changed, 853 insertions(+) create mode 100644 .claude/CLAUDE.md create mode 100644 .claude/rules/compliance-checklist.md create mode 100644 .claude/rules/open-source-policy.md create mode 100644 .claude/skills/debug-framework.md diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md new file mode 100644 index 0000000..c9872bd --- /dev/null +++ b/.claude/CLAUDE.md @@ -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 && " +``` + +**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 +docker compose up -d + +# Logs anzeigen +docker compose logs -f + +# 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 diff --git a/.claude/rules/compliance-checklist.md b/.claude/rules/compliance-checklist.md new file mode 100644 index 0000000..2b6cc2d --- /dev/null +++ b/.claude/rules/compliance-checklist.md @@ -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. diff --git a/.claude/rules/open-source-policy.md b/.claude/rules/open-source-policy.md new file mode 100644 index 0000000..af7001a --- /dev/null +++ b/.claude/rules/open-source-policy.md @@ -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 license + +# Python Package +pip show | grep License + +# Go Module +go-licenses check +``` + +### 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 diff --git a/.claude/skills/debug-framework.md b/.claude/skills/debug-framework.md new file mode 100644 index 0000000..3fe3dee --- /dev/null +++ b/.claude/skills/debug-framework.md @@ -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 " +``` + +| 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 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 " + +# In Container einloggen +ssh macmini "docker exec -it breakpilot-pwa- 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 |