breakpilot-pwa/docs/zeugnis-system/README.md

# 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](#architektur)
2. [Rights-Aware Crawler](#rights-aware-crawler)
3. [Training Dashboard](#training-dashboard)
4. [Lehrer-Frontend](#lehrer-frontend)
5. [API-Referenz](#api-referenz)
6. [Deployment](#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:**
```json
[
  {
    "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:**
```json
{
  "bundesland": "ni",  // Optional: Nur dieses Bundesland
  "priority": 5        // 1-10, Standard: 5
}
```

**Response:**
```json
{
  "success": true,
  "message": "Crawler started"
}
```

#### GET /api/v1/admin/zeugnis/stats
Holt Statistiken.

**Response:**
```json
{
  "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

```env
# 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

```yaml
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:
   ```bash
   docker-compose up -d
   ```

2. Datenbank initialisieren:
   ```bash
   curl -X POST http://localhost:8086/api/v1/admin/zeugnis/init
   ```

3. Crawler starten:
   ```bash
   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