breakpilot-pwa/docs/zeugnis-system

Zeugnis-System Dokumentation

Übersicht

Das Zeugnis-System ist ein umfassendes Modul für die Verwaltung und Nutzung von Zeugnisverordnungen aller 16 deutschen Bundesländer. Es besteht aus drei Hauptkomponenten:

1. Rights-Aware Crawler - Automatische Sammlung von Verordnungen
2. Training Dashboard - Steuerung und Überwachung von KI-Trainingsprozessen
3. Lehrer-Frontend - Intuitive Benutzeroberfläche für Lehrkräfte

---

Inhaltsverzeichnis

1. Architektur
2. Rights-Aware Crawler
3. Training Dashboard
4. Lehrer-Frontend
5. API-Referenz
6. Deployment

---

Architektur

┌─────────────────────────────────────────────────────────────────┐
│                        Frontend (Next.js)                        │
├─────────────────┬─────────────────┬─────────────────────────────┤
│  /admin/training │  /admin/zeugnis │  /zeugnisse (Lehrer)        │
│  Dashboard       │  Crawler Admin  │  Assistent                  │
└────────┬────────┴────────┬────────┴────────┬────────────────────┘
         │                 │                  │
         ▼                 ▼                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                   API Proxy (/api/admin/...)                     │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│               Klausur-Service (FastAPI, Port 8086)               │
├─────────────────┬─────────────────┬─────────────────────────────┤
│  zeugnis_api.py │  zeugnis_       │  zeugnis_models.py          │
│  (Endpoints)    │  crawler.py     │  (Datenmodelle)             │
└────────┬────────┴────────┬────────┴────────┬────────────────────┘
         │                 │                  │
         ▼                 ▼                  ▼
┌────────────────┐ ┌───────────────┐ ┌───────────────────────────┐
│   PostgreSQL   │ │    MinIO      │ │        Qdrant             │
│   (Metadata)   │ │  (Dokumente)  │ │    (Vektoren)             │
└────────────────┘ └───────────────┘ └───────────────────────────┘

---

Rights-Aware Crawler

Konzept

Der Rights-Aware Crawler sammelt automatisch Zeugnisverordnungen und respektiert dabei die Urheberrechte:

• Training erlaubt: Amtliche Werke nach §5 UrhG
• Training nicht erlaubt: Dokumente ohne explizite Lizenzierung

Bundesländer-Berechtigungen

Bundesland	Training	Begründung
Baden-Württemberg	✅ Ja	Amtliches Werk
Bayern	✅ Ja	Amtliches Werk
Berlin	❌ Nein	Keine Lizenz
Brandenburg	❌ Nein	Keine Lizenz
Bremen	❌ Nein	Eingeschränkt
Hamburg	❌ Nein	Keine Lizenz
Hessen	✅ Ja	Amtliches Werk
Mecklenburg-Vorpommern	❌ Nein	Eingeschränkt
Niedersachsen	✅ Ja	Amtliches Werk
Nordrhein-Westfalen	✅ Ja	Amtliches Werk
Rheinland-Pfalz	✅ Ja	Amtliches Werk
Saarland	❌ Nein	Keine Lizenz
Sachsen	✅ Ja	Amtliches Werk
Sachsen-Anhalt	❌ Nein	Eingeschränkt
Schleswig-Holstein	✅ Ja	Amtliches Werk
Thüringen	✅ Ja	Amtliches Werk

Admin-Oberfläche

URL: /admin/zeugnisse-crawler

Features:

• Übersicht aller 16 Bundesländer
• Training-Status pro Bundesland
• Crawler starten/stoppen
• Dokument-Browser
• Audit-Trail

Screenshot-Bereiche:

1. Stats-Karten: Gesamtdokumente, indexierte Dokumente, Training-erlaubt
2. Bundesland-Tabelle: Status, Dokumentanzahl, letzter Crawl
3. Dokument-Liste: Filterbar, mit Statusanzeige

API-Endpunkte

GET  /api/v1/admin/zeugnis/sources           # Alle Bundesländer
POST /api/v1/admin/zeugnis/sources           # Neue Quelle
PUT  /api/v1/admin/zeugnis/sources/{id}/verify  # Lizenz verifizieren

GET  /api/v1/admin/zeugnis/crawler/status    # Crawler-Status
POST /api/v1/admin/zeugnis/crawler/start     # Crawler starten
POST /api/v1/admin/zeugnis/crawler/stop      # Crawler stoppen

GET  /api/v1/admin/zeugnis/documents         # Dokumente abrufen
GET  /api/v1/admin/zeugnis/stats             # Statistiken
GET  /api/v1/admin/zeugnis/audit/events      # Audit-Trail

---

Training Dashboard

Konzept

Das Training Dashboard ermöglicht die vollständige Kontrolle über KI-Trainingsprozesse:

• Echtzeit-Monitoring von Trainingsjobs
• Konfiguration von Hyperparametern
• Visualisierung von Metriken (Loss, Precision, Recall, F1)
• Multi-Bundesland Training

URL: /admin/training

Features

1. Übersichtskarten

• Dokumente gesamt / indexiert
• Training-erlaubte Dokumente
• Heute gecrawlt / Fehler

2. Training-Job-Karten

Jeder laufende Job zeigt:

• Progress Ring: Visueller Fortschritt (0-100%)
• Epochen-Fortschritt: Aktuelle / Gesamt
• Dokument-Fortschritt: Verarbeitet / Gesamt
• Metriken: Loss, Val Loss, Precision, F1
• Loss-Chart: Verlaufsgrafik

3. Datensatz-Übersicht

• Verteilung nach Bundesland (Balkendiagramm)
• Verteilung nach Dokumenttyp
• Training-erlaubte Quote

4. Neues Training starten (Wizard)

Schritt 1 - Datenauswahl:

• Checkbox-Grid für Bundesländer
• Nur Training-erlaubte wählbar
• Deaktivierte Anzeige für nicht-erlaubte

Schritt 2 - Parameter:

• Batch Size (Standard: 16)
• Learning Rate (Standard: 0.00005)
• Epochen (Standard: 10)
• Warmup Steps (Standard: 500)
• Mixed Precision (FP16) Toggle

Schritt 3 - Bestätigung:

• Zusammenfassung aller Einstellungen
• Geschätzte Trainingszeit
• Start-Button

Training-Kontrolle

Aktion	Beschreibung
Pausieren	Training temporär unterbrechen
Fortsetzen	Pausiertes Training fortsetzen
Abbrechen	Training beenden (Daten bleiben)
Details	Erweiterte Metriken anzeigen

---

Lehrer-Frontend

Konzept

Das Lehrer-Frontend bietet eine intuitive Oberfläche für Lehrkräfte zur Recherche in Zeugnisverordnungen.

URL: /zeugnisse

Onboarding-Wizard

Beim ersten Besuch führt ein 4-stufiger Wizard durch die Einrichtung:

Schritt 1: Willkommen

• Vorstellung des Assistenten
• Feature-Übersicht (Suche, KI-Antworten, 16 Bundesländer)

Schritt 2: Bundesland

• Grid mit allen 16 Bundesländern
• Emoji-Icons für visuelle Zuordnung
• Auswahl speichert bevorzugtes Bundesland

Schritt 3: Schulform

• Auswahl der Schulform:
  • Grundschule
  • Hauptschule
  • Realschule
  • Gymnasium
  • Gesamtschule
  • Förderschule
  • Berufsschule

Schritt 4: Fertig

• Zusammenfassung der Einstellungen
• Option zum Ändern

Hauptfunktionen

Tab 1: Assistent (Chat)

• KI-gestützter Dialog
• Fragen in natürlicher Sprache
• Quellenangaben zu Antworten
• Vorgeschlagene Fragen

Tab 2: Suche

• Volltextsuche in Verordnungen
• Letzte Suchen (gespeichert)
• Häufige Fragen als Schnellauswahl
• Relevanz-Score pro Ergebnis

Tab 3: Dokumente

• Dokumenten-Browser
• Filterbar nach Bundesland
• Download-Möglichkeit

Häufige Fragen (vordefiniert)

1. "Wie formuliere ich eine Bemerkung zur Arbeits- und Sozialverhalten?"
2. "Welche Noten dürfen im Zeugnis stehen?"
3. "Wann sind Zeugniskonferenzen durchzuführen?"
4. "Wie gehe ich mit Fehlzeiten um?"
5. "Welche Unterschriften sind erforderlich?"
6. "Wie werden Versetzungsentscheidungen dokumentiert?"

Benutzereinstellungen

Gespeichert im localStorage:

• Bundesland
• Schulform
• Wizard-Status
• Favoriten
• Letzte Suchen

---

API-Referenz

Zeugnis-Crawler API

GET /api/v1/admin/zeugnis/sources

Listet alle Bundesland-Quellen.

Response:

[
  {
    "id": "uuid",
    "bundesland": "ni",
    "name": "Niedersachsen",
    "license_type": "gov_statute",
    "training_allowed": true,
    "verified_by": "admin@example.com",
    "verified_at": "2024-01-15T10:00:00Z"
  }
]

POST /api/v1/admin/zeugnis/crawler/start

Startet den Crawler.

Request:

{
  "bundesland": "ni",  // Optional: Nur dieses Bundesland
  "priority": 5        // 1-10, Standard: 5
}

Response:

{
  "success": true,
  "message": "Crawler started"
}

GET /api/v1/admin/zeugnis/stats

Holt Statistiken.

Response:

{
  "total_sources": 16,
  "total_documents": 632,
  "indexed_documents": 489,
  "training_allowed_documents": 423,
  "active_crawls": 1,
  "per_bundesland": [...]
}

---

Deployment

Voraussetzungen

• Docker & Docker Compose
• PostgreSQL 16+
• Qdrant 1.12+
• MinIO

Umgebungsvariablen

# Klausur-Service
QDRANT_URL=http://qdrant:6333
MINIO_ENDPOINT=minio:9000
MINIO_ACCESS_KEY=breakpilot
MINIO_SECRET_KEY=breakpilot123
MINIO_BUCKET=breakpilot-rag
EMBEDDING_BACKEND=local  # oder "openai"

# Website
KLAUSUR_SERVICE_URL=http://klausur-service:8086

Docker Compose

services:
  qdrant:
    image: qdrant/qdrant:v1.12.1

  minio:
    image: minio/minio:latest

  klausur-service:
    build: ./klausur-service
    depends_on:
      - qdrant
      - minio

Initialisierung

1. Container starten:

   docker-compose up -d
   

2. Datenbank initialisieren:

   curl -X POST http://localhost:8086/api/v1/admin/zeugnis/init
   

3. Crawler starten:

   curl -X POST http://localhost:8086/api/v1/admin/zeugnis/crawler/start
   

4. Frontend öffnen:

   • Admin: http://localhost:3000/admin/zeugnisse-crawler
   • Training: http://localhost:3000/admin/training
   • Lehrer: http://localhost:3000/zeugnisse

---

Sicherheit

Datenschutz

• Audit-Trail: Alle Zugriffe werden protokolliert
• DSGVO-Export: /api/v1/admin/zeugnis/audit/export
• Verschlüsselung: Sensible Daten in MinIO verschlüsselt

Rights Management

• Training nur mit expliziter Erlaubnis
• Lizenz-Verifizierung durch Admin
• Quellen-Nachverfolgung für alle Dokumente

---

Support

Bei Fragen oder Problemen:

• GitHub Issues: https://github.com/...
• E-Mail: support@breakpilot.app