ad111d5e69
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>
264 lines
4.8 KiB
Markdown
264 lines
4.8 KiB
Markdown
# BreakPilot Backend API Dokumentation
|
|
|
|
## Übersicht
|
|
|
|
Base URL: `http://localhost:8000/api`
|
|
|
|
Alle Endpoints erfordern Authentifizierung via JWT im Authorization-Header:
|
|
```
|
|
Authorization: Bearer <token>
|
|
```
|
|
|
|
---
|
|
|
|
## Worksheets API
|
|
|
|
Generiert Lernmaterialien (MC-Tests, Lückentexte, Mindmaps, Quiz).
|
|
|
|
### POST /worksheets/generate/multiple-choice
|
|
|
|
Generiert Multiple-Choice-Fragen aus Quelltext.
|
|
|
|
**Request Body:**
|
|
```json
|
|
{
|
|
"source_text": "Der Text, aus dem Fragen generiert werden sollen...",
|
|
"num_questions": 5,
|
|
"difficulty": "medium",
|
|
"topic": "Thema",
|
|
"subject": "Deutsch"
|
|
}
|
|
```
|
|
|
|
**Response (200):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"content": {
|
|
"type": "multiple_choice",
|
|
"data": {
|
|
"questions": [
|
|
{
|
|
"question": "Was ist...?",
|
|
"options": ["A", "B", "C", "D"],
|
|
"correct": 0,
|
|
"explanation": "Erklärung..."
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### POST /worksheets/generate/cloze
|
|
|
|
Generiert Lückentexte.
|
|
|
|
### POST /worksheets/generate/mindmap
|
|
|
|
Generiert Mindmap als Mermaid-Diagramm.
|
|
|
|
### POST /worksheets/generate/quiz
|
|
|
|
Generiert Mix aus verschiedenen Fragetypen.
|
|
|
|
---
|
|
|
|
## Corrections API
|
|
|
|
OCR-basierte Klausurkorrektur mit automatischer Bewertung.
|
|
|
|
### POST /corrections/
|
|
|
|
Erstellt neue Korrektur-Session.
|
|
|
|
### POST /corrections/{id}/upload
|
|
|
|
Lädt gescannte Klausur hoch und startet OCR im Hintergrund.
|
|
|
|
### GET /corrections/{id}
|
|
|
|
Ruft Korrektur-Status ab.
|
|
|
|
**Status-Werte:**
|
|
- `uploaded` - Datei hochgeladen
|
|
- `processing` - OCR läuft
|
|
- `ocr_complete` - OCR fertig
|
|
- `analyzing` - Analyse läuft
|
|
- `analyzed` - Analyse abgeschlossen
|
|
- `completed` - Fertig
|
|
- `error` - Fehler
|
|
|
|
### POST /corrections/{id}/analyze
|
|
|
|
Analysiert extrahierten Text und bewertet Antworten.
|
|
|
|
### GET /corrections/{id}/export-pdf
|
|
|
|
Exportiert korrigierte Arbeit als PDF.
|
|
|
|
---
|
|
|
|
## Letters API
|
|
|
|
Elternbriefe mit GFK-Integration und PDF-Export.
|
|
|
|
### POST /letters/
|
|
|
|
Erstellt neuen Elternbrief.
|
|
|
|
**letter_type Werte:**
|
|
- `general` - Allgemeine Information
|
|
- `halbjahr` - Halbjahresinformation
|
|
- `fehlzeiten` - Fehlzeiten-Mitteilung
|
|
- `elternabend` - Einladung Elternabend
|
|
- `lob` - Positives Feedback
|
|
- `custom` - Benutzerdefiniert
|
|
|
|
### POST /letters/improve
|
|
|
|
Verbessert Text nach GFK-Prinzipien.
|
|
|
|
---
|
|
|
|
## State Engine API
|
|
|
|
Begleiter-Modus mit Phasen-Management und Antizipation.
|
|
|
|
### GET /state/dashboard
|
|
|
|
Komplettes Dashboard für Begleiter-Modus.
|
|
|
|
### GET /state/suggestions
|
|
|
|
Ruft Vorschläge für Lehrer ab.
|
|
|
|
### POST /state/milestone
|
|
|
|
Schließt Meilenstein ab.
|
|
|
|
---
|
|
|
|
## Klausur-Korrektur API (Abitur)
|
|
|
|
Abitur-Klausurkorrektur mit 15-Punkte-System, Erst-/Zweitprüfer-Workflow und KI-gestützter Bewertung.
|
|
|
|
### Klausur-Modi
|
|
|
|
| Modus | Beschreibung |
|
|
|-------|--------------|
|
|
| `landes_abitur` | NiBiS Niedersachsen - rechtlich geklärte Aufgaben |
|
|
| `vorabitur` | Lehrer-erstellte Klausuren mit Rights-Gate |
|
|
|
|
### POST /klausur-korrektur/klausuren
|
|
|
|
Erstellt neue Abitur-Klausur.
|
|
|
|
### POST /klausur-korrektur/students/{id}/evaluate
|
|
|
|
Startet KI-Bewertung.
|
|
|
|
**Response (200):**
|
|
```json
|
|
{
|
|
"criteria_scores": {
|
|
"rechtschreibung": {"score": 85, "weight": 0.15},
|
|
"grammatik": {"score": 90, "weight": 0.15},
|
|
"inhalt": {"score": 75, "weight": 0.40},
|
|
"struktur": {"score": 80, "weight": 0.15},
|
|
"stil": {"score": 85, "weight": 0.15}
|
|
},
|
|
"raw_points": 80,
|
|
"grade_points": 11,
|
|
"grade_label": "2"
|
|
}
|
|
```
|
|
|
|
### 15-Punkte-Notenschlüssel
|
|
|
|
| Punkte | Prozent | Note |
|
|
|--------|---------|------|
|
|
| 15 | ≥95% | 1+ |
|
|
| 14 | ≥90% | 1 |
|
|
| 13 | ≥85% | 1- |
|
|
| 12 | ≥80% | 2+ |
|
|
| 11 | ≥75% | 2 |
|
|
| 10 | ≥70% | 2- |
|
|
| 9 | ≥65% | 3+ |
|
|
| 8 | ≥60% | 3 |
|
|
| 7 | ≥55% | 3- |
|
|
| 6 | ≥50% | 4+ |
|
|
| 5 | ≥45% | 4 |
|
|
| 4 | ≥40% | 4- |
|
|
| 3 | ≥33% | 5+ |
|
|
| 2 | ≥27% | 5 |
|
|
| 1 | ≥20% | 5- |
|
|
| 0 | <20% | 6 |
|
|
|
|
### Bewertungskriterien
|
|
|
|
| Kriterium | Gewicht | Beschreibung |
|
|
|-----------|---------|--------------|
|
|
| `rechtschreibung` | 15% | Orthografie |
|
|
| `grammatik` | 15% | Grammatik & Syntax |
|
|
| `inhalt` | 40% | Inhaltliche Qualität |
|
|
| `struktur` | 15% | Aufbau & Gliederung |
|
|
| `stil` | 15% | Ausdruck & Stil |
|
|
|
|
---
|
|
|
|
## Security API (DevSecOps Dashboard)
|
|
|
|
API fuer das Security Dashboard mit DevSecOps-Tools Integration.
|
|
|
|
### GET /v1/security/tools
|
|
|
|
Gibt Status aller DevSecOps-Tools zurueck.
|
|
|
|
### GET /v1/security/findings
|
|
|
|
Gibt alle Security-Findings zurueck.
|
|
|
|
### GET /v1/security/sbom
|
|
|
|
Gibt SBOM (Software Bill of Materials) zurueck.
|
|
|
|
### POST /v1/security/scan/{type}
|
|
|
|
Startet einen Security-Scan.
|
|
|
|
**Path Parameter:**
|
|
- `type`: Scan-Typ (secrets, sast, deps, containers, sbom, all)
|
|
|
|
---
|
|
|
|
## Fehler-Responses
|
|
|
|
### 400 Bad Request
|
|
```json
|
|
{
|
|
"detail": "Beschreibung des Fehlers"
|
|
}
|
|
```
|
|
|
|
### 401 Unauthorized
|
|
```json
|
|
{
|
|
"detail": "Not authenticated"
|
|
}
|
|
```
|
|
|
|
### 404 Not Found
|
|
```json
|
|
{
|
|
"detail": "Ressource nicht gefunden"
|
|
}
|
|
```
|
|
|
|
### 500 Internal Server Error
|
|
```json
|
|
{
|
|
"detail": "Interner Serverfehler"
|
|
}
|
|
```
|