Files

Benjamin Boenisch e22019b2d5 Add CLAUDE.md, MkDocs docs, .claude/rules

- CLAUDE.md: Comprehensive documentation for Lehrer KI platform
- docs-src: Klausur, Voice, Agent-Core, KI-Pipeline docs
- mkdocs.yml: Lehrer-specific nav with blue theme
- docker-compose: Added docs service (port 8010, profile: docs)
- .claude/rules: testing, docs, open-source, abiturkorrektur, vocab-worksheet, multi-agent, experimental-dashboard

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-12 00:49:25 +01:00

6.7 KiB

Raw Blame History

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

6.7 KiB Raw Blame History