fix: Restore all files lost during destructive rebase

A previous `git pull --rebase origin main` dropped 177 local commits, losing 3400+ files across admin-v2, backend, studio-v2, website, klausur-service, and many other services. The partial restore attempt (660295e2) only recovered some files. This commit restores all missing files from pre-rebase ref 98933f5e while preserving post-rebase additions (night-scheduler, night-mode UI, NightModeWidget dashboard integration). Restored features include: - AI Module Sidebar (FAB), OCR Labeling, OCR Compare - GPU Dashboard, RAG Pipeline, Magic Help - Klausur-Korrektur (8 files), Abitur-Archiv (5+ files) - Companion, Zeugnisse-Crawler, Screen Flow - Full backend, studio-v2, website, klausur-service - All compliance SDKs, agent-core, voice-service - CI/CD configs, documentation, scripts Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-09 09:51:32 +01:00
parent f7487ee240
commit bfdaf63ba9
2009 changed files with 749983 additions and 1731 deletions
--- a/docs/zeugnis-system/README.md
+++ b/docs/zeugnis-system/README.md
@@ -0,0 +1,400 @@
+# 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