Initial commit: breakpilot-core - Shared Infrastructure
Docker Compose with 24+ services: - PostgreSQL (PostGIS), Valkey, MinIO, Qdrant - Vault (PKI/TLS), Nginx (Reverse Proxy) - Backend Core API, Consent Service, Billing Service - RAG Service, Embedding Service - Gitea, Woodpecker CI/CD - Night Scheduler, Health Aggregator - Jitsi (Web/XMPP/JVB/Jicofo), Mailpit Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Benjamin Boenisch
294
docs-src/architecture/auth-system.md
Normal file
294
docs-src/architecture/auth-system.md
Normal file
@@ -0,0 +1,294 @@
|
||||
# BreakPilot Authentifizierung & Autorisierung
|
||||
|
||||
## Uebersicht
|
||||
|
||||
BreakPilot verwendet einen **Hybrid-Ansatz** fuer Authentifizierung und Autorisierung:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ AUTHENTIFIZIERUNG │
|
||||
│ "Wer bist du?" │
|
||||
│ ┌────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ HybridAuthenticator │ │
|
||||
│ │ ┌─────────────────────┐ ┌─────────────────────────────────┐ │ │
|
||||
│ │ │ Keycloak │ │ Lokales JWT │ │ │
|
||||
│ │ │ (Produktion) │ OR │ (Entwicklung) │ │ │
|
||||
│ │ │ RS256 + JWKS │ │ HS256 + Secret │ │ │
|
||||
│ │ └─────────────────────┘ └─────────────────────────────────┘ │ │
|
||||
│ └────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ AUTORISIERUNG │
|
||||
│ "Was darfst du?" │
|
||||
│ ┌────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ rbac.py (Eigenentwicklung) │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌───────────────────┐ │ │
|
||||
│ │ │ Rollen-Hierarchie│ │ PolicySet │ │ DEFAULT_PERMISSIONS│ │ │
|
||||
│ │ │ 15+ Rollen │ │ Bundesland- │ │ Matrix │ │ │
|
||||
│ │ │ - Erstkorrektor │ │ spezifisch │ │ Rolle→Ressource→ │ │ │
|
||||
│ │ │ - Klassenlehrer │ │ - Niedersachsen │ │ Aktion │ │ │
|
||||
│ │ │ - Schulleitung │ │ - Bayern │ │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └───────────────────┘ │ │
|
||||
│ └────────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Warum dieser Ansatz?
|
||||
|
||||
### Alternative Loesungen (verworfen)
|
||||
|
||||
| Tool | Problem fuer BreakPilot |
|
||||
|------|-------------------------|
|
||||
| **Casbin** | Zu generisch fuer Bundesland-spezifische Policies |
|
||||
| **Cerbos** | Overhead: Externer PDP-Service fuer ~15 Rollen ueberdimensioniert |
|
||||
| **OpenFGA** | Zanzibar-Modell optimiert fuer Graph-Beziehungen, nicht Hierarchien |
|
||||
| **Keycloak RBAC** | Kann keine ressourcen-spezifischen Zuweisungen (User X ist Erstkorrektor fuer Package Y) |
|
||||
|
||||
### Vorteile des Hybrid-Ansatzes
|
||||
|
||||
1. **Keycloak fuer Authentifizierung:**
|
||||
- Bewährtes IAM-System
|
||||
- SSO, Federation, MFA
|
||||
- Apache-2.0 Lizenz
|
||||
|
||||
2. **Eigenes rbac.py fuer Autorisierung:**
|
||||
- Domaenenspezifische Logik (Korrekturkette, Zeugnis-Workflow)
|
||||
- Bundesland-spezifische Regeln
|
||||
- Zeitlich begrenzte Zuweisungen
|
||||
- Key-Sharing fuer verschluesselte Klausuren
|
||||
|
||||
---
|
||||
|
||||
## Authentifizierung (auth/keycloak_auth.py)
|
||||
|
||||
### Konfiguration
|
||||
|
||||
```python
|
||||
# Entwicklung: Lokales JWT (Standard)
|
||||
JWT_SECRET=your-secret-key
|
||||
|
||||
# Produktion: Keycloak
|
||||
KEYCLOAK_SERVER_URL=https://keycloak.breakpilot.app
|
||||
KEYCLOAK_REALM=breakpilot
|
||||
KEYCLOAK_CLIENT_ID=breakpilot-backend
|
||||
KEYCLOAK_CLIENT_SECRET=your-client-secret
|
||||
```
|
||||
|
||||
### Token-Erkennung
|
||||
|
||||
Der `HybridAuthenticator` erkennt automatisch den Token-Typ:
|
||||
|
||||
```python
|
||||
# Keycloak-Token (RS256)
|
||||
{
|
||||
"iss": "https://keycloak.breakpilot.app/realms/breakpilot",
|
||||
"sub": "user-uuid",
|
||||
"realm_access": {"roles": ["teacher", "admin"]},
|
||||
...
|
||||
}
|
||||
|
||||
# Lokales JWT (HS256)
|
||||
{
|
||||
"iss": "breakpilot",
|
||||
"user_id": "user-uuid",
|
||||
"role": "admin",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
### FastAPI Integration
|
||||
|
||||
```python
|
||||
from auth import get_current_user
|
||||
|
||||
@app.get("/api/protected")
|
||||
async def protected_endpoint(user: dict = Depends(get_current_user)):
|
||||
# user enthält: user_id, email, role, realm_roles, tenant_id
|
||||
return {"user_id": user["user_id"]}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Autorisierung (klausur-service/backend/rbac.py)
|
||||
|
||||
### Rollen (15+)
|
||||
|
||||
| Rolle | Beschreibung | Bereich |
|
||||
|-------|--------------|---------|
|
||||
| `erstkorrektor` | Erster Prüfer | Klausur |
|
||||
| `zweitkorrektor` | Zweiter Prüfer | Klausur |
|
||||
| `drittkorrektor` | Dritter Prüfer | Klausur |
|
||||
| `klassenlehrer` | Klassenleitung | Zeugnis |
|
||||
| `fachlehrer` | Fachlehrkraft | Noten |
|
||||
| `fachvorsitz` | Fachkonferenz-Leitung | Fachschaft |
|
||||
| `schulleitung` | Schulleiter/in | Schule |
|
||||
| `zeugnisbeauftragter` | Zeugnis-Koordination | Zeugnis |
|
||||
| `sekretariat` | Verwaltung | Schule |
|
||||
| `data_protection_officer` | DSB | DSGVO |
|
||||
| ... | | |
|
||||
|
||||
### Ressourcentypen (25+)
|
||||
|
||||
```python
|
||||
class ResourceType(str, Enum):
|
||||
EXAM_PACKAGE = "exam_package" # Klausurpaket
|
||||
STUDENT_SUBMISSION = "student_submission"
|
||||
CORRECTION = "correction"
|
||||
ZEUGNIS = "zeugnis"
|
||||
FACHNOTE = "fachnote"
|
||||
KOPFNOTE = "kopfnote"
|
||||
BEMERKUNG = "bemerkung"
|
||||
...
|
||||
```
|
||||
|
||||
### Aktionen (17)
|
||||
|
||||
```python
|
||||
class Action(str, Enum):
|
||||
CREATE = "create"
|
||||
READ = "read"
|
||||
UPDATE = "update"
|
||||
DELETE = "delete"
|
||||
SIGN_OFF = "sign_off" # Freigabe
|
||||
BREAK_GLASS = "break_glass" # Notfall-Zugriff
|
||||
SHARE_KEY = "share_key" # Schlüssel teilen
|
||||
...
|
||||
```
|
||||
|
||||
### Permission-Pruefung
|
||||
|
||||
```python
|
||||
from klausur_service.backend.rbac import PolicyEngine
|
||||
|
||||
engine = PolicyEngine()
|
||||
|
||||
# Pruefe ob User X Klausur Y korrigieren darf
|
||||
allowed = engine.check_permission(
|
||||
user_id="user-uuid",
|
||||
action=Action.UPDATE,
|
||||
resource_type=ResourceType.CORRECTION,
|
||||
resource_id="klausur-uuid"
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Bundesland-spezifische Policies
|
||||
|
||||
```python
|
||||
@dataclass
|
||||
class PolicySet:
|
||||
bundesland: str
|
||||
abitur_type: str # "landesabitur" | "zentralabitur"
|
||||
|
||||
# Korrekturkette
|
||||
korrektoren_anzahl: int # 2 oder 3
|
||||
anonyme_erstkorrektur: bool
|
||||
|
||||
# Sichtbarkeit
|
||||
zk_visibility_mode: ZKVisibilityMode # BLIND | SEMI | FULL
|
||||
eh_visibility_mode: EHVisibilityMode
|
||||
|
||||
# Zeugnis
|
||||
kopfnoten_enabled: bool
|
||||
...
|
||||
```
|
||||
|
||||
### Beispiel: Niedersachsen
|
||||
|
||||
```python
|
||||
NIEDERSACHSEN_POLICY = PolicySet(
|
||||
bundesland="niedersachsen",
|
||||
abitur_type="landesabitur",
|
||||
korrektoren_anzahl=2,
|
||||
anonyme_erstkorrektur=True,
|
||||
zk_visibility_mode=ZKVisibilityMode.BLIND,
|
||||
eh_visibility_mode=EHVisibilityMode.SUMMARY_ONLY,
|
||||
kopfnoten_enabled=True,
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Workflow-Beispiele
|
||||
|
||||
### Klausurkorrektur-Workflow
|
||||
|
||||
```
|
||||
1. Lehrer laedt Klausuren hoch
|
||||
└── Rolle: "lehrer" + Action.CREATE auf EXAM_PACKAGE
|
||||
|
||||
2. Erstkorrektor korrigiert
|
||||
└── Rolle: "erstkorrektor" (ressourcen-spezifisch) + Action.UPDATE auf CORRECTION
|
||||
|
||||
3. Zweitkorrektor ueberprueft
|
||||
└── Rolle: "zweitkorrektor" + Action.READ auf CORRECTION
|
||||
└── Policy: zk_visibility_mode bestimmt Sichtbarkeit
|
||||
|
||||
4. Drittkorrektor (bei Abweichung)
|
||||
└── Rolle: "drittkorrektor" + Action.SIGN_OFF
|
||||
```
|
||||
|
||||
### Zeugnis-Workflow
|
||||
|
||||
```
|
||||
1. Fachlehrer traegt Noten ein
|
||||
└── Rolle: "fachlehrer" + Action.CREATE auf FACHNOTE
|
||||
|
||||
2. Klassenlehrer prueft
|
||||
└── Rolle: "klassenlehrer" + Action.READ auf ZEUGNIS
|
||||
└── Action.SIGN_OFF freigeben
|
||||
|
||||
3. Zeugnisbeauftragter final
|
||||
└── Rolle: "zeugnisbeauftragter" + Action.SIGN_OFF
|
||||
|
||||
4. Schulleitung unterzeichnet
|
||||
└── Rolle: "schulleitung" + Action.SIGN_OFF
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dateien
|
||||
|
||||
| Datei | Beschreibung |
|
||||
|-------|--------------|
|
||||
| `backend/auth/__init__.py` | Auth-Modul Exports |
|
||||
| `backend/auth/keycloak_auth.py` | Hybrid-Authentifizierung |
|
||||
| `klausur-service/backend/rbac.py` | Autorisierungs-Engine |
|
||||
| `backend/rbac_api.py` | REST API fuer Rollenverwaltung |
|
||||
|
||||
---
|
||||
|
||||
## Konfiguration
|
||||
|
||||
### Entwicklung (ohne Keycloak)
|
||||
|
||||
```bash
|
||||
# .env
|
||||
ENVIRONMENT=development
|
||||
JWT_SECRET=dev-secret-32-chars-minimum-here
|
||||
```
|
||||
|
||||
### Produktion (mit Keycloak)
|
||||
|
||||
```bash
|
||||
# .env
|
||||
ENVIRONMENT=production
|
||||
JWT_SECRET=<openssl rand -hex 32>
|
||||
KEYCLOAK_SERVER_URL=https://keycloak.breakpilot.app
|
||||
KEYCLOAK_REALM=breakpilot
|
||||
KEYCLOAK_CLIENT_ID=breakpilot-backend
|
||||
KEYCLOAK_CLIENT_SECRET=<from keycloak admin console>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Sicherheitshinweise
|
||||
|
||||
1. **Secrets niemals im Code** - Immer Umgebungsvariablen verwenden
|
||||
2. **JWT_SECRET in Produktion** - Mindestens 32 Bytes, generiert mit `openssl rand -hex 32`
|
||||
3. **Keycloak HTTPS** - KEYCLOAK_VERIFY_SSL=true in Produktion
|
||||
4. **Token-Expiration** - Keycloak-Tokens kurz halten (5-15 Minuten)
|
||||
5. **Audit-Trail** - Alle Berechtigungspruefungen werden geloggt
|
||||
215
docs-src/architecture/devsecops.md
Normal file
215
docs-src/architecture/devsecops.md
Normal file
@@ -0,0 +1,215 @@
|
||||
# BreakPilot DevSecOps Architecture
|
||||
|
||||
## Uebersicht
|
||||
|
||||
BreakPilot implementiert einen umfassenden DevSecOps-Ansatz mit Security-by-Design fuer die Entwicklung und den Betrieb der Bildungsplattform.
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||||
│ DEVSECOPS PIPELINE │
|
||||
│ │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ Pre-Commit │───►│ CI/CD │───►│ Build │───►│ Deploy │ │
|
||||
│ │ Hooks │ │ Pipeline │ │ & Scan │ │ & Monitor │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
│ │ │ │ │ │
|
||||
│ ▼ ▼ ▼ ▼ │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ Gitleaks │ │ Semgrep │ │ Trivy │ │ Falco │ │
|
||||
│ │ Bandit │ │ OWASP DC │ │ Grype │ │ (optional) │ │
|
||||
│ │ Secrets │ │ SAST/SCA │ │ SBOM │ │ Runtime │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Security Tools Stack
|
||||
|
||||
### 1. Secrets Detection
|
||||
|
||||
| Tool | Version | Lizenz | Verwendung |
|
||||
|------|---------|--------|------------|
|
||||
| **Gitleaks** | 8.18.x | MIT | Pre-commit Hook, CI/CD |
|
||||
| **detect-secrets** | 1.4.x | Apache-2.0 | Zusaetzliche Baseline-Pruefung |
|
||||
|
||||
**Konfiguration:** `.gitleaks.toml`
|
||||
|
||||
```bash
|
||||
# Lokal ausfuehren
|
||||
gitleaks detect --source . -v
|
||||
|
||||
# Pre-commit (automatisch)
|
||||
gitleaks protect --staged -v
|
||||
```
|
||||
|
||||
### 2. Static Application Security Testing (SAST)
|
||||
|
||||
| Tool | Version | Lizenz | Sprachen |
|
||||
|------|---------|--------|----------|
|
||||
| **Semgrep** | 1.52.x | LGPL-2.1 | Python, Go, JavaScript, TypeScript |
|
||||
| **Bandit** | 1.7.x | Apache-2.0 | Python (spezialisiert) |
|
||||
|
||||
**Konfiguration:** `.semgrep.yml`
|
||||
|
||||
```bash
|
||||
# Semgrep ausfuehren
|
||||
semgrep scan --config auto --config .semgrep.yml
|
||||
|
||||
# Bandit ausfuehren
|
||||
bandit -r backend/ -ll
|
||||
```
|
||||
|
||||
### 3. Software Composition Analysis (SCA)
|
||||
|
||||
| Tool | Version | Lizenz | Verwendung |
|
||||
|------|---------|--------|------------|
|
||||
| **Trivy** | 0.48.x | Apache-2.0 | Filesystem, Container, IaC |
|
||||
| **Grype** | 0.74.x | Apache-2.0 | Vulnerability Scanning |
|
||||
| **OWASP Dependency-Check** | 9.x | Apache-2.0 | CVE/NVD Abgleich |
|
||||
|
||||
**Konfiguration:** `.trivy.yaml`
|
||||
|
||||
```bash
|
||||
# Filesystem-Scan
|
||||
trivy fs . --severity HIGH,CRITICAL
|
||||
|
||||
# Container-Scan
|
||||
trivy image breakpilot-pwa-backend:latest
|
||||
```
|
||||
|
||||
### 4. SBOM (Software Bill of Materials)
|
||||
|
||||
| Tool | Version | Lizenz | Formate |
|
||||
|------|---------|--------|---------|
|
||||
| **Syft** | 0.100.x | Apache-2.0 | CycloneDX, SPDX |
|
||||
|
||||
```bash
|
||||
# SBOM generieren
|
||||
syft dir:. -o cyclonedx-json=sbom.json
|
||||
syft dir:. -o spdx-json=sbom-spdx.json
|
||||
```
|
||||
|
||||
### 5. Dynamic Application Security Testing (DAST)
|
||||
|
||||
| Tool | Version | Lizenz | Verwendung |
|
||||
|------|---------|--------|------------|
|
||||
| **OWASP ZAP** | 2.14.x | Apache-2.0 | Staging-Scans (nightly) |
|
||||
|
||||
```bash
|
||||
# ZAP Scan gegen Staging
|
||||
docker run -t owasp/zap2docker-stable zap-baseline.py \
|
||||
-t http://staging.breakpilot.app -r zap-report.html
|
||||
```
|
||||
|
||||
## Pre-Commit Hooks
|
||||
|
||||
Die Pre-Commit-Konfiguration (`.pre-commit-config.yaml`) fuehrt automatisch bei jedem Commit aus:
|
||||
|
||||
1. **Schnelle Checks** (< 10 Sekunden):
|
||||
- Gitleaks (Secrets)
|
||||
- Trailing Whitespace
|
||||
- YAML/JSON Validierung
|
||||
|
||||
2. **Code Quality** (< 30 Sekunden):
|
||||
- Black/Ruff (Python Formatting)
|
||||
- Go fmt/vet
|
||||
- ESLint (JavaScript)
|
||||
|
||||
3. **Security Checks** (< 60 Sekunden):
|
||||
- Bandit (Python Security)
|
||||
- Semgrep (Error-Severity)
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
# Pre-commit installieren
|
||||
pip install pre-commit
|
||||
|
||||
# Hooks aktivieren
|
||||
pre-commit install
|
||||
|
||||
# Alle Checks manuell ausfuehren
|
||||
pre-commit run --all-files
|
||||
```
|
||||
|
||||
## Severity-Gates
|
||||
|
||||
| Phase | Severity | Aktion |
|
||||
|-------|----------|--------|
|
||||
| Pre-Commit | ERROR | Commit blockiert |
|
||||
| PR/CI | CRITICAL, HIGH | Pipeline blockiert |
|
||||
| Nightly Scan | MEDIUM+ | Report generiert |
|
||||
| Production Deploy | CRITICAL | Deploy blockiert |
|
||||
|
||||
## Security Dashboard
|
||||
|
||||
Das BreakPilot Admin Panel enthaelt ein integriertes Security Dashboard unter **Verwaltung > Security**.
|
||||
|
||||
### Features
|
||||
|
||||
**Fuer Entwickler:**
|
||||
- Scan-Ergebnisse auf einen Blick
|
||||
- Pre-commit Hook Status
|
||||
- Quick-Fix Suggestions
|
||||
- SBOM Viewer mit Suchfunktion
|
||||
|
||||
**Fuer Security-Experten:**
|
||||
- Vulnerability Severity Distribution (Critical/High/Medium/Low)
|
||||
- CVE-Tracking mit Fix-Verfuegbarkeit
|
||||
- Compliance-Status (OWASP Top 10, DSGVO)
|
||||
- Secrets Detection History
|
||||
|
||||
**Fuer Ops:**
|
||||
- Container Image Scan Results
|
||||
- Dependency Update Status
|
||||
- Security Scan Scheduling
|
||||
- Auto-Refresh alle 30 Sekunden
|
||||
|
||||
### API Endpoints
|
||||
|
||||
```
|
||||
GET /api/v1/security/tools - Tool-Status
|
||||
GET /api/v1/security/findings - Alle Findings
|
||||
GET /api/v1/security/summary - Severity-Zusammenfassung
|
||||
GET /api/v1/security/sbom - SBOM-Daten
|
||||
GET /api/v1/security/history - Scan-Historie
|
||||
GET /api/v1/security/reports/{tool} - Tool-spezifischer Report
|
||||
POST /api/v1/security/scan/{type} - Scan starten
|
||||
GET /api/v1/security/health - Health-Check
|
||||
```
|
||||
|
||||
## Compliance
|
||||
|
||||
Die DevSecOps-Pipeline unterstuetzt folgende Compliance-Anforderungen:
|
||||
|
||||
- **DSGVO/GDPR**: Automatische Erkennung von PII-Leaks
|
||||
- **OWASP Top 10**: SAST/DAST-Scans gegen bekannte Schwachstellen
|
||||
- **Supply Chain Security**: SBOM-Generierung fuer Audit-Trails
|
||||
- **CVE Tracking**: Automatischer Abgleich mit NVD/CVE-Datenbanken
|
||||
|
||||
## Tool-Installation
|
||||
|
||||
### macOS (Homebrew)
|
||||
|
||||
```bash
|
||||
# Security Tools
|
||||
brew install gitleaks
|
||||
brew install trivy
|
||||
brew install syft
|
||||
brew install grype
|
||||
|
||||
# Python Tools
|
||||
pip install semgrep bandit pre-commit
|
||||
```
|
||||
|
||||
### Linux (apt/snap)
|
||||
|
||||
```bash
|
||||
# Gitleaks
|
||||
sudo snap install gitleaks
|
||||
|
||||
# Trivy
|
||||
sudo apt-get install trivy
|
||||
|
||||
# Python Tools
|
||||
pip install semgrep bandit pre-commit
|
||||
```
|
||||
197
docs-src/architecture/environments.md
Normal file
197
docs-src/architecture/environments.md
Normal file
@@ -0,0 +1,197 @@
|
||||
# Umgebungs-Architektur
|
||||
|
||||
## Übersicht
|
||||
|
||||
BreakPilot verwendet eine 3-Umgebungs-Strategie für sichere Entwicklung und Deployment:
|
||||
|
||||
```
|
||||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||||
│ Development │────▶│ Staging │────▶│ Production │
|
||||
│ (develop) │ │ (staging) │ │ (main) │
|
||||
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
||||
Tägliche Getesteter Code Produktionsreif
|
||||
Entwicklung
|
||||
```
|
||||
|
||||
## Umgebungen
|
||||
|
||||
### Development (Dev)
|
||||
|
||||
**Zweck:** Tägliche Entwicklungsarbeit
|
||||
|
||||
| Eigenschaft | Wert |
|
||||
|-------------|------|
|
||||
| Git Branch | `develop` |
|
||||
| Compose File | `docker-compose.yml` + `docker-compose.override.yml` (auto) |
|
||||
| Env File | `.env.dev` |
|
||||
| Database | `breakpilot_dev` |
|
||||
| Debug | Aktiviert |
|
||||
| Hot-Reload | Aktiviert |
|
||||
|
||||
**Start:**
|
||||
```bash
|
||||
./scripts/start.sh dev
|
||||
# oder einfach:
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### Staging
|
||||
|
||||
**Zweck:** Getesteter, freigegebener Code vor Produktion
|
||||
|
||||
| Eigenschaft | Wert |
|
||||
|-------------|------|
|
||||
| Git Branch | `staging` |
|
||||
| Compose File | `docker-compose.yml` + `docker-compose.staging.yml` |
|
||||
| Env File | `.env.staging` |
|
||||
| Database | `breakpilot_staging` (separates Volume) |
|
||||
| Debug | Deaktiviert |
|
||||
| Hot-Reload | Deaktiviert |
|
||||
|
||||
**Start:**
|
||||
```bash
|
||||
./scripts/start.sh staging
|
||||
# oder:
|
||||
docker compose -f docker-compose.yml -f docker-compose.staging.yml up -d
|
||||
```
|
||||
|
||||
### Production (Prod)
|
||||
|
||||
**Zweck:** Live-System für Endbenutzer (ab Launch)
|
||||
|
||||
| Eigenschaft | Wert |
|
||||
|-------------|------|
|
||||
| Git Branch | `main` |
|
||||
| Compose File | `docker-compose.yml` + `docker-compose.prod.yml` |
|
||||
| Env File | `.env.prod` (NICHT im Repository!) |
|
||||
| Database | `breakpilot_prod` (separates Volume) |
|
||||
| Debug | Deaktiviert |
|
||||
| Vault | Pflicht (keine Env-Fallbacks) |
|
||||
|
||||
## Datenbank-Trennung
|
||||
|
||||
Jede Umgebung verwendet separate Docker Volumes für vollständige Datenisolierung:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ PostgreSQL Volumes │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ breakpilot-dev_postgres_data │ Development Database │
|
||||
│ breakpilot_staging_postgres │ Staging Database │
|
||||
│ breakpilot_prod_postgres │ Production Database │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Port-Mapping
|
||||
|
||||
Um mehrere Umgebungen gleichzeitig laufen zu lassen, verwenden sie unterschiedliche Ports:
|
||||
|
||||
| Service | Dev Port | Staging Port | Prod Port |
|
||||
|---------|----------|--------------|-----------|
|
||||
| Backend | 8000 | 8001 | 8000 |
|
||||
| PostgreSQL | 5432 | 5433 | - (intern) |
|
||||
| MinIO | 9000/9001 | 9002/9003 | - (intern) |
|
||||
| Qdrant | 6333/6334 | 6335/6336 | - (intern) |
|
||||
| Mailpit | 8025/1025 | 8026/1026 | - (deaktiviert) |
|
||||
|
||||
## Git Branching Strategie
|
||||
|
||||
```
|
||||
main (Prod) ← Nur Release-Merges, geschützt
|
||||
│
|
||||
▼
|
||||
staging ← Getesteter Code, Review erforderlich
|
||||
│
|
||||
▼
|
||||
develop (Dev) ← Tägliche Arbeit, Default-Branch
|
||||
│
|
||||
▼
|
||||
feature/* ← Feature-Branches (optional)
|
||||
```
|
||||
|
||||
### Workflow
|
||||
|
||||
1. **Entwicklung:** Arbeite auf `develop`
|
||||
2. **Code-Review:** Erstelle PR von Feature-Branch → `develop`
|
||||
3. **Staging:** Promote `develop` → `staging` mit Tests
|
||||
4. **Release:** Promote `staging` → `main` nach Freigabe
|
||||
|
||||
### Promotion-Befehle
|
||||
|
||||
```bash
|
||||
# develop → staging
|
||||
./scripts/promote.sh dev-to-staging
|
||||
|
||||
# staging → main (Production)
|
||||
./scripts/promote.sh staging-to-prod
|
||||
```
|
||||
|
||||
## Secrets Management
|
||||
|
||||
### Development
|
||||
- `.env.dev` enthält Entwicklungs-Credentials
|
||||
- Vault optional (Dev-Token)
|
||||
- Mailpit für E-Mail-Tests
|
||||
|
||||
### Staging
|
||||
- `.env.staging` enthält Test-Credentials
|
||||
- Vault empfohlen
|
||||
- Mailpit für E-Mail-Sicherheit
|
||||
|
||||
### Production
|
||||
- `.env.prod` NICHT im Repository
|
||||
- Vault PFLICHT
|
||||
- Echte SMTP-Konfiguration
|
||||
|
||||
Siehe auch: [Secrets Management](./secrets-management.md)
|
||||
|
||||
## Docker Compose Architektur
|
||||
|
||||
```
|
||||
docker-compose.yml ← Basis-Konfiguration
|
||||
│
|
||||
├── docker-compose.override.yml ← Dev (auto-geladen)
|
||||
│
|
||||
├── docker-compose.staging.yml ← Staging (explizit)
|
||||
│
|
||||
└── docker-compose.prod.yml ← Production (explizit)
|
||||
```
|
||||
|
||||
### Automatisches Laden
|
||||
|
||||
Docker Compose lädt automatisch:
|
||||
1. `docker-compose.yml`
|
||||
2. `docker-compose.override.yml` (falls vorhanden)
|
||||
|
||||
Daher startet `docker compose up` automatisch die Dev-Umgebung.
|
||||
|
||||
## Helper Scripts
|
||||
|
||||
| Script | Beschreibung |
|
||||
|--------|--------------|
|
||||
| `scripts/env-switch.sh` | Wechselt zwischen Umgebungen |
|
||||
| `scripts/start.sh` | Startet Services für Umgebung |
|
||||
| `scripts/stop.sh` | Stoppt Services |
|
||||
| `scripts/promote.sh` | Promotet Code zwischen Branches |
|
||||
| `scripts/status.sh` | Zeigt aktuellen Status |
|
||||
|
||||
## Verifikation
|
||||
|
||||
Nach Setup prüfen:
|
||||
|
||||
```bash
|
||||
# Status anzeigen
|
||||
./scripts/status.sh
|
||||
|
||||
# Branches prüfen
|
||||
git branch -v
|
||||
|
||||
# Volumes prüfen
|
||||
docker volume ls | grep breakpilot
|
||||
```
|
||||
|
||||
## Verwandte Dokumentation
|
||||
|
||||
- [Secrets Management](./secrets-management.md) - Vault & Secrets
|
||||
- [DevSecOps](./devsecops.md) - CI/CD & Security
|
||||
- [System-Architektur](./system-architecture.md) - Gesamtarchitektur
|
||||
215
docs-src/architecture/mail-rbac-architecture.md
Normal file
215
docs-src/architecture/mail-rbac-architecture.md
Normal file
@@ -0,0 +1,215 @@
|
||||
# Mail-RBAC Architektur mit Mitarbeiter-Anonymisierung
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Status:** Architekturplanung
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Dieses Dokument beschreibt eine neuartige Architektur, die E-Mail, Kalender und Videokonferenzen mit rollenbasierter Zugriffskontrolle (RBAC) verbindet. Das Kernkonzept ermöglicht die **vollständige Anonymisierung von Mitarbeiterdaten** bei Verlassen des Unternehmens, während geschäftliche Kommunikationshistorie erhalten bleibt.
|
||||
|
||||
---
|
||||
|
||||
## 1. Das Problem
|
||||
|
||||
### Traditionelle E-Mail-Systeme
|
||||
```
|
||||
max.mustermann@firma.de → Person gebunden
|
||||
→ DSGVO: Daten müssen gelöscht werden
|
||||
→ Geschäftshistorie geht verloren
|
||||
```
|
||||
|
||||
### BreakPilot-Lösung: Rollenbasierte E-Mail
|
||||
```
|
||||
klassenlehrer.5a@schule.breakpilot.app → Rolle gebunden
|
||||
→ Person kann anonymisiert werden
|
||||
→ Kommunikationshistorie bleibt erhalten
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Architektur-Übersicht
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ BreakPilot Groupware │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ Webmail │ │ Kalender │ │ Jitsi │ │
|
||||
│ │ (SOGo) │ │ (SOGo) │ │ Meeting │ │
|
||||
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
|
||||
│ │ │ │ │
|
||||
│ └────────────────┼────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌───────────┴───────────┐ │
|
||||
│ │ RBAC-Mail-Bridge │ ◄─── Neue Komponente │
|
||||
│ │ (Python/Go) │ │
|
||||
│ └───────────┬───────────┘ │
|
||||
│ │ │
|
||||
│ ┌─────────────────────┼─────────────────────┐ │
|
||||
│ │ │ │ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ ┌──────────┐ ┌──────────────┐ ┌────────────┐ │
|
||||
│ │PostgreSQL│ │ Mail Server │ │ MinIO │ │
|
||||
│ │(RBAC DB) │ │ (Stalwart) │ │ (Backups) │ │
|
||||
│ └──────────┘ └──────────────┘ └────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Komponenten-Auswahl
|
||||
|
||||
### 3.1 E-Mail Server: Stalwart Mail Server
|
||||
|
||||
**Empfehlung:** [Stalwart Mail Server](https://stalw.art/)
|
||||
|
||||
| Kriterium | Bewertung |
|
||||
|-----------|-----------|
|
||||
| Lizenz | AGPL-3.0 (Open Source) |
|
||||
| Sprache | Rust (performant, sicher) |
|
||||
| Features | IMAP, SMTP, JMAP, WebSocket |
|
||||
| Kalender | CalDAV integriert |
|
||||
| Kontakte | CardDAV integriert |
|
||||
| Spam/Virus | Integriert |
|
||||
| API | REST API für Administration |
|
||||
|
||||
### 3.2 Webmail-Client: SOGo oder Roundcube
|
||||
|
||||
**Option A: SOGo** (empfohlen)
|
||||
- Lizenz: GPL-2.0 / LGPL-2.1
|
||||
- Kalender, Kontakte, Mail in einem
|
||||
- ActiveSync Support
|
||||
- Outlook-ähnliche Oberfläche
|
||||
|
||||
**Option B: Roundcube**
|
||||
- Lizenz: GPL-3.0
|
||||
- Nur Webmail
|
||||
- Benötigt separaten Kalender
|
||||
|
||||
---
|
||||
|
||||
## 4. Anonymisierungs-Workflow
|
||||
|
||||
```
|
||||
Mitarbeiter kündigt
|
||||
│
|
||||
▼
|
||||
┌───────────────────────────┐
|
||||
│ 1. Functional Mailboxes │
|
||||
│ → Neu zuweisen oder │
|
||||
│ → Deaktivieren │
|
||||
└───────────┬───────────────┘
|
||||
│
|
||||
▼
|
||||
┌───────────────────────────┐
|
||||
│ 2. Personal Email Account │
|
||||
│ → Anonymisieren: │
|
||||
│ max.mustermann@... │
|
||||
│ → mitarbeiter_a7x2@... │
|
||||
└───────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌───────────────────────────┐
|
||||
│ 3. Users-Tabelle │
|
||||
│ → Pseudonymisieren: │
|
||||
│ name: "Max Mustermann" │
|
||||
│ → "Ehem. Mitarbeiter" │
|
||||
└───────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌───────────────────────────┐
|
||||
│ 4. Mailbox Assignments │
|
||||
│ → Bleiben für Audit │
|
||||
│ → User-Referenz zeigt │
|
||||
│ auf anonymisierte │
|
||||
│ Daten │
|
||||
└───────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌───────────────────────────┐
|
||||
│ 5. E-Mail-Archiv │
|
||||
│ → Header anonymisieren │
|
||||
│ → Inhalte optional │
|
||||
│ löschen │
|
||||
└───────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Unified Inbox Implementation
|
||||
|
||||
### Implementierte Komponenten
|
||||
|
||||
Die Unified Inbox wurde als Teil des klausur-service implementiert:
|
||||
|
||||
| Komponente | Pfad | Beschreibung |
|
||||
|------------|------|--------------|
|
||||
| **Models** | `klausur-service/backend/mail/models.py` | Pydantic Models für Accounts, E-Mails, Tasks |
|
||||
| **Database** | `klausur-service/backend/mail/mail_db.py` | PostgreSQL-Operationen mit asyncpg |
|
||||
| **Credentials** | `klausur-service/backend/mail/credentials.py` | Vault-Integration für IMAP/SMTP-Passwörter |
|
||||
| **Aggregator** | `klausur-service/backend/mail/aggregator.py` | Multi-Account IMAP Sync |
|
||||
| **AI Service** | `klausur-service/backend/mail/ai_service.py` | KI-Analyse (Absender, Fristen, Kategorien) |
|
||||
| **Task Service** | `klausur-service/backend/mail/task_service.py` | Arbeitsvorrat-Management |
|
||||
| **API** | `klausur-service/backend/mail/api.py` | FastAPI Router mit 30+ Endpoints |
|
||||
|
||||
### API-Endpoints (Port 8086)
|
||||
|
||||
```
|
||||
# Account Management
|
||||
POST /api/v1/mail/accounts - Neues Konto hinzufügen
|
||||
GET /api/v1/mail/accounts - Alle Konten auflisten
|
||||
DELETE /api/v1/mail/accounts/{id} - Konto entfernen
|
||||
POST /api/v1/mail/accounts/{id}/test - Verbindung testen
|
||||
|
||||
# Unified Inbox
|
||||
GET /api/v1/mail/inbox - Aggregierte Inbox
|
||||
GET /api/v1/mail/inbox/{id} - Einzelne E-Mail
|
||||
POST /api/v1/mail/send - E-Mail senden
|
||||
|
||||
# KI-Features
|
||||
POST /api/v1/mail/analyze/{id} - E-Mail analysieren
|
||||
GET /api/v1/mail/suggestions/{id} - Antwortvorschläge
|
||||
|
||||
# Arbeitsvorrat
|
||||
GET /api/v1/mail/tasks - Alle Tasks
|
||||
POST /api/v1/mail/tasks - Manuelle Task erstellen
|
||||
PATCH /api/v1/mail/tasks/{id} - Task aktualisieren
|
||||
GET /api/v1/mail/tasks/dashboard - Dashboard-Statistiken
|
||||
```
|
||||
|
||||
### Niedersachsen-spezifische Absendererkennung
|
||||
|
||||
```python
|
||||
KNOWN_AUTHORITIES_NI = {
|
||||
"@mk.niedersachsen.de": "Kultusministerium Niedersachsen",
|
||||
"@rlsb.de": "Regionales Landesamt für Schule und Bildung",
|
||||
"@landesschulbehoerde-nds.de": "Landesschulbehörde",
|
||||
"@nibis.de": "NiBiS",
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Lizenz-Übersicht
|
||||
|
||||
| Komponente | Lizenz | Kommerzielle Nutzung | Veröffentlichungspflicht |
|
||||
|------------|--------|---------------------|-------------------------|
|
||||
| Stalwart Mail | AGPL-3.0 | Ja | Nur bei Code-Änderungen |
|
||||
| SOGo | GPL-2.0/LGPL | Ja | Nur bei Code-Änderungen |
|
||||
| Roundcube | GPL-3.0 | Ja | Nur bei Code-Änderungen |
|
||||
| RBAC-Mail-Bridge | Eigene | N/A | Kann proprietär bleiben |
|
||||
| BreakPilot Backend | Eigene | N/A | Proprietär |
|
||||
|
||||
---
|
||||
|
||||
## 7. Referenzen
|
||||
|
||||
- [Stalwart Mail Server](https://stalw.art/)
|
||||
- [SOGo Groupware](https://www.sogo.nu/)
|
||||
- [Roundcube Webmail](https://roundcube.net/)
|
||||
- [CalDAV Standard](https://tools.ietf.org/html/rfc4791)
|
||||
- [DSGVO Art. 17 - Recht auf Löschung](https://dsgvo-gesetz.de/art-17-dsgvo/)
|
||||
286
docs-src/architecture/multi-agent.md
Normal file
286
docs-src/architecture/multi-agent.md
Normal file
@@ -0,0 +1,286 @@
|
||||
# Multi-Agent Architektur - Entwicklerdokumentation
|
||||
|
||||
**Status:** Implementiert
|
||||
**Modul:** `/agent-core/`
|
||||
|
||||
---
|
||||
|
||||
## 1. Übersicht
|
||||
|
||||
Die Multi-Agent-Architektur erweitert Breakpilot um ein verteiltes Agent-System basierend auf Mission Control Konzepten.
|
||||
|
||||
### Kernkomponenten
|
||||
|
||||
| Komponente | Pfad | Beschreibung |
|
||||
|------------|------|--------------|
|
||||
| Session Management | `/agent-core/sessions/` | Lifecycle & Recovery |
|
||||
| Shared Brain | `/agent-core/brain/` | Langzeit-Gedächtnis |
|
||||
| Orchestrator | `/agent-core/orchestrator/` | Koordination |
|
||||
| SOUL Files | `/agent-core/soul/` | Agent-Persönlichkeiten |
|
||||
|
||||
---
|
||||
|
||||
## 2. Agent-Typen
|
||||
|
||||
| Agent | Aufgabe | SOUL-Datei |
|
||||
|-------|---------|------------|
|
||||
| **TutorAgent** | Lernbegleitung, Fragen beantworten | `tutor-agent.soul.md` |
|
||||
| **GraderAgent** | Klausur-Korrektur, Bewertung | `grader-agent.soul.md` |
|
||||
| **QualityJudge** | BQAS Qualitätsprüfung | `quality-judge.soul.md` |
|
||||
| **AlertAgent** | Monitoring, Benachrichtigungen | `alert-agent.soul.md` |
|
||||
| **Orchestrator** | Task-Koordination | `orchestrator.soul.md` |
|
||||
|
||||
---
|
||||
|
||||
## 3. Wichtige Dateien
|
||||
|
||||
### Session Management
|
||||
```
|
||||
agent-core/sessions/
|
||||
├── session_manager.py # AgentSession, SessionManager, SessionState
|
||||
├── heartbeat.py # HeartbeatMonitor, HeartbeatClient
|
||||
└── checkpoint.py # CheckpointManager
|
||||
```
|
||||
|
||||
### Shared Brain
|
||||
```
|
||||
agent-core/brain/
|
||||
├── memory_store.py # MemoryStore, Memory (mit TTL)
|
||||
├── context_manager.py # ConversationContext, ContextManager
|
||||
└── knowledge_graph.py # KnowledgeGraph, Entity, Relationship
|
||||
```
|
||||
|
||||
### Orchestrator
|
||||
```
|
||||
agent-core/orchestrator/
|
||||
├── message_bus.py # MessageBus, AgentMessage, MessagePriority
|
||||
├── supervisor.py # AgentSupervisor, AgentInfo, AgentStatus
|
||||
└── task_router.py # TaskRouter, RoutingRule, RoutingResult
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Datenbank-Schema
|
||||
|
||||
Die Migration befindet sich in:
|
||||
`/backend/migrations/add_agent_core_tables.sql`
|
||||
|
||||
### Tabellen
|
||||
|
||||
1. **agent_sessions** - Session-Daten mit Checkpoints
|
||||
2. **agent_memory** - Langzeit-Gedächtnis mit TTL
|
||||
3. **agent_messages** - Audit-Trail für Inter-Agent Kommunikation
|
||||
|
||||
### Helper-Funktionen
|
||||
|
||||
```sql
|
||||
-- Abgelaufene Memories bereinigen
|
||||
SELECT cleanup_expired_agent_memory();
|
||||
|
||||
-- Inaktive Sessions bereinigen
|
||||
SELECT cleanup_stale_agent_sessions(48); -- 48 Stunden
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Integration Voice-Service
|
||||
|
||||
Der `EnhancedTaskOrchestrator` erweitert den bestehenden `TaskOrchestrator`:
|
||||
|
||||
```python
|
||||
# voice-service/services/enhanced_task_orchestrator.py
|
||||
|
||||
from agent_core.sessions import SessionManager
|
||||
from agent_core.orchestrator import MessageBus
|
||||
|
||||
class EnhancedTaskOrchestrator(TaskOrchestrator):
|
||||
# Nutzt Session-Checkpoints für Recovery
|
||||
# Routet komplexe Tasks an spezialisierte Agents
|
||||
# Führt Quality-Checks via BQAS durch
|
||||
```
|
||||
|
||||
**Wichtig:** Der Enhanced Orchestrator ist abwärtskompatibel und kann parallel zum Original verwendet werden.
|
||||
|
||||
---
|
||||
|
||||
## 6. Integration BQAS
|
||||
|
||||
Der `QualityJudgeAgent` integriert BQAS mit dem Multi-Agent-System:
|
||||
|
||||
```python
|
||||
# voice-service/bqas/quality_judge_agent.py
|
||||
|
||||
from bqas.judge import LLMJudge
|
||||
from agent_core.orchestrator import MessageBus
|
||||
|
||||
class QualityJudgeAgent:
|
||||
# Wertet Responses in Echtzeit aus
|
||||
# Nutzt Memory für konsistente Bewertungen
|
||||
# Empfängt Evaluierungs-Requests via Message Bus
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Code-Beispiele
|
||||
|
||||
### Session erstellen
|
||||
|
||||
```python
|
||||
from agent_core.sessions import SessionManager
|
||||
|
||||
manager = SessionManager(redis_client=redis, db_pool=pool)
|
||||
session = await manager.create_session(
|
||||
agent_type="tutor-agent",
|
||||
user_id="user-123"
|
||||
)
|
||||
```
|
||||
|
||||
### Memory speichern
|
||||
|
||||
```python
|
||||
from agent_core.brain import MemoryStore
|
||||
|
||||
store = MemoryStore(redis_client=redis, db_pool=pool)
|
||||
await store.remember(
|
||||
key="student:123:progress",
|
||||
value={"level": 5, "score": 85},
|
||||
agent_id="tutor-agent",
|
||||
ttl_days=30
|
||||
)
|
||||
```
|
||||
|
||||
### Nachricht senden
|
||||
|
||||
```python
|
||||
from agent_core.orchestrator import MessageBus, AgentMessage
|
||||
|
||||
bus = MessageBus(redis_client=redis)
|
||||
await bus.publish(AgentMessage(
|
||||
sender="orchestrator",
|
||||
receiver="grader-agent",
|
||||
message_type="grade_request",
|
||||
payload={"exam_id": "exam-1"}
|
||||
))
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Tests ausführen
|
||||
|
||||
```bash
|
||||
# Alle Agent-Core Tests
|
||||
cd agent-core && pytest -v
|
||||
|
||||
# Mit Coverage-Report
|
||||
pytest --cov=. --cov-report=html
|
||||
|
||||
# Einzelne Module
|
||||
pytest tests/test_session_manager.py -v
|
||||
pytest tests/test_message_bus.py -v
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Deployment-Schritte
|
||||
|
||||
### 1. Migration ausführen
|
||||
|
||||
```bash
|
||||
psql -h localhost -U breakpilot -d breakpilot \
|
||||
-f backend/migrations/add_agent_core_tables.sql
|
||||
```
|
||||
|
||||
### 2. Voice-Service aktualisieren
|
||||
|
||||
```bash
|
||||
# Sync zu Server
|
||||
rsync -avz --exclude 'node_modules' --exclude '.git' \
|
||||
/path/to/breakpilot-pwa/ server:/path/to/breakpilot-pwa/
|
||||
|
||||
# Container neu bauen
|
||||
docker compose build --no-cache voice-service
|
||||
|
||||
# Starten
|
||||
docker compose up -d voice-service
|
||||
```
|
||||
|
||||
### 3. Verifizieren
|
||||
|
||||
```bash
|
||||
# Session-Tabelle prüfen
|
||||
psql -c "SELECT COUNT(*) FROM agent_sessions;"
|
||||
|
||||
# Memory-Tabelle prüfen
|
||||
psql -c "SELECT COUNT(*) FROM agent_memory;"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Monitoring
|
||||
|
||||
### Metriken
|
||||
|
||||
| Metrik | Beschreibung |
|
||||
|--------|--------------|
|
||||
| `agent_session_count` | Anzahl aktiver Sessions |
|
||||
| `agent_heartbeat_delay_ms` | Zeit seit letztem Heartbeat |
|
||||
| `agent_message_latency_ms` | Nachrichtenlatenz |
|
||||
| `agent_memory_count` | Gespeicherte Memories |
|
||||
| `agent_routing_success_rate` | Erfolgreiche Routings |
|
||||
|
||||
### Health-Check-Endpunkte
|
||||
|
||||
```
|
||||
GET /api/v1/agents/health # Supervisor Status
|
||||
GET /api/v1/agents/sessions # Aktive Sessions
|
||||
GET /api/v1/agents/memory/stats # Memory-Statistiken
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Troubleshooting
|
||||
|
||||
### Problem: Session nicht gefunden
|
||||
|
||||
1. Prüfen ob Valkey läuft: `redis-cli ping`
|
||||
2. Session-Timeout prüfen (default 24h)
|
||||
3. Heartbeat-Status checken
|
||||
|
||||
### Problem: Message Bus Timeout
|
||||
|
||||
1. Redis Pub/Sub Status prüfen
|
||||
2. Ziel-Agent registriert?
|
||||
3. Timeout erhöhen (default 30s)
|
||||
|
||||
### Problem: Memory nicht gefunden
|
||||
|
||||
1. Namespace korrekt?
|
||||
2. TTL abgelaufen?
|
||||
3. Cleanup-Job gelaufen?
|
||||
|
||||
---
|
||||
|
||||
## 12. Erweiterungen
|
||||
|
||||
### Neuen Agent hinzufügen
|
||||
|
||||
1. SOUL-Datei erstellen in `/agent-core/soul/`
|
||||
2. Routing-Regel in `task_router.py` hinzufügen
|
||||
3. Handler beim Supervisor registrieren
|
||||
4. Tests schreiben
|
||||
|
||||
### Neuen Memory-Typ hinzufügen
|
||||
|
||||
1. Key-Schema definieren (z.B. `student:*:progress`)
|
||||
2. TTL festlegen
|
||||
3. Access-Pattern dokumentieren
|
||||
|
||||
---
|
||||
|
||||
## 13. Referenzen
|
||||
|
||||
- **Agent-Core README:** `/agent-core/README.md`
|
||||
- **Migration:** `/backend/migrations/add_agent_core_tables.sql`
|
||||
- **Voice-Service Integration:** `/voice-service/services/enhanced_task_orchestrator.py`
|
||||
- **BQAS Integration:** `/voice-service/bqas/quality_judge_agent.py`
|
||||
- **Tests:** `/agent-core/tests/`
|
||||
251
docs-src/architecture/secrets-management.md
Normal file
251
docs-src/architecture/secrets-management.md
Normal file
@@ -0,0 +1,251 @@
|
||||
# BreakPilot Secrets Management
|
||||
|
||||
## Uebersicht
|
||||
|
||||
BreakPilot verwendet **HashiCorp Vault** als zentrales Secrets-Management-System.
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ SECRETS MANAGEMENT │
|
||||
│ │
|
||||
│ ┌────────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ HashiCorp Vault │ │
|
||||
│ │ Port 8200 │ │
|
||||
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │ │
|
||||
│ │ │ KV v2 Engine │ │ AppRole Auth │ │ Audit Logging │ │ │
|
||||
│ │ │ secret/ │ │ Token Auth │ │ Verschluesselung │ │ │
|
||||
│ │ └──────────────┘ └──────────────┘ └──────────────────────────┘ │ │
|
||||
│ └────────────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌─────────────────────┼─────────────────────┐ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Python Backend │ │ Go Services │ │ Frontend │ │
|
||||
│ │ (hvac client) │ │ (vault-client) │ │ (via Backend) │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Warum Vault?
|
||||
|
||||
| Alternative | Nachteil |
|
||||
|-------------|----------|
|
||||
| Environment Variables | Keine Audit-Logs, keine Verschluesselung, keine Rotation |
|
||||
| Docker Secrets | Nur fuer Docker Swarm, keine zentrale Verwaltung |
|
||||
| AWS Secrets Manager | Cloud Lock-in, Kosten |
|
||||
| Kubernetes Secrets | Keine Verschluesselung by default, nur K8s |
|
||||
| **HashiCorp Vault** | Open Source (BSL 1.1), Self-Hosted, Enterprise Features |
|
||||
|
||||
## Architektur
|
||||
|
||||
### Secret-Hierarchie
|
||||
|
||||
```
|
||||
secret/breakpilot/
|
||||
├── api_keys/
|
||||
│ ├── anthropic # Anthropic Claude API Key
|
||||
│ ├── vast # vast.ai GPU API Key
|
||||
│ ├── stripe # Stripe Payment Key
|
||||
│ ├── stripe_webhook
|
||||
│ └── tavily # Tavily Search API Key
|
||||
├── database/
|
||||
│ ├── postgres # username, password, url
|
||||
│ └── synapse # Matrix Synapse DB
|
||||
├── auth/
|
||||
│ ├── jwt # secret, refresh_secret
|
||||
│ └── keycloak # client_secret
|
||||
├── communication/
|
||||
│ ├── matrix # access_token, db_password
|
||||
│ └── jitsi # app_secret, jicofo, jvb passwords
|
||||
├── storage/
|
||||
│ └── minio # access_key, secret_key
|
||||
└── infra/
|
||||
└── vast # api_key, instance_id, control_key
|
||||
```
|
||||
|
||||
### Python Integration
|
||||
|
||||
```python
|
||||
from secrets import get_secret
|
||||
|
||||
# Einzelnes Secret abrufen
|
||||
api_key = get_secret("ANTHROPIC_API_KEY")
|
||||
|
||||
# Mit Default-Wert
|
||||
debug = get_secret("DEBUG", default="false")
|
||||
|
||||
# Als Pflicht-Secret
|
||||
db_url = get_secret("DATABASE_URL", required=True)
|
||||
```
|
||||
|
||||
### Fallback-Reihenfolge
|
||||
|
||||
```
|
||||
1. HashiCorp Vault (wenn VAULT_ADDR gesetzt)
|
||||
↓ falls nicht verfuegbar
|
||||
2. Environment Variables
|
||||
↓ falls nicht gesetzt
|
||||
3. Docker Secrets (/run/secrets/)
|
||||
↓ falls nicht vorhanden
|
||||
4. Default-Wert (wenn angegeben)
|
||||
↓ sonst
|
||||
5. SecretNotFoundError (wenn required=True)
|
||||
```
|
||||
|
||||
## Setup
|
||||
|
||||
### Entwicklung (Dev Mode)
|
||||
|
||||
```bash
|
||||
# Vault starten (Dev Mode - NICHT fuer Produktion!)
|
||||
docker-compose -f docker-compose.vault.yml up -d vault
|
||||
|
||||
# Warten bis healthy
|
||||
docker-compose -f docker-compose.vault.yml up vault-init
|
||||
|
||||
# Environment setzen
|
||||
export VAULT_ADDR=http://localhost:8200
|
||||
export VAULT_TOKEN=breakpilot-dev-token
|
||||
```
|
||||
|
||||
### Secrets setzen
|
||||
|
||||
```bash
|
||||
# Anthropic API Key
|
||||
vault kv put secret/breakpilot/api_keys/anthropic value='sk-ant-api03-...'
|
||||
|
||||
# vast.ai Credentials
|
||||
vault kv put secret/breakpilot/infra/vast \
|
||||
api_key='xxx' \
|
||||
instance_id='123' \
|
||||
control_key='yyy'
|
||||
|
||||
# Database
|
||||
vault kv put secret/breakpilot/database/postgres \
|
||||
username='breakpilot' \
|
||||
password='supersecret' \
|
||||
url='postgres://breakpilot:supersecret@localhost:5432/breakpilot_db'
|
||||
```
|
||||
|
||||
### Secrets lesen
|
||||
|
||||
```bash
|
||||
# Liste aller Secrets
|
||||
vault kv list secret/breakpilot/
|
||||
|
||||
# Secret anzeigen
|
||||
vault kv get secret/breakpilot/api_keys/anthropic
|
||||
|
||||
# Nur den Wert
|
||||
vault kv get -field=value secret/breakpilot/api_keys/anthropic
|
||||
```
|
||||
|
||||
## Produktion
|
||||
|
||||
### AppRole Authentication
|
||||
|
||||
In Produktion verwenden Services AppRole statt Token-Auth:
|
||||
|
||||
```bash
|
||||
# 1. AppRole aktivieren (einmalig)
|
||||
vault auth enable approle
|
||||
|
||||
# 2. Policy erstellen
|
||||
vault policy write breakpilot-backend - <<EOF
|
||||
path "secret/data/breakpilot/*" {
|
||||
capabilities = ["read", "list"]
|
||||
}
|
||||
EOF
|
||||
|
||||
# 3. Role erstellen
|
||||
vault write auth/approle/role/breakpilot-backend \
|
||||
token_policies="breakpilot-backend" \
|
||||
token_ttl=1h \
|
||||
token_max_ttl=4h
|
||||
|
||||
# 4. Role-ID holen (fix)
|
||||
vault read -field=role_id auth/approle/role/breakpilot-backend/role-id
|
||||
|
||||
# 5. Secret-ID generieren (bei jedem Deploy neu)
|
||||
vault write -f auth/approle/role/breakpilot-backend/secret-id
|
||||
```
|
||||
|
||||
### Environment fuer Services
|
||||
|
||||
```bash
|
||||
# Docker-Compose / Kubernetes
|
||||
VAULT_ADDR=https://vault.breakpilot.app:8200
|
||||
VAULT_AUTH_METHOD=approle
|
||||
VAULT_ROLE_ID=<role-id>
|
||||
VAULT_SECRET_ID=<secret-id>
|
||||
VAULT_SECRETS_PATH=breakpilot
|
||||
```
|
||||
|
||||
## Sicherheits-Checkliste
|
||||
|
||||
### Muss erfuellt sein
|
||||
|
||||
- [ ] Keine echten Secrets in `.env` Dateien
|
||||
- [ ] `.env` in `.gitignore`
|
||||
- [ ] Vault im Sealed-State wenn nicht in Verwendung
|
||||
- [ ] TLS fuer Vault in Produktion
|
||||
- [ ] AppRole statt Token-Auth in Produktion
|
||||
- [ ] Audit-Logging aktiviert
|
||||
- [ ] Minimale Policies (Least Privilege)
|
||||
|
||||
### Sollte erfuellt sein
|
||||
|
||||
- [ ] Automatische Secret-Rotation
|
||||
- [ ] Separate Vault-Instanz fuer Produktion
|
||||
- [ ] HSM-basiertes Auto-Unseal
|
||||
- [ ] Disaster Recovery Plan
|
||||
|
||||
## Dateien
|
||||
|
||||
| Datei | Beschreibung |
|
||||
|-------|--------------|
|
||||
| `backend/secrets/__init__.py` | Secrets-Modul Exports |
|
||||
| `backend/secrets/vault_client.py` | Vault Client Implementation |
|
||||
| `docker-compose.vault.yml` | Vault Docker Configuration |
|
||||
| `vault/init-secrets.sh` | Entwicklungs-Secrets Initialisierung |
|
||||
| `vault/policies/` | Vault Policy Files |
|
||||
|
||||
## Fehlerbehebung
|
||||
|
||||
### Vault nicht erreichbar
|
||||
|
||||
```bash
|
||||
# Status pruefen
|
||||
vault status
|
||||
|
||||
# Falls sealed
|
||||
vault operator unseal <unseal-key>
|
||||
```
|
||||
|
||||
### Secret nicht gefunden
|
||||
|
||||
```bash
|
||||
# Pfad pruefen
|
||||
vault kv list secret/breakpilot/
|
||||
|
||||
# Cache leeren (Python)
|
||||
from secrets import get_secrets_manager
|
||||
get_secrets_manager().clear_cache()
|
||||
```
|
||||
|
||||
### Token abgelaufen
|
||||
|
||||
```bash
|
||||
# Neuen Token holen (AppRole)
|
||||
vault write auth/approle/login \
|
||||
role_id=$VAULT_ROLE_ID \
|
||||
secret_id=$VAULT_SECRET_ID
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Referenzen
|
||||
|
||||
- [HashiCorp Vault Documentation](https://developer.hashicorp.com/vault/docs)
|
||||
- [hvac Python Client](https://hvac.readthedocs.io/)
|
||||
- [Vault Best Practices](https://developer.hashicorp.com/vault/tutorials/recommended-patterns)
|
||||
311
docs-src/architecture/system-architecture.md
Normal file
311
docs-src/architecture/system-architecture.md
Normal file
@@ -0,0 +1,311 @@
|
||||
# BreakPilot PWA - System-Architektur
|
||||
|
||||
## Übersicht
|
||||
|
||||
BreakPilot ist eine modulare Bildungsplattform für Lehrkräfte mit folgenden Hauptkomponenten:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ Browser │
|
||||
│ ┌───────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Frontend (Studio UI) │ │
|
||||
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │ │
|
||||
│ │ │Dashboard │ │Worksheets│ │Correction│ │Letters/Companion │ │ │
|
||||
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────────────┘ │ │
|
||||
│ └───────────────────────────────────────────────────────────────┘ │
|
||||
└───────────────────────────┬─────────────────────────────────────────┘
|
||||
│ HTTP/REST
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ Python Backend (FastAPI) │
|
||||
│ Port 8000 │
|
||||
│ ┌────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ API Layer │ │
|
||||
│ │ /api/worksheets /api/corrections /api/letters /api/state │ │
|
||||
│ │ /api/school /api/certificates /api/messenger /api/jitsi │ │
|
||||
│ └────────────────────────────────────────────────────────────────┘ │
|
||||
│ ┌────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Service Layer │ │
|
||||
│ │ FileProcessor │ PDFService │ ContentGenerators │ StateEngine │ │
|
||||
│ └────────────────────────────────────────────────────────────────┘ │
|
||||
└───────────────────────────┬─────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────┼─────────────┐
|
||||
▼ ▼ ▼
|
||||
┌─────────────────┐ ┌───────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ Go Consent │ │ PostgreSQL │ │ LLM Gateway │ │ HashiCorp │
|
||||
│ Service │ │ Database │ │ (optional) │ │ Vault │
|
||||
│ Port 8081 │ │ Port 5432 │ │ │ │ Port 8200 │
|
||||
└─────────────────┘ └───────────────┘ └──────────────┘ └──────────────┘
|
||||
```
|
||||
|
||||
## Komponenten
|
||||
|
||||
### 1. Admin Frontend (Next.js Website)
|
||||
|
||||
Das **Admin Frontend** ist eine vollständige Next.js 15 Anwendung für Developer und Administratoren:
|
||||
|
||||
**Technologie:** Next.js 15, React 18, TypeScript, Tailwind CSS
|
||||
|
||||
**Container:** `breakpilot-pwa-website` auf **Port 3000**
|
||||
|
||||
**Verzeichnis:** `/website`
|
||||
|
||||
| Modul | Route | Beschreibung |
|
||||
|-------|-------|--------------|
|
||||
| Dashboard | `/admin` | Übersicht & Statistiken |
|
||||
| GPU Infrastruktur | `/admin/gpu` | vast.ai GPU Management |
|
||||
| Consent Verwaltung | `/admin/consent` | Rechtliche Dokumente & Versionen |
|
||||
| Datenschutzanfragen | `/admin/dsr` | DSGVO Art. 15-21 Anfragen |
|
||||
| DSMS | `/admin/dsms` | Datenschutz-Management-System |
|
||||
| Education Search | `/admin/edu-search` | Bildungsquellen & Crawler |
|
||||
| Personensuche | `/admin/staff-search` | Uni-Mitarbeiter & Publikationen |
|
||||
| Uni-Crawler | `/admin/uni-crawler` | Universitäts-Crawling Orchestrator |
|
||||
| LLM Vergleich | `/admin/llm-compare` | KI-Provider Vergleich |
|
||||
| PCA Platform | `/admin/pca-platform` | Bot-Erkennung & Monetarisierung |
|
||||
| Production Backlog | `/admin/backlog` | Go-Live Checkliste |
|
||||
| Developer Docs | `/admin/docs` | API & Architektur Dokumentation |
|
||||
| Kommunikation | `/admin/communication` | Matrix & Jitsi Monitoring |
|
||||
| **Security** | `/admin/security` | DevSecOps Dashboard, Scans, Findings |
|
||||
| **SBOM** | `/admin/sbom` | Software Bill of Materials |
|
||||
|
||||
### 2. Lehrer Frontend (Studio UI)
|
||||
|
||||
Das **Lehrer Frontend** ist ein Single-Page-Application-ähnliches System für Lehrkräfte, das in Python-Modulen organisiert ist:
|
||||
|
||||
| Modul | Datei | Beschreibung |
|
||||
|-------|-------|--------------|
|
||||
| Base | `frontend/modules/base.py` | TopBar, Sidebar, Theme, Login |
|
||||
| Dashboard | `frontend/modules/dashboard.py` | Übersichtsseite |
|
||||
| Worksheets | `frontend/modules/worksheets.py` | Lerneinheiten-Generator |
|
||||
| Correction | `frontend/modules/correction.py` | OCR-Klausurkorrektur |
|
||||
| Letters | `frontend/modules/letters.py` | Elternkommunikation |
|
||||
| Companion | `frontend/modules/companion.py` | Begleiter-Modus mit State Engine |
|
||||
| School | `frontend/modules/school.py` | Schulverwaltung |
|
||||
| Gradebook | `frontend/modules/gradebook.py` | Notenbuch |
|
||||
| ContentCreator | `frontend/modules/content_creator.py` | H5P Content Creator |
|
||||
| ContentFeed | `frontend/modules/content_feed.py` | Content Discovery |
|
||||
| Messenger | `frontend/modules/messenger.py` | Matrix Messenger |
|
||||
| Jitsi | `frontend/modules/jitsi.py` | Videokonferenzen |
|
||||
| **KlausurKorrektur** | `frontend/modules/klausur_korrektur.py` | **Abitur-Klausurkorrektur (15-Punkte-System)** |
|
||||
| **AbiturDocsAdmin** | `frontend/modules/abitur_docs_admin.py` | **Admin für Abitur-Dokumente (NiBiS)** |
|
||||
|
||||
Jedes Modul exportiert:
|
||||
- `get_css()` - CSS-Styles
|
||||
- `get_html()` - HTML-Template
|
||||
- `get_js()` - JavaScript-Logik
|
||||
|
||||
### 3. Python Backend (FastAPI)
|
||||
|
||||
#### API-Router
|
||||
|
||||
| Router | Präfix | Beschreibung |
|
||||
|--------|--------|--------------|
|
||||
| `worksheets_api` | `/api/worksheets` | Content-Generatoren (MC, Cloze, Mindmap, Quiz) |
|
||||
| `correction_api` | `/api/corrections` | OCR-Pipeline für Klausurkorrektur |
|
||||
| `letters_api` | `/api/letters` | Elternbriefe mit GFK-Integration |
|
||||
| `state_engine_api` | `/api/state` | Begleiter-Modus Phasen & Vorschläge |
|
||||
| `school_api` | `/api/school` | Schulverwaltung (Proxy zu school-service) |
|
||||
| `certificates_api` | `/api/certificates` | Zeugniserstellung |
|
||||
| `messenger_api` | `/api/messenger` | Matrix Messenger Integration |
|
||||
| `jitsi_api` | `/api/jitsi` | Jitsi Meeting-Einladungen |
|
||||
| `consent_api` | `/api/consent` | DSGVO Consent-Verwaltung |
|
||||
| `gdpr_api` | `/api/gdpr` | GDPR-Export |
|
||||
| **`klausur_korrektur_api`** | `/api/klausur-korrektur` | **Abitur-Klausuren (15-Punkte, Gutachten, Fairness)** |
|
||||
| **`abitur_docs_api`** | `/api/abitur-docs` | **NiBiS-Dokumentenverwaltung für RAG** |
|
||||
|
||||
#### Services
|
||||
|
||||
| Service | Datei | Beschreibung |
|
||||
|---------|-------|--------------|
|
||||
| FileProcessor | `services/file_processor.py` | OCR mit PaddleOCR |
|
||||
| PDFService | `services/pdf_service.py` | PDF-Generierung |
|
||||
| ContentGenerators | `services/content_generators/` | MC, Cloze, Mindmap, Quiz |
|
||||
| StateEngine | `state_engine/` | Phasen-Management & Antizipation |
|
||||
|
||||
### 4. Klausur-Korrektur System (Abitur)
|
||||
|
||||
Das Klausur-Korrektur-System implementiert die vollständige Abitur-Bewertungspipeline:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ Klausur-Korrektur Modul │
|
||||
│ │
|
||||
│ ┌─────────────┐ ┌──────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Modus-Wahl │───►│ Text-Quellen & │───►│ Erwartungs- │ │
|
||||
│ │ LandesAbi/ │ │ Rights-Gate │ │ horizont │ │
|
||||
│ │ Vorabitur │ └──────────────────┘ └─────────────────┘ │
|
||||
│ └─────────────┘ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Schülerarbeiten-Pipeline │ │
|
||||
│ │ Upload → OCR → KI-Bewertung → Gutachten → 15-Punkte-Note │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌────────────────────┐ ┌──────────────────────────────────┐ │
|
||||
│ │ Erst-/Zweitprüfer │───►│ Fairness-Analyse & PDF-Export │ │
|
||||
│ └────────────────────┘ └──────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
#### 15-Punkte-Notensystem
|
||||
|
||||
Das System verwendet den deutschen Abitur-Notenschlüssel:
|
||||
|
||||
| Punkte | Prozent | Note |
|
||||
|--------|---------|------|
|
||||
| 15-13 | 95-85% | 1+/1/1- |
|
||||
| 12-10 | 80-70% | 2+/2/2- |
|
||||
| 9-7 | 65-55% | 3+/3/3- |
|
||||
| 6-4 | 50-40% | 4+/4/4- |
|
||||
| 3-1 | 33-20% | 5+/5/5- |
|
||||
| 0 | <20% | 6 |
|
||||
|
||||
#### Bewertungskriterien
|
||||
|
||||
| Kriterium | Gewicht | Beschreibung |
|
||||
|-----------|---------|--------------|
|
||||
| Rechtschreibung | 15% | Orthografie |
|
||||
| Grammatik | 15% | Grammatik & Syntax |
|
||||
| **Inhalt** | **40%** | Inhaltliche Qualität (höchste Gewichtung) |
|
||||
| Struktur | 15% | Aufbau & Gliederung |
|
||||
| Stil | 15% | Ausdruck & Stil |
|
||||
|
||||
### 5. Go Consent Service
|
||||
|
||||
Verwaltet DSGVO-Einwilligungen:
|
||||
|
||||
```
|
||||
consent-service/
|
||||
├── cmd/server/ # Main entry point
|
||||
├── internal/
|
||||
│ ├── handlers/ # HTTP Handler
|
||||
│ ├── services/ # Business Logic
|
||||
│ ├── models/ # Data Models
|
||||
│ └── middleware/ # Auth Middleware
|
||||
└── migrations/ # SQL Migrations
|
||||
```
|
||||
|
||||
### 6. LLM Gateway (Optional)
|
||||
|
||||
Wenn `LLM_GATEWAY_ENABLED=true`:
|
||||
|
||||
```
|
||||
llm_gateway/
|
||||
├── routes/
|
||||
│ ├── chat.py # Chat-Completion API
|
||||
│ ├── communication.py # GFK-Validierung
|
||||
│ ├── edu_search_seeds.py # Bildungssuche
|
||||
│ └── legal_crawler.py # Schulgesetz-Crawler
|
||||
└── services/
|
||||
└── communication_service.py
|
||||
```
|
||||
|
||||
## Datenfluss
|
||||
|
||||
### Worksheet-Generierung
|
||||
|
||||
```
|
||||
User Input → Frontend (worksheets.py)
|
||||
↓
|
||||
POST /api/worksheets/generate/multiple-choice
|
||||
↓
|
||||
worksheets_api.py → MCGenerator (services/content_generators/)
|
||||
↓
|
||||
Optional: LLM für erweiterte Generierung
|
||||
↓
|
||||
Response: WorksheetContent → Frontend rendert Ergebnis
|
||||
```
|
||||
|
||||
### Klausurkorrektur
|
||||
|
||||
```
|
||||
File Upload → Frontend (correction.py)
|
||||
↓
|
||||
POST /api/corrections/ (erstellen)
|
||||
POST /api/corrections/{id}/upload (Datei)
|
||||
↓
|
||||
Background Task: OCR via FileProcessor
|
||||
↓
|
||||
Poll GET /api/corrections/{id} bis status="ocr_complete"
|
||||
↓
|
||||
POST /api/corrections/{id}/analyze
|
||||
↓
|
||||
Review Interface → PUT /api/corrections/{id} (Anpassungen)
|
||||
↓
|
||||
GET /api/corrections/{id}/export-pdf
|
||||
```
|
||||
|
||||
## Sicherheit
|
||||
|
||||
### Authentifizierung & Autorisierung
|
||||
|
||||
BreakPilot verwendet einen **Hybrid-Ansatz**:
|
||||
|
||||
| Schicht | Komponente | Beschreibung |
|
||||
|---------|------------|--------------|
|
||||
| **Authentifizierung** | Keycloak (Prod) / Lokales JWT (Dev) | Token-Validierung via JWKS oder HS256 |
|
||||
| **Autorisierung** | rbac.py (Eigenentwicklung) | Domaenenspezifische Berechtigungen |
|
||||
|
||||
Siehe: [Auth-System](auth-system.md)
|
||||
|
||||
### Basis-Rollen
|
||||
|
||||
| Rolle | Beschreibung |
|
||||
|-------|--------------|
|
||||
| `user` | Normaler Benutzer |
|
||||
| `teacher` / `lehrer` | Lehrkraft |
|
||||
| `admin` | Administrator |
|
||||
| `data_protection_officer` | Datenschutzbeauftragter |
|
||||
|
||||
### Erweiterte Rollen (rbac.py)
|
||||
|
||||
15+ domaenenspezifische Rollen fuer Klausurkorrektur und Zeugnisse:
|
||||
- `erstkorrektor`, `zweitkorrektor`, `drittkorrektor`
|
||||
- `klassenlehrer`, `fachlehrer`, `fachvorsitz`
|
||||
- `schulleitung`, `zeugnisbeauftragter`, `sekretariat`
|
||||
|
||||
### Sicherheitsfeatures
|
||||
|
||||
- JWT-basierte Authentifizierung (RS256/HS256)
|
||||
- CORS konfiguriert für Frontend-Zugriff
|
||||
- DSGVO-konformes Consent-Management
|
||||
- **HashiCorp Vault** fuer Secrets-Management (keine hardcodierten Secrets)
|
||||
- Bundesland-spezifische Policy-Sets
|
||||
- **DevSecOps Pipeline** mit automatisierten Security-Scans (SAST, SCA, Secrets Detection)
|
||||
|
||||
Siehe:
|
||||
- [Secrets Management](secrets-management.md)
|
||||
- [DevSecOps](devsecops.md)
|
||||
|
||||
## Deployment
|
||||
|
||||
```yaml
|
||||
services:
|
||||
backend:
|
||||
build: ./backend
|
||||
ports: ["8000:8000"]
|
||||
environment:
|
||||
- DATABASE_URL=postgresql://...
|
||||
- LLM_GATEWAY_ENABLED=false
|
||||
|
||||
consent-service:
|
||||
build: ./consent-service
|
||||
ports: ["8081:8081"]
|
||||
|
||||
postgres:
|
||||
image: postgres:15
|
||||
volumes:
|
||||
- pgdata:/var/lib/postgresql/data
|
||||
```
|
||||
|
||||
## Erweiterung
|
||||
|
||||
Neues Frontend-Modul hinzufügen:
|
||||
|
||||
1. Modul erstellen: `frontend/modules/new_module.py`
|
||||
2. Klasse mit `get_css()`, `get_html()`, `get_js()` implementieren
|
||||
3. In `frontend/modules/__init__.py` importieren und exportieren
|
||||
4. Optional: Zugehörige API in `new_module_api.py` erstellen
|
||||
5. In `main.py` Router registrieren
|
||||
169
docs-src/architecture/zeugnis-system.md
Normal file
169
docs-src/architecture/zeugnis-system.md
Normal file
@@ -0,0 +1,169 @@
|
||||
# Zeugnis-System - Architecture Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
The Zeugnis (Certificate) System enables schools to generate official school certificates with grades, attendance data, and remarks. It extends the existing School-Service with comprehensive grade management and certificate generation workflows.
|
||||
|
||||
## Architecture Diagram
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Python Backend (Port 8000) │
|
||||
│ backend/frontend/modules/school.py │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────┐ │
|
||||
│ │ panel-school-certificates │ │
|
||||
│ │ - Klassenauswahl │ │
|
||||
│ │ - Notenspiegel │ │
|
||||
│ │ - Zeugnis-Wizard (5 Steps) │ │
|
||||
│ │ - Workflow-Status │ │
|
||||
│ └─────────────────────────────────┘ │
|
||||
└──────────────────┬──────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────────────────────┐
|
||||
│ School-Service (Go, Port 8084) │
|
||||
├─────────────────────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────────────────┐ │
|
||||
│ │ Grade Handlers │ │ Statistics Handlers │ │ Certificate Handlers │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ GetClassGrades │ │ GetClassStatistics │ │ GetCertificateTemplates │ │
|
||||
│ │ GetStudentGrades │ │ GetSubjectStatistics│ │ GetClassCertificates │ │
|
||||
│ │ UpdateOralGrade │ │ GetStudentStatistics│ │ GenerateCertificate │ │
|
||||
│ │ CalculateFinalGrades│ │ GetNotenspiegel │ │ BulkGenerateCertificates │ │
|
||||
│ │ LockFinalGrade │ │ │ │ FinalizeCertificate │ │
|
||||
│ │ UpdateGradeWeights │ │ │ │ GetCertificatePDF │ │
|
||||
│ └─────────────────────┘ └─────────────────────┘ └─────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────┐
|
||||
│ PostgreSQL Database │
|
||||
│ │
|
||||
│ Tables: │
|
||||
│ - grade_overview │
|
||||
│ - exam_results │
|
||||
│ - students │
|
||||
│ - classes │
|
||||
│ - subjects │
|
||||
│ - certificates │
|
||||
│ - attendance │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Zeugnis Workflow (Role Chain)
|
||||
|
||||
The certificate workflow follows a strict approval chain from subject teachers to school principal:
|
||||
|
||||
```
|
||||
┌──────────────────┐ ┌──────────────────┐ ┌────────────────────────┐ ┌────────────────────┐ ┌──────────────────┐
|
||||
│ FACHLEHRER │───▶│ KLASSENLEHRER │───▶│ ZEUGNISBEAUFTRAGTER │───▶│ SCHULLEITUNG │───▶│ SEKRETARIAT │
|
||||
│ (Subject │ │ (Class │ │ (Certificate │ │ (Principal) │ │ (Secretary) │
|
||||
│ Teacher) │ │ Teacher) │ │ Coordinator) │ │ │ │ │
|
||||
└──────────────────┘ └──────────────────┘ └────────────────────────┘ └────────────────────┘ └──────────────────┘
|
||||
│ │ │ │ │
|
||||
▼ ▼ ▼ ▼ ▼
|
||||
Grades Entry Approve Quality Check Sign-off & Lock Print & Archive
|
||||
(Oral/Written) Grades & Review
|
||||
```
|
||||
|
||||
### Workflow States
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ DRAFT │────▶│ SUBMITTED │────▶│ REVIEWED │────▶│ SIGNED │────▶│ PRINTED │
|
||||
│ (Entwurf) │ │ (Eingereicht)│ │ (Geprueft) │ │(Unterzeichnet) │ (Gedruckt) │
|
||||
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
|
||||
│ │ │ │
|
||||
▼ ▼ ▼ ▼
|
||||
Fachlehrer Klassenlehrer Zeugnisbeauftragter Schulleitung
|
||||
```
|
||||
|
||||
## RBAC Integration
|
||||
|
||||
### Certificate-Related Roles
|
||||
|
||||
| Role | German | Description |
|
||||
|------|--------|-------------|
|
||||
| `FACHLEHRER` | Fachlehrer | Subject teacher - enters grades |
|
||||
| `KLASSENLEHRER` | Klassenlehrer | Class teacher - approves class grades |
|
||||
| `ZEUGNISBEAUFTRAGTER` | Zeugnisbeauftragter | Certificate coordinator - quality control |
|
||||
| `SCHULLEITUNG` | Schulleitung | Principal - final sign-off |
|
||||
| `SEKRETARIAT` | Sekretariat | Secretary - printing & archiving |
|
||||
|
||||
### Certificate Resource Types
|
||||
|
||||
| ResourceType | Description |
|
||||
|--------------|-------------|
|
||||
| `ZEUGNIS` | Final certificate document |
|
||||
| `ZEUGNIS_VORLAGE` | Certificate template (per Bundesland) |
|
||||
| `ZEUGNIS_ENTWURF` | Draft certificate (before approval) |
|
||||
| `FACHNOTE` | Subject grade |
|
||||
| `KOPFNOTE` | Head grade (Arbeits-/Sozialverhalten) |
|
||||
| `BEMERKUNG` | Certificate remarks |
|
||||
| `STATISTIK` | Class/subject statistics |
|
||||
| `NOTENSPIEGEL` | Grade distribution chart |
|
||||
|
||||
## German Grading System
|
||||
|
||||
| Grade | Meaning | Points |
|
||||
|-------|---------|--------|
|
||||
| 1 | sehr gut (excellent) | 15-13 |
|
||||
| 2 | gut (good) | 12-10 |
|
||||
| 3 | befriedigend (satisfactory) | 9-7 |
|
||||
| 4 | ausreichend (adequate) | 6-4 |
|
||||
| 5 | mangelhaft (poor) | 3-1 |
|
||||
| 6 | ungenuegend (inadequate) | 0 |
|
||||
|
||||
### Grade Calculation
|
||||
|
||||
```
|
||||
Final Grade = (Written Weight * Written Avg) + (Oral Weight * Oral Avg)
|
||||
|
||||
Default weights:
|
||||
- Written (Klassenarbeiten): 50%
|
||||
- Oral (muendliche Note): 50%
|
||||
|
||||
Customizable per subject/student via UpdateGradeWeights endpoint.
|
||||
```
|
||||
|
||||
## API Routes (School-Service)
|
||||
|
||||
### Grade Management
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/v1/school/grades/:classId` | Get class grades |
|
||||
| GET | `/api/v1/school/grades/student/:studentId` | Get student grades |
|
||||
| PUT | `/api/v1/school/grades/:studentId/:subjectId/oral` | Update oral grade |
|
||||
| POST | `/api/v1/school/grades/calculate` | Calculate final grades |
|
||||
| PUT | `/api/v1/school/grades/:studentId/:subjectId/lock` | Lock final grade |
|
||||
|
||||
### Statistics
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/v1/school/statistics/:classId` | Class statistics |
|
||||
| GET | `/api/v1/school/statistics/:classId/subject/:subjectId` | Subject statistics |
|
||||
| GET | `/api/v1/school/statistics/student/:studentId` | Student statistics |
|
||||
| GET | `/api/v1/school/statistics/:classId/notenspiegel` | Grade distribution |
|
||||
|
||||
### Certificates
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/v1/school/certificates/templates` | List templates |
|
||||
| GET | `/api/v1/school/certificates/class/:classId` | Class certificates |
|
||||
| POST | `/api/v1/school/certificates/generate` | Generate single |
|
||||
| POST | `/api/v1/school/certificates/generate-bulk` | Generate bulk |
|
||||
| GET | `/api/v1/school/certificates/detail/:id/pdf` | Download PDF |
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **RBAC Enforcement**: All certificate operations check user role permissions
|
||||
2. **Tenant Isolation**: Teachers only see their own classes/students
|
||||
3. **Audit Trail**: All grade changes and approvals logged
|
||||
4. **Lock Mechanism**: Finalized certificates cannot be modified
|
||||
5. **Workflow Enforcement**: Cannot skip approval steps
|
||||
Reference in New Issue
Block a user