breakpilot-pwa/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

# 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 - Client-seitige Verschluesselung
• OCR Compare - Block Review Feature fuer OCR-Vergleich
• Zeugnis-System - Zeugniserstellung
• Backend API - Allgemeine API-Dokumentation