breakpilot-pwa/docs-src/api/backend-api.md

# 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"
}
```