[split-required] [guardrail-change] Enforce 500 LOC budget across all services

Install LOC guardrails (check-loc.sh, architecture.md, pre-commit hook) and split all 44 files exceeding 500 LOC into domain-focused modules: - consent-service (Go): models, handlers, services, database splits - backend-core (Python): security_api, rbac_api, pdf_service, auth splits - admin-core (TypeScript): 5 page.tsx + sidebar extractions - pitch-deck (TypeScript): 6 slides, 3 UI components, engine.ts splits - voice-service (Python): enhanced_task_orchestrator split Result: 0 violations, 36 exempted (pipeline, tests, pure-data files). Go build verified clean. No behavior changes — pure structural splits. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-27 00:09:30 +02:00
parent 5ef039a6bc
commit 92c86ec6ba
162 changed files with 23853 additions and 23034 deletions
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -27,6 +27,25 @@ git push origin main
 **NIEMALS** manuell in Orca auf "Redeploy" klicken — Gitea Actions triggert Orca automatisch.
 **IMMER auf `main` pushen** — sowohl origin als auch gitea.

+### TEMPORAER: Compliance-Repo Refactoring (Stand 2026-04-12)
+
+**Das Compliance-Repo wird aktuell auf Production (gitea) refakturiert.**
+
+- **Core + Lehrer:** Normal auf `main` pushen (origin + gitea) ✅
+- **Compliance auf Mac Mini (origin):** Normal auf `main` pushen ✅
+- **Compliance auf Production (gitea):** **NUR Feature Branches**, NICHT auf `main` pushen! ⚠️
+
+```bash
+# Compliance-Repo — RICHTIG:
+git push origin main                                    # Mac Mini OK
+git push gitea feature/mein-feature                     # Production: nur Feature Branch!
+
+# Compliance-Repo — FALSCH (waehrend Refactoring):
+# git push gitea main                                   # NICHT MACHEN!
+```
+
+**Nach Abschluss des Refactorings:** Gesamten Compliance-Code einmalig von Production auf Mac Mini uebernehmen. User sagt Bescheid wann es soweit ist.
+
 ### Post-Push Deploy-Monitoring (PFLICHT nach jedem Push auf gitea)

 **IMMER wenn Claude auf gitea pusht, MUSS danach automatisch das Deploy-Monitoring laufen:**
@@ -318,6 +337,46 @@ npx tsc --noEmit && npm run lint && npm run build

 ---

+## Code-Qualitaet Guardrails (NON-NEGOTIABLE)
+
+> Vollstaendige Details: `.claude/rules/architecture.md`
+> Ausnahmen: `.claude/rules/loc-exceptions.txt`
+
+### File Size Budget
+
+- **Hard Cap: 500 LOC** pro Datei
+- Wenn eine Aenderung eine Datei ueber 500 LOC bringen wuerde: **erst splitten, dann aendern**
+- Ausnahmen nur mit Begruendung in `loc-exceptions.txt` + `[guardrail-change]` Commit-Marker
+
+### Architektur
+
+- **Go:** Handler ≤40 LOC → Service-Layer → Repository-Pattern
+- **Python:** Routes duenn → Business Logic in Services → Persistenz in Repositories
+- **TypeScript/Next.js:** page.tsx duenn → _components/, _hooks/ auslagern
+
+### FINGER WEG (laufende RAG Pipeline)
+
+Diese Verzeichnisse duerfen NICHT refaktoriert werden:
+- `control-pipeline/` — RAG/Control-Extraction Pipeline
+- `rag-service/` — Semantische Suche
+- `embedding-service/` — Text-Embeddings
+- `voice-service/bqas/` — RAG Quality Assessment
+
+### LOC-Check ausfuehren
+
+```bash
+bash scripts/check-loc.sh --changed   # nur geaenderte Dateien
+bash scripts/check-loc.sh --all       # alle Dateien (zeigt alle Violations)
+```
+
+### Commit-Marker
+
+- `[split-required]` — Aenderung beginnt mit Datei-Split
+- `[guardrail-change]` — Aenderungen an .claude/**, scripts/check-loc.sh
+- `[interface-change]` — Public API Contracts geaendert
+
+---
+
 ## Kernprinzipien

 ### 1. Open Source Policy
--- a/.claude/rules/architecture.md
+++ b/.claude/rules/architecture.md
@@ -0,0 +1,79 @@
+# Architecture Rule — BreakPilot Core
+
+## File Size Budget
+
+Hard default: **500 LOC max** per file.
+Soft targets:
+- Handler/Router/Service: 300-400 LOC
+- Models/Schemas/Types: 200-300 LOC
+- Utilities: 100-200 LOC
+
+Ausnahmen nur in `.claude/rules/loc-exceptions.txt` mit Begruendung.
+
+## Split-Trigger
+
+Sofort splitten wenn:
+- Datei ueberschreitet 500 LOC
+- Datei wuerde nach Aenderung 500 LOC ueberschreiten
+- Datei mischt Transport + Business Logic + Persistence
+- Datei enthaelt mehrere unabhaengig testbare Verantwortlichkeiten
+
+## Go (consent-service, billing-service)
+
+- Handler duenn halten (≤40 LOC pro Handler-Funktion)
+- Business Logic in Services/Use-Cases
+- Transport/Request-Decoding getrennt von Domain-Logik
+- Dateien im gleichen Package teilen Typen automatisch — kein Re-Export noetig
+- Models nach Domain splitten (user, consent, school, document, etc.)
+
+## Python (backend-core, night-scheduler)
+
+- Routes duenn halten — Business Logic in Services
+- Persistenz in Repositories/Data-Access-Module
+- Pydantic Schemas nach Domain splitten
+- Zirkulaere Imports vermeiden
+
+## TypeScript / Next.js (admin-core, pitch-deck)
+
+- page.tsx duenn halten — Server Actions, Queries, Components auslagern
+- _components/ + _hooks/ Konvention fuer Route-lokale Extracts
+- .ts Dateien mit JSX muessen .tsx heissen (Turbopack!)
+- Monolithische types.ts frueh splitten
+- types.ts + types/ Shadowing vermeiden
+
+## Entscheidungsreihenfolge
+
+1. Bestehendes kleines kohaeesives Modul wiederverwenden
+2. Neues Modul in der Naehe erstellen
+3. Ueberfuellte Datei splitten, neues Verhalten in richtiges Split-Modul
+4. Nur als letzter Ausweg: Grosse bestehende Datei erweitern
+
+## FINGER WEG (laufende RAG Pipeline)
+
+Diese Verzeichnisse duerfen NICHT refaktoriert werden:
+- `control-pipeline/` — RAG/Control-Extraction Pipeline
+- `rag-service/` — Semantische Suche
+- `embedding-service/` — Text-Embeddings
+- `voice-service/bqas/` — RAG Quality Assessment
+
+## Workflow (bei jeder Aenderung)
+
+1. Datei lesen + LOC pruefen
+2. Wenn nahe am Budget → erst splitten
+3. Minimale kohaerente Aenderung
+4. Verifikation (Tests + Lint)
+5. Zusammenfassung: Was geaendert, was verifiziert, Restrisiko
+
+## LOC-Check ausfuehren
+
+```bash
+bash scripts/check-loc.sh --changed   # nur geaenderte Dateien
+bash scripts/check-loc.sh --all       # alle Dateien (zeigt alle Violations)
+```
+
+## Commit-Marker
+
+- `[split-required]` — Aenderung beginnt mit Datei-Split
+- `[guardrail-change]` — Aenderungen an .claude/**, scripts/check-loc.sh
+- `[interface-change]` — Public API Contracts geaendert
+- `[migration-approved]` — Schema-/Migrations-Aenderungen
--- a/.claude/rules/loc-exceptions.txt
+++ b/.claude/rules/loc-exceptions.txt
@@ -0,0 +1,35 @@
+# LOC Exceptions — BreakPilot Core
+# Format: <glob> | owner=<person> | reason=<why> | review=<date>
+#
+# Jede Ausnahme braucht Begruendung und Review-Datum.
+# Temporaere Ausnahmen muessen mit [guardrail-change] Commit-Marker versehen werden.
+
+# Generated / Build Artifacts
+**/node_modules/** | owner=infra | reason=npm packages | review=permanent
+**/.next/** | owner=infra | reason=Next.js build output | review=permanent
+**/__pycache__/** | owner=infra | reason=Python bytecode | review=permanent
+**/venv/** | owner=infra | reason=Python virtualenv | review=permanent
+
+# Test-Dateien (duerfen groesser sein fuer Table-Driven Tests)
+**/*test*.py | owner=all | reason=Tests mit Table-Driven Patterns duerfen groesser sein | review=permanent
+**/*test*.go | owner=all | reason=Go Tests mit Table-Driven Patterns | review=permanent
+**/*test*.ts | owner=all | reason=TypeScript Tests | review=permanent
+**/tests/** | owner=all | reason=Test-Verzeichnisse | review=permanent
+
+# FINGER WEG — Laufende RAG Pipeline (NICHT anfassen!)
+control-pipeline/** | owner=pipeline | reason=Laufende RAG Pipeline, parallele Jobs aktiv | review=permanent
+rag-service/** | owner=pipeline | reason=Semantische Suche, produktiv | review=permanent
+embedding-service/** | owner=pipeline | reason=Text-Embeddings, produktiv | review=permanent
+voice-service/bqas/** | owner=pipeline | reason=RAG Quality Assessment, produktiv | review=permanent
+
+# Seed/Helper Scripts (keine Service-Logik)
+scripts/seed-demo-and-screenshot.py | owner=infra | reason=Einmaliges Seed-Script, kein Service-Code | review=permanent
+pitch-deck/scripts/import-finanzplan.py | owner=pitch-deck | reason=583 LOC, einmaliges Excel-Import-Script (9 Sheet-Importer), hardcodierte Row/Col-Mappings fuer eine Finanzplan-.xlsm-Datei, keine wiederverwendbare Logik | review=2027-01
+
+# PDF Templates (reine statische HTML/CSS Strings, keine Logik)
+backend-core/services/pdf_templates.py | owner=all | reason=519 LOC, rein statische Jinja2-HTML-Templates + CSS, keine Logik | review=2026-07
+
+# Pitch Deck — pure data files (static text, translations, no logic)
+pitch-deck/lib/presenter/presenter-faq.ts | owner=pitch-deck | reason=973 LOC, pure static FAQ array (questions/answers/keywords), no logic | review=2027-01
+pitch-deck/lib/presenter/presenter-script.ts | owner=pitch-deck | reason=608 LOC, pure static presenter script data + 3 trivial lookup functions | review=2027-01
+pitch-deck/lib/i18n.ts | owner=pitch-deck | reason=620 LOC, pure DE/EN translation dictionaries + 3 small format helpers | review=2027-01