Benjamin Admin
77c720e2df
CI / go-lint (push) Has been skipped
CI / python-lint (push) Has been skipped
CI / nodejs-lint (push) Has been skipped
CI / test-go-school (push) Successful in 50s
CI / test-go-edu-search (push) Successful in 45s
CI / test-python-klausur (push) Failing after 3m50s
CI / test-python-agent-core (push) Successful in 36s
CI / test-nodejs-website (push) Successful in 49s
- CLAUDE.md gets a new section summarising the two feature strands, pitfalls (Timefold name, JSX quotes, LOC budget), the auth/messaging outsourcing, and pointers to the three memory files for next session. - docs-src/services/schulkalender/ — 5 MkDocs pages mirroring the stundenplan structure: index, architecture, holidays, parent-flow, notifications. Each with DB tables, endpoints, and the dispatch payload contract for the colleague's Matrix/Email services. - mkdocs.yml gains the Schulkalender nav entry under Services. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
352 lines
13 KiB
Markdown
352 lines
13 KiB
Markdown
# BreakPilot Lehrer - KI-Bildungsplattform
|
||
|
||
## Entwicklungsumgebung (WICHTIG - IMMER ZUERST LESEN)
|
||
|
||
### Zwei-Rechner-Setup
|
||
|
||
| Geraet | Rolle | Aufgaben |
|
||
|--------|-------|----------|
|
||
| **MacBook** | Entwicklung | Claude Terminal, Code-Entwicklung, Browser (Frontend-Tests) |
|
||
| **Mac Mini** | Server | Docker, alle Services, Tests, Builds, Deployment |
|
||
|
||
**WICHTIG:** Code wird direkt auf dem MacBook in diesem Repo bearbeitet. Docker und Services laufen auf dem Mac Mini.
|
||
|
||
### Entwicklungsworkflow
|
||
|
||
```bash
|
||
# 1. Code auf MacBook bearbeiten (dieses Verzeichnis)
|
||
# 2. Committen und pushen:
|
||
git push origin main && git push gitea main
|
||
|
||
# 3. Auf Mac Mini pullen und Container neu bauen:
|
||
ssh macmini "git -C /Users/benjaminadmin/Projekte/breakpilot-lehrer pull --no-rebase origin main"
|
||
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-lehrer/docker-compose.yml build --no-cache <service>"
|
||
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-lehrer/docker-compose.yml up -d <service>"
|
||
```
|
||
|
||
### SSH-Verbindung (fuer Docker/Tests)
|
||
|
||
**WICHTIG:** `cd` in SSH-Kommandos funktioniert NICHT zuverlaessig! Stattdessen:
|
||
- Git: `git -C /Users/benjaminadmin/Projekte/breakpilot-lehrer <cmd>`
|
||
- Docker: `/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-lehrer/docker-compose.yml <cmd>`
|
||
- Logs: `/usr/local/bin/docker logs -f bp-lehrer-<service>`
|
||
|
||
---
|
||
|
||
## Voraussetzung
|
||
|
||
**breakpilot-core MUSS laufen!** Dieses Projekt nutzt Core-Services:
|
||
- PostgreSQL (Schema: `lehrer`, `core`)
|
||
- Valkey (Session-Cache)
|
||
- Vault (Secrets)
|
||
- RAG-Service (Vektorsuche)
|
||
- Embedding-Service (Text-Embeddings)
|
||
- Nginx (Reverse Proxy)
|
||
|
||
Pruefen: `curl -sf http://macmini:8099/health`
|
||
|
||
---
|
||
|
||
## Haupt-URLs (Browser auf MacBook)
|
||
|
||
### Frontends
|
||
|
||
| URL | Service | Beschreibung |
|
||
|-----|---------|--------------|
|
||
| **https://macmini/** | Studio v2 | Lehrer-/Schueler-Interface |
|
||
| **https://macmini:3000/** | Website | Oeffentliche Website |
|
||
| **https://macmini:3002/** | Admin Lehrer | Dashboard, AI-Tools, Architektur |
|
||
|
||
### Backend-APIs
|
||
|
||
| URL | Service | Beschreibung |
|
||
|-----|---------|--------------|
|
||
| https://macmini:8001/ | Backend Lehrer | Classroom, Units, Meetings, State Engine |
|
||
| https://macmini:8086/ | Klausur-Service | Pruefungen, OCR, Vokabel-Worksheets, RAG |
|
||
| wss://macmini:8091/ | Voice-Service | Spracheingabe WebSocket |
|
||
|
||
### Admin Lehrer Module (https://macmini:3002/)
|
||
|
||
| Pfad | Modul |
|
||
|------|-------|
|
||
| `/dashboard` | Dashboard + Catalog-Manager |
|
||
| `/ai/llm-compare` | LLM Vergleich |
|
||
| `/ai/ocr-compare` | OCR Vergleich |
|
||
| `/ai/ocr-labeling` | OCR Trainingsdaten |
|
||
| `/ai/test-quality` | Test Quality (BQAS) |
|
||
| `/ai/gpu` | GPU Infrastruktur (vast.ai) |
|
||
| `/ai/rag-pipeline` | RAG Pipeline |
|
||
| `/ai/magic-help` | KI-Assistent |
|
||
| `/education` | Bildungsmodule |
|
||
| `/communication` | Messenger, Meetings |
|
||
| `/development` | Entwickler-Tools, Docs |
|
||
| `/infrastructure` | Night-Mode, Security, SBOM |
|
||
| `/architecture` | Architektur-Visualisierung |
|
||
| `/rbac` | Rollenverwaltung |
|
||
| `/website` | Website-Management |
|
||
|
||
### Lehrer-Tools (Studio v2 - https://macmini/)
|
||
|
||
| Pfad | Tool | Beschreibung |
|
||
|------|------|--------------|
|
||
| `/vocab-worksheet` | Vokabel-Arbeitsblatt | OCR-Scan + Arbeitsblatt-Generator |
|
||
| `/korrektur` | Korrekturplattform | Abiturklausur-Korrektur |
|
||
|
||
---
|
||
|
||
## Services (~12 Container)
|
||
|
||
| Service | Tech | Port | Container |
|
||
|---------|------|------|-----------|
|
||
| admin-lehrer | Next.js 15 | 3002 (via nginx) | bp-lehrer-admin |
|
||
| studio-v2 | Next.js 15 | 443 (via nginx) | bp-lehrer-studio-v2 |
|
||
| website | Next.js 14 | 3000 (via nginx) | bp-lehrer-website |
|
||
| backend-lehrer | Python/FastAPI | 8001 | bp-lehrer-backend |
|
||
| klausur-service | Python/FastAPI | 8086 | bp-lehrer-klausur-service |
|
||
| school-service | Python | 8082 | bp-lehrer-school-service |
|
||
| voice-service | Python/FastAPI | 8091 | bp-lehrer-voice-service |
|
||
| geo-service | Python/FastAPI | 8084 | bp-lehrer-geo-service |
|
||
| breakpilot-drive | Node.js | - | bp-lehrer-drive (Profil: game) |
|
||
| paddleocr-service | Python | - | bp-lehrer-paddleocr (Profil: ocr) |
|
||
| agent-core | Python | - | bp-lehrer-agent-core (Profil: dev) |
|
||
|
||
### Profile (nur bei Bedarf)
|
||
|
||
| Profil | Services | Start mit |
|
||
|--------|----------|-----------|
|
||
| game | breakpilot-drive | `--profile game` |
|
||
| ocr | paddleocr-service | `--profile ocr` |
|
||
| dev | agent-core | `--profile dev` |
|
||
| recording | transcription-worker | `--profile recording` |
|
||
|
||
### Docker-Netzwerk
|
||
Nutzt das externe Core-Netzwerk:
|
||
```yaml
|
||
networks:
|
||
breakpilot-network:
|
||
external: true
|
||
name: breakpilot-network
|
||
```
|
||
|
||
### Container-Naming: `bp-lehrer-*`
|
||
### DB search_path: `lehrer,core,public`
|
||
|
||
---
|
||
|
||
## Verzeichnisstruktur
|
||
|
||
```
|
||
breakpilot-lehrer/
|
||
├── .claude/
|
||
│ ├── CLAUDE.md # Diese Datei
|
||
│ └── rules/ # Automatische Regeln
|
||
├── admin-lehrer/ # Next.js Admin Dashboard
|
||
│ ├── app/(admin)/ # 12 Route-Groups
|
||
│ ├── components/ # UI-Komponenten
|
||
│ └── lib/ # Utilities, Navigation
|
||
├── studio-v2/ # Next.js Lehrer-/Schueler-Studio
|
||
├── website/ # Next.js Oeffentliche Website
|
||
├── backend-lehrer/ # Python/FastAPI Backend
|
||
│ ├── classroom_api.py
|
||
│ ├── state_engine_api.py
|
||
│ ├── worksheets_api.py
|
||
│ ├── correction_api.py
|
||
│ ├── meetings_api.py
|
||
│ ├── messenger_api.py
|
||
│ └── ...
|
||
├── klausur-service/ # Klausur/OCR/RAG Service
|
||
├── school-service/ # Schulverwaltung
|
||
├── voice-service/ # Spracheingabe (Whisper)
|
||
├── geo-service/ # Geo-Daten (PostGIS)
|
||
├── agent-core/ # Multi-Agent System
|
||
├── breakpilot-drive/ # Dateiablage (IPFS)
|
||
├── scripts/ # Helper Scripts
|
||
└── docker-compose.yml # Lehrer Compose (~12 Services)
|
||
```
|
||
|
||
---
|
||
|
||
## Haeufige Befehle
|
||
|
||
### Docker
|
||
|
||
```bash
|
||
# Lehrer-Services starten (Core muss laufen!)
|
||
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-lehrer/docker-compose.yml up -d"
|
||
|
||
# Einzelnen Service neu bauen
|
||
ssh macmini "/usr/local/bin/docker compose -f /Users/benjaminadmin/Projekte/breakpilot-lehrer/docker-compose.yml build --no-cache <service>"
|
||
|
||
# Logs
|
||
ssh macmini "/usr/local/bin/docker logs -f bp-lehrer-<service>"
|
||
|
||
# Status
|
||
ssh macmini "/usr/local/bin/docker ps --filter name=bp-lehrer"
|
||
```
|
||
|
||
**WICHTIG:** Docker-Pfad auf Mac Mini ist `/usr/local/bin/docker` (nicht im Standard-SSH-PATH).
|
||
**WICHTIG:** Immer `-f` mit vollem Pfad zur docker-compose.yml nutzen, `cd` in SSH funktioniert nicht!
|
||
|
||
### Frontend-Entwicklung
|
||
|
||
```bash
|
||
# Admin Lehrer im Browser testen:
|
||
# https://macmini:3002/
|
||
|
||
# Studio v2 im Browser testen:
|
||
# https://macmini/
|
||
|
||
# Website im Browser testen:
|
||
# https://macmini:3000/
|
||
```
|
||
|
||
### Git
|
||
|
||
```bash
|
||
# Zu BEIDEN Remotes pushen (PFLICHT!):
|
||
ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-lehrer && 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
|
||
- Dokumentation aktualisieren in MkDocs
|
||
|
||
### 3. Sensitive Dateien
|
||
**NIEMALS aendern oder committen:**
|
||
- `.env`, `.env.local`, Vault-Tokens, SSL-Zertifikate
|
||
- `*.pdf`, `*.docx`, kompilierte Binaries, grosse Medien
|
||
|
||
---
|
||
|
||
## Tech-Stack
|
||
|
||
| Sprache | Services |
|
||
|---------|----------|
|
||
| Python/FastAPI | backend-lehrer, klausur-service, voice-service, geo-service |
|
||
| TypeScript/Next.js | admin-lehrer, studio-v2, website |
|
||
| Node.js | breakpilot-drive |
|
||
| Python | agent-core, paddleocr-service |
|
||
|
||
---
|
||
|
||
## Stundenplan + Schulkalender (Mai 2026, alle Phasen deployed)
|
||
|
||
Zwei groesse Feature-Strange, vollstaendig live auf Mac Mini:
|
||
|
||
| Pfad | Beschreibung |
|
||
|------|--------------|
|
||
| `/stundenplan` (studio-v2) | Lehrer-UI mit 9 Tabs (Plan + 7 Stammdaten + Regeln), 15 Constraint-Editoren, Pin/Unpin im Wochengrid |
|
||
| `/schulkalender` (studio-v2) | Bundesland-Wizard, Monatsansicht mit Ferien (16 BL × 3 Jahre), Schul-Events, Schuljahres-Rollover, Eltern-Manager |
|
||
| `/eltern` (studio-v2) | Eltern-Sicht: Wochengrid des eigenen Kindes in Eltern-Sprache, Magic-Link-Login |
|
||
| `school-service` (Go, :8084) | Beide Backends — 30+ Tabellen, JWT-Auth (Dev-Bypass aktiv), Cron fuer Notifications |
|
||
| `timetable-solver-service` (Python+JVM, :8095) | Timefold-basierter Solver, 14 Constraints implementiert |
|
||
|
||
**Wichtigste Memo-Dateien fuer Wiedereinstieg:**
|
||
- `~/.claude/projects/-Users-benjaminadmin-Projekte-breakpilot-lehrer/memory/session_summary_2026_05_22.md` — vollstaendiges Inventar
|
||
- `~/.claude/projects/-Users-benjaminadmin/memory/project_timetable_scheduler.md` — Stundenplan-Status
|
||
- `~/.claude/projects/-Users-benjaminadmin-Projekte-breakpilot-lehrer/memory/project_schulkalender.md` — Schulkalender-Status
|
||
|
||
**Pitfalls (vermeidet diese):**
|
||
- Timefold Python-Package heisst `timefold` (NICHT `timefold-solver`), v1.24.0b0
|
||
- Production-Auth + Matrix/Email-Services baut Kollege — Frontend-Hooks nutzen, kein eigener Service-Code
|
||
- JSX-Attribute mit deutschen Quotes `„X"` brechen, Loesung: `description={"..."}` Expression-Form
|
||
- LOC-Budget 500 pro File — bei specs mit shared Helpers arbeiten (`e2e/_helpers.ts`)
|
||
|
||
**Test-Status (Stand 2026-05-22):** 89 Go + 21 Playwright im Schulkalender + 42 Playwright im Stundenplan = **152 grun**
|
||
|
||
**Offen:** Seed-Daten fuer Demo-Schule, Vollschuljahr-ICS mit RRULE+EXDATE, Untis-Import (Phase 4 geparkt).
|
||
|
||
---
|
||
|
||
## Wichtige Dateien (Referenz)
|
||
|
||
| Datei | Beschreibung |
|
||
|-------|--------------|
|
||
| `klausur-service/backend/main.py` | Haupt-API: Klausuren, OCR, Vocab |
|
||
| `klausur-service/backend/nru_worksheet_generator.py` | NRU Arbeitsblatt-Generator |
|
||
| `klausur-service/backend/hybrid_vocab_extractor.py` | OCR-Extraktion |
|
||
| `admin-lehrer/app/(admin)/` | Alle 12 Admin Route-Groups |
|
||
| `admin-lehrer/lib/navigation.ts` | Sidebar-Navigation |
|
||
| `studio-v2/app/vocab-worksheet/page.tsx` | Vokabel-Arbeitsblatt UI |
|
||
| `website/app/admin/klausur-korrektur/` | Korrektur-Workspace |
|
||
| `backend-lehrer/classroom_api.py` | Classroom Engine |
|
||
| `backend-lehrer/state_engine_api.py` | State Engine |
|
||
|
||
---
|
||
|
||
## Compliance: Kein Scan/OCR im Kunden-Frontend (NON-NEGOTIABLE)
|
||
|
||
Studio-v2 (Kunden-Frontend, Port 443) darf **KEINE** Features enthalten die:
|
||
- Buchseiten/Schulbuecher von Dritten rekonstruieren oder reproduzieren
|
||
- Aktiv zum Upload fremder urheberrechtlich geschuetzter Werke auffordern
|
||
|
||
**Erlaubt** in studio-v2:
|
||
- Upload eigener Dokumente durch Lehrer (eigene Arbeitsblaetter, Tests, Materialien)
|
||
- OCR/Verarbeitung von Dokumenten bei denen der Lehrer Urheber ist
|
||
- Manuelle Vokabeleingabe durch Lehrer
|
||
- Vorschlagslisten aus eigenem Woerterbuch (160k MIT-lizenzierte Woerter)
|
||
- Lernunit-Erstellung aus eigenen/ausgewaehlten Inhalten
|
||
- Audio/Bild/Quiz/Karteikarten-Generierung
|
||
|
||
**Erweiterte OCR/Scan Features** (z.B. Vision-LLM Fusion, A/B Testing Toggles) bleiben
|
||
im Admin-Frontend (admin-lehrer, Port 3002) fuer Entwicklung und Testing.
|
||
|
||
**Hintergrund**: Urheberrechtliche Haftung der GmbH. Das System ist eine
|
||
Didaktik-Engine (Transformation + Lernen), KEIN Content-Reconstruction-Tool.
|
||
|
||
---
|
||
|
||
## 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
|
||
|
||
- **Python:** Routes duenn → Business Logic in Services → Persistenz in Repositories
|
||
- **Go:** Handler ≤40 LOC → Service-Layer → Repository-Pattern
|
||
- **TypeScript/Next.js:** page.tsx duenn → Server Actions, Queries, Components auslagern
|
||
- **Types:** Monolithische types.ts frueh splitten, types.ts + types/ Shadowing vermeiden
|
||
|
||
### 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
|
||
|
||
### Commit-Marker
|
||
|
||
- `[migration-approved]` — Schema-/Migrations-Aenderungen
|
||
- `[guardrail-change]` — Aenderungen an .claude/**, scripts/check-loc.sh
|
||
- `[split-required]` — Aenderung beginnt mit Datei-Split
|
||
- `[interface-change]` — Public API Contracts geaendert
|
||
|
||
### LOC-Check ausfuehren
|
||
|
||
```bash
|
||
bash scripts/check-loc.sh --changed # nur geaenderte Dateien
|
||
bash scripts/check-loc.sh --all # alle Dateien (zeigt alle Violations)
|
||
```
|