breakpilot-lehrer/docs-src/services/klausur-service/index.md

# Klausur-Service

Der Klausur-Service ist ein FastAPI-basierter Microservice fuer KI-gestuetzte Abitur-Klausurkorrektur.

## Uebersicht

| Eigenschaft | Wert |
|-------------|------|
| **Port** | 8086 |
| **Framework** | FastAPI (Python) |
| **Datenbank** | PostgreSQL + Qdrant (Vektor-DB) |
| **Speicher** | MinIO (Datei-Storage) |

## Features

- **OCR-Erkennung**: Automatische Texterkennung aus gescannten Klausuren
- **KI-Bewertung**: Automatische Bewertungsvorschlaege basierend auf Erwartungshorizont
- **BYOEH**: Bring-Your-Own-Expectation-Horizon mit Client-seitiger Verschluesselung
- **Fairness-Analyse**: Statistische Analyse der Bewertungskonsistenz
- **PDF-Export**: Gutachten und Notenuebersichten als PDF
- **Zweitkorrektur**: Vollstaendiger Workflow fuer Erst-, Zweit- und Drittkorrektur

## Architektur

```
┌─────────────────────────────────────────────────────────────┐
│                    Frontend (Next.js)                        │
│  /website/app/admin/klausur-korrektur/                      │
│  - Klausur-Liste                                            │
│  - Studenten-Liste                                          │
│  - Korrektur-Workspace (2/3-1/3 Layout)                     │
│  - Fairness-Dashboard                                       │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                 klausur-service (FastAPI)                    │
│  Port 8086 - /klausur-service/backend/main.py               │
│  - Klausur CRUD (/api/v1/klausuren)                         │
│  - Student Work (/api/v1/students)                          │
│  - Annotations (/api/v1/annotations)                        │
│  - BYOEH (/api/v1/eh)                                       │
│  - PDF Export                                               │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Infrastruktur                             │
│  - Qdrant (Vektor-DB fuer RAG)                              │
│  - MinIO (Datei-Storage)                                    │
│  - PostgreSQL (Metadaten)                                   │
│  - Embedding-Service (Port 8087)                            │
└─────────────────────────────────────────────────────────────┘
```

## API Endpoints

### Klausur-Verwaltung

| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/api/v1/klausuren` | Liste aller Klausuren |
| POST | `/api/v1/klausuren` | Neue Klausur erstellen |
| GET | `/api/v1/klausuren/{id}` | Klausur-Details |
| DELETE | `/api/v1/klausuren/{id}` | Klausur loeschen |

### Studenten-Arbeiten

| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| POST | `/api/v1/klausuren/{id}/students` | Arbeit hochladen |
| GET | `/api/v1/klausuren/{id}/students` | Studenten-Liste |
| GET | `/api/v1/students/{id}` | Einzelne Arbeit |
| PUT | `/api/v1/students/{id}/criteria` | Kriterien bewerten |
| PUT | `/api/v1/students/{id}/gutachten` | Gutachten speichern |

### KI-Funktionen

| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| POST | `/api/v1/students/{id}/gutachten/generate` | Gutachten generieren |
| GET | `/api/v1/klausuren/{id}/fairness` | Fairness-Analyse |
| POST | `/api/v1/students/{id}/eh-suggestions` | EH-Vorschlaege via RAG |

### PDF-Export

| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/api/v1/students/{id}/export/gutachten` | Einzelgutachten PDF |
| GET | `/api/v1/students/{id}/export/annotations` | Anmerkungen PDF |
| GET | `/api/v1/klausuren/{id}/export/overview` | Notenuebersicht PDF |
| GET | `/api/v1/klausuren/{id}/export/all-gutachten` | Alle Gutachten PDF |

## Notensystem

Das System verwendet das deutsche 15-Punkte-System fuer Abiturklausuren:

| 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 Qualitaet |
| Struktur | 15% | Aufbau & Gliederung |
| Stil | 15% | Ausdruck & Stil |

## Verzeichnisstruktur

```
klausur-service/
├── backend/
│   ├── main.py              # API Endpoints + Datenmodelle
│   ├── qdrant_service.py    # Vektor-Datenbank Operationen
│   ├── eh_pipeline.py       # BYOEH Verarbeitung
│   ├── hybrid_search.py     # Hybrid Search (BM25 + Semantic)
│   └── requirements.txt     # Python Dependencies
├── frontend/
│   └── src/
│       ├── components/      # React Komponenten
│       ├── pages/           # Seiten
│       └── services/        # API Client
└── docs/
    ├── BYOEH-Architecture.md
    └── BYOEH-Developer-Guide.md
```

## Konfiguration

### Umgebungsvariablen

```env
# Klausur-Service
KLAUSUR_SERVICE_PORT=8086
QDRANT_URL=http://qdrant:6333
MINIO_ENDPOINT=minio:9000
MINIO_ACCESS_KEY=...
MINIO_SECRET_KEY=...

# Embedding-Service
EMBEDDING_SERVICE_URL=http://embedding:8087
OPENAI_API_KEY=sk-...

# BYOEH
BYOEH_ENCRYPTION_ENABLED=true
EH_UPLOAD_DIR=/app/eh-uploads
```

## Weiterführende Dokumentation

- [BYOEH Architektur](./BYOEH-Architecture.md) - Client-seitige Verschluesselung
- [OCR Compare](./OCR-Compare.md) - Block Review Feature fuer OCR-Vergleich
- [Zeugnis-System](../../architecture/zeugnis-system.md) - Zeugniserstellung
- [Backend API](../../api/backend-api.md) - Allgemeine API-Dokumentation