breakpilot-pwa/backend/PLAN_KLAUSURKORREKTUR.md

# Klausurkorrektur - Privacy-by-Design Implementation Plan

## Übersicht

Implementierung eines DSGVO-konformen Klausurkorrektur-Moduls mit QR-Code-basierter Pseudonymisierung. Keine personenbezogenen Daten werden an das LLM gesendet.

## Architektur-Prinzipien

1. **Pseudonymisierung (Art. 4 Nr. 5 DSGVO)**: `doc_token` (128-bit random) als einziger Join-Key
2. **Teacher Namespace Isolation**: Jeder Lehrer hat isolierten Workspace
3. **Privacy by Architecture**: Backend kann Schüler nicht identifizieren
4. **Self-hosted LLM**: SysEleven, kein OpenAI/externe Datenübertragung

---

## Phase 1: Backend-Infrastruktur

### 1.1 Datenmodelle erstellen
**Datei**: `/backend/klausur/db_models.py` (NEU)

```python
# Modelle:
- ExamSession: teacher_id, session_id, created_at, status
- PseudonymizedDocument: doc_token (UUID), session_id, ocr_text, ai_feedback, created_at
- TeacherVault: teacher_id, encrypted_identity_map (lokal verschlüsselt)
```

### 1.2 Repository-Klasse
**Datei**: `/backend/klausur/repository.py` (NEU)

- CRUD für ExamSession, PseudonymizedDocument
- Teacher-Isolation durch `teacher_id` Filter
- Keine Speicherung von Klarnamen im Backend

### 1.3 Pseudonymisierung-Service
**Datei**: `/backend/klausur/services/pseudonymizer.py` (NEU)

```python
class PseudonymizationService:
    def generate_doc_token() -> str  # 128-bit UUID
    def generate_qr_overlay(doc_token: str) -> bytes  # QR-Code PNG
    def redact_header(image: bytes) -> bytes  # Entfernt Kopfzeile mit Namen
    def extract_doc_token_from_qr(image: bytes) -> str  # QR-Code lesen
```

### 1.4 OCR-Integration erweitern
**Datei**: `/backend/services/file_processor.py` (ERWEITERN)

- Neue Methode: `process_exam_page(image, redact_header=True)`
- Integration mit PaddleOCR für Handschrift
- Header-Redaction vor OCR

### 1.5 LLM-Korrektur-Service
**Datei**: `/backend/klausur/services/correction_service.py` (NEU)

```python
class ExamCorrectionService:
    def correct_answer(doc_token: str, question: str, student_answer: str, rubric: str) -> CorrectionResult
    def batch_correct(session_id: str) -> List[CorrectionResult]
```

- Nutzt bestehenden LLM-Gateway (Ollama/vLLM)
- Nur pseudonymisierte Texte werden gesendet
- `doc_token` als einzige Referenz

---

## Phase 2: API-Endpunkte

### 2.1 Klausur-API
**Datei**: `/backend/klausur/routes.py` (NEU)

```
POST /api/klausur/session                    # Neue Korrektur-Session erstellen
GET  /api/klausur/session/{session_id}       # Session-Status abrufen
POST /api/klausur/session/{session_id}/upload # Gescannte Seiten hochladen
GET  /api/klausur/session/{session_id}/qr-sheet # QR-Overlay-Bogen generieren
POST /api/klausur/session/{session_id}/process # OCR + KI-Korrektur starten
GET  /api/klausur/session/{session_id}/results # Pseudonymisierte Ergebnisse
DELETE /api/klausur/session/{session_id}     # Session löschen
```

### 2.2 Teacher Vault API (Client-seitig)
**Datei**: `/backend/klausur/routes.py`

```
POST /api/klausur/vault/encrypt   # Identity-Map clientseitig verschlüsseln
POST /api/klausur/vault/decrypt   # Identity-Map clientseitig entschlüsseln
```

- Server speichert nur verschlüsselte Blobs
- Schlüssel bleibt beim Lehrer (Browser/LocalStorage)

---

## Phase 3: PWA Frontend-Modul

### 3.1 Klausurkorrektur-Modul ersetzen
**Datei**: `/backend/frontend/modules/klausur_korrektur.py` (ÜBERSCHREIBEN)

**Tabs im Modul**:
1. **Neue Session**: QR-Bogen generieren, Schülerliste eingeben
2. **Upload**: Gescannte Klausuren hochladen (Drag & Drop)
3. **Verarbeitung**: OCR + KI-Korrektur Status
4. **Ergebnisse**: Pseudonymisierte Bewertungen → Re-Join mit lokaler Identity-Map
5. **Export**: Excel/PDF Export der Ergebnisse

### 3.2 Identity-Map (Teacher Vault)
**Client-seitig in JavaScript**:

```javascript
class TeacherVault {
    constructor(teacherId)
    generateIdentityMap(studentNames) // Erstellt doc_token → Name Mapping
    encrypt(password) // AES-256 Verschlüsselung im Browser
    decrypt(password) // Entschlüsselung im Browser
    rejoinResults(pseudonymizedResults) // Verknüpft Ergebnisse mit Namen
    exportToLocalStorage()
    importFromLocalStorage()
}
```

### 3.3 QR-Code Workflow
**UI-Flow**:
1. Lehrer gibt Schülerliste ein (Namen)
2. System generiert für jeden Schüler einen `doc_token`
3. Identity-Map wird lokal im Browser verschlüsselt gespeichert
4. QR-Bogen wird zum Ausdrucken generiert (jeder QR = ein doc_token)
5. Schüler kleben QR auf ihre Klausur
6. Nach Scan: QR wird erkannt, Header redacted, nur Text an LLM

---

## Phase 4: Admin-Panel Integration

### 4.1 GPU/LLM-Tab erweitern
**Datei**: `/backend/frontend/components/admin_gpu.py` (ERWEITERN)

Neue Abschnitte:
- **Klausur-Queue**: Warteschlange der Korrektur-Jobs
- **LLM-Status**: Verbindung zu SysEleven vLLM
- **OCR-Status**: PaddleOCR Verfügbarkeit
- **Session-Übersicht**: Aktive Korrektur-Sessions (nur Anzahl, keine Namen)

---

## Phase 5: Sicherheits-Features

### 5.1 Zero-Knowledge Design
- Backend speichert niemals Klarnamen
- Identity-Map nur verschlüsselt (Client-Key)
- doc_token ist kryptografisch zufällig (UUID4)
- Keine Korrelation zwischen Sessions möglich

### 5.2 Daten-Retention
- Pseudonymisierte Daten: 30 Tage, dann auto-delete
- Verschlüsselte Vault-Daten: Lehrer kann jederzeit löschen
- Audit-Log ohne PII

### 5.3 Teacher-Isolation
- Alle Queries gefiltert nach `teacher_id`
- Kein Cross-Teacher-Zugriff möglich
- Row-Level Security in PostgreSQL

---

## Implementierungs-Reihenfolge

1. **Backend-Modelle** (`/backend/klausur/db_models.py`)
2. **Repository** (`/backend/klausur/repository.py`)
3. **Pseudonymizer-Service** (`/backend/klausur/services/pseudonymizer.py`)
4. **Correction-Service** (`/backend/klausur/services/correction_service.py`)
5. **API-Routes** (`/backend/klausur/routes.py`)
6. **PWA-Modul** (`/backend/frontend/modules/klausur_korrektur.py`)
7. **TeacherVault JS** (eingebettet in Modul)
8. **Admin-Panel** (`/backend/frontend/components/admin_gpu.py`)
9. **Tests** (`/backend/klausur/tests/`)
10. **Migration** (Alembic für neue Tabellen)

---

## Technologie-Stack

| Komponente | Technologie |
|------------|-------------|
| QR-Code | `qrcode` + `Pillow` |
| OCR | PaddleOCR (bereits vorhanden) |
| Verschlüsselung (Client) | Web Crypto API (AES-256-GCM) |
| Verschlüsselung (Server) | `cryptography` (Fernet) |
| LLM | vLLM @ SysEleven (via llm_gateway) |
| DB | PostgreSQL + SQLAlchemy |

---

## Datenschutz-Garantien

✅ Keine Schülernamen im Backend gespeichert
✅ Keine Schülernamen an LLM gesendet
✅ Identity-Map nur verschlüsselt (Client-Schlüssel)
✅ Teacher-Namespace-Isolation
✅ Automatische Daten-Löschung nach 30 Tagen
✅ Vergleichbar mit lokaler PC-Verarbeitung (Art. 4 Nr. 5 DSGVO)