# Training Engine (CP-TRAIN)

KI-generierte Schulungsinhalte, Rollenmatrix, Quiz-Engine, Zertifikate und Training Blocks fuer Compliance-Schulungen.

**Prefix:** `CP-TRAIN` · **seq:** 4800 · **Frontend:** `https://macmini:3007/sdk/training`
**Learner-Portal:** `https://macmini:3007/sdk/training/learner`
**Service:** `ai-compliance-sdk` (Go/Gin, Port 8093)
**Proxy:** `/api/sdk/v1/training/[[...path]]` → `ai-compliance-sdk:8090/sdk/v1/training/...`
**Developer Portal:** `https://macmini:3006/api/training`

---

## Features

- Rollenbasierte Schulungsmatrix (CTM) — 10 Rollen (R1–R10)
- KI-generierte Schulungsinhalte (Text, Audio, Video via TTS-Service)
- Quiz-Engine mit automatischer Auswertung und Bestehensgrenze
- Deadline-Tracking und 4-stufige Eskalation (7/14/30/45 Tage)
- Aufgabenzuweisung (Assignments) mit Fortschrittstracking
- PDF-Zertifikate nach erfolgreichem Abschluss
- Training Blocks — automatische Modul-Erstellung aus Canonical Controls
- Learner-Portal fuer Mitarbeiter (Schulung absolvieren, Quiz, Zertifikat)
- Unveraenderliches Audit-Log fuer Compliance-Nachweise
- Bulk-Content-Generierung fuer alle Module auf einmal

---

## Rechtsgrundlage

| Artikel | Bezug |
|---------|-------|
| Art. 39 Abs. 1b DSGVO | DSB-Aufgabe: Sensibilisierung und Schulung |
| Art. 5 AI Act | Schulungspflicht fuer verbotene KI-Praktiken |
| Art. 4 Abs. 2 AI Act | Schulung fuer KI-Alphabetisierung |

---

## Tabs / Ansichten

### Admin-Frontend (`/sdk/training`)

| Tab | Inhalt |
|-----|--------|
| `overview` | Statistiken, Deadline-Warnung, Eskalation-Check |
| `modules` | CRUD aller Schulungsmodule mit Filter (Status, Regulierung) |
| `matrix` | Rollen-Modul-Matrix — wer muss welche Schulung absolvieren |
| `assignments` | Zugewiesene Schulungen mit Fortschritt und Deadline |
| `content` | KI-generierter Inhalt pro Modul + Audio/Video-Player |
| `audit` | Unveraenderliches Audit-Log aller Schulungsaktivitaeten |

### Learner-Portal (`/sdk/training/learner`)

| Tab | Inhalt |
|-----|--------|
| Meine Schulungen | Zuweisungsliste mit Status-Badges, Fortschrittsbalken, Deadline |
| Schulungsinhalt | Modul-Content (Markdown), AudioPlayer, VideoPlayer |
| Quiz | Fragen mit Antwortauswahl, Timer, Ergebnis-Anzeige |
| Zertifikate | Grid mit abgeschlossenen Schulungen, PDF-Download |

**Learner-Workflow:**

1. Mitarbeiter sieht seine Zuweisungen
2. Klickt "Schulung starten" → Content lesen, Audio/Video anhoeren
3. "Quiz starten" → Fragen beantworten
4. Bei Bestehen: "Zertifikat generieren" → PDF-Download

---

## API Endpoints

### Module

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/sdk/v1/training/modules` | Alle Module (`regulation_area`, `frequency_type`, `search` Filter) |
| `GET` | `/sdk/v1/training/modules/:id` | Modul-Detail mit Content und Quiz-Fragen |
| `POST` | `/sdk/v1/training/modules` | Modul erstellen |
| `PUT` | `/sdk/v1/training/modules/:id` | Modul aktualisieren |
| `DELETE` | `/sdk/v1/training/modules/:id` | Modul loeschen |

### Rollenmatrix (CTM)

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/sdk/v1/training/matrix` | Vollstaendige Rollenmatrix |
| `GET` | `/sdk/v1/training/matrix/:role` | Matrix fuer eine Rolle |
| `POST` | `/sdk/v1/training/matrix` | Eintrag hinzufuegen |
| `DELETE` | `/sdk/v1/training/matrix/:role/:moduleId` | Eintrag entfernen |

**Rollen:** R1 Geschaeftsfuehrung, R2 IT-Leitung, R3 DSB, R4 ISB, R5 HR, R6 Einkauf, R7 Fachabteilung, R8 IT-Admin, R9 Alle Mitarbeiter, R10 Behoerden

### Assignments

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/sdk/v1/training/assignments` | Alle Zuweisungen (Filter: `user_id`, `module_id`, `role`, `status`) |
| `GET` | `/sdk/v1/training/assignments/:id` | Zuweisung-Detail |
| `POST` | `/sdk/v1/training/assignments/compute` | Zuweisungen aus Matrix berechnen |
| `POST` | `/sdk/v1/training/assignments/:id/start` | Schulung starten |
| `POST` | `/sdk/v1/training/assignments/:id/progress` | Fortschritt aktualisieren |
| `POST` | `/sdk/v1/training/assignments/:id/complete` | Schulung abschliessen |
| `PUT` | `/sdk/v1/training/assignments/:id` | Deadline aktualisieren |

### KI-Content-Generierung

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `POST` | `/sdk/v1/training/content/generate` | Inhalt KI-generieren (Markdown) |
| `POST` | `/sdk/v1/training/content/generate-quiz` | Quiz-Fragen KI-generieren |
| `GET` | `/sdk/v1/training/content/:moduleId` | Veroeffentlichten Content laden |
| `POST` | `/sdk/v1/training/content/:contentId/publish` | Inhalt freigeben |
| `POST` | `/sdk/v1/training/content/generate-all` | Alle Module bulk-generieren |
| `POST` | `/sdk/v1/training/content/generate-all-quiz` | Alle Quizzes bulk-generieren |

### Quiz

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/sdk/v1/training/quiz/:moduleId` | Quiz-Fragen fuer ein Modul |
| `POST` | `/sdk/v1/training/quiz/:moduleId/submit` | Antworten einreichen |
| `GET` | `/sdk/v1/training/quiz/attempts/:assignmentId` | Quiz-Versuche anzeigen |

### Media (Audio/Video)

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `POST` | `/sdk/v1/training/content/:moduleId/generate-audio` | Audio generieren (Piper TTS) |
| `POST` | `/sdk/v1/training/content/:moduleId/generate-video` | Video generieren (TTS + Folien) |
| `POST` | `/sdk/v1/training/content/:moduleId/preview-script` | Video-Script Vorschau (JSON) |
| `GET` | `/sdk/v1/training/media/module/:moduleId` | Alle Medien eines Moduls |
| `GET` | `/sdk/v1/training/media/:mediaId/url` | Metadaten (Bucket, Object Key) |
| `POST` | `/sdk/v1/training/media/:mediaId/publish` | Media veroeffentlichen |
| `GET` | `/sdk/v1/training/media/:mediaId/stream` | **Media streamen** (307 → Presigned URL) |

**Media-Streaming:** Der `/stream`-Endpoint liefert einen `307 Temporary Redirect` zu einer zeitlich begrenzten Presigned URL (MinIO/S3). Browser und Player folgen dem Redirect automatisch. Der Next.js-Proxy leitet den Redirect transparent weiter.

### Deadlines & Eskalation

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/sdk/v1/training/deadlines` | Bevorstehende Deadlines |
| `GET` | `/sdk/v1/training/deadlines/overdue` | Ueberfaellige Deadlines |
| `POST` | `/sdk/v1/training/escalation/check` | Eskalation ausfuehren |

**Eskalationsstufen:**

| Stufe | Tage ueberfaellig | Aktion |
|-------|-------------------|--------|
| 1 | 7 Tage | Erinnerung an Mitarbeiter |
| 2 | 14 Tage | Benachrichtigung Teamleitung |
| 3 | 30 Tage | Benachrichtigung Management |
| 4 | 45 Tage | Benachrichtigung Compliance Officer |

### Zertifikate

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `POST` | `/sdk/v1/training/certificates/generate/:assignmentId` | Zertifikat generieren |
| `GET` | `/sdk/v1/training/certificates` | Alle Zertifikate des Tenants |
| `GET` | `/sdk/v1/training/certificates/:id/pdf` | Zertifikat als PDF herunterladen |
| `GET` | `/sdk/v1/training/certificates/:id/verify` | Zertifikat verifizieren |

**Voraussetzungen:** Status `completed` UND `quiz_passed = true`. Das PDF wird im Querformat (A4 Landscape) generiert und enthaelt Modul-Titel, Benutzer-Name, Datum und eine eindeutige Zertifikats-ID.

### Training Blocks (Controls → Module)

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/sdk/v1/training/blocks` | Alle Block-Konfigurationen |
| `POST` | `/sdk/v1/training/blocks` | Block-Konfiguration erstellen |
| `GET` | `/sdk/v1/training/blocks/:id` | Block-Konfiguration laden |
| `PUT` | `/sdk/v1/training/blocks/:id` | Block-Konfiguration aktualisieren |
| `DELETE` | `/sdk/v1/training/blocks/:id` | Block-Konfiguration loeschen |
| `POST` | `/sdk/v1/training/blocks/:id/preview` | Vorschau: Welche Controls/Module? |
| `POST` | `/sdk/v1/training/blocks/:id/generate` | Module generieren (Content + CTM) |
| `GET` | `/sdk/v1/training/blocks/:id/controls` | Verlinkte Controls anzeigen |

### Canonical Controls

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/sdk/v1/training/canonical/controls` | Controls auflisten (Filter: domain, category, severity, target_audience) |
| `GET` | `/sdk/v1/training/canonical/meta` | Metadaten (Domains, Kategorien, Audiences mit Counts) |

### Statistiken & Audit

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/sdk/v1/training/stats` | Ueberblick-Statistiken |
| `GET` | `/sdk/v1/training/audit-log` | Audit-Log (Filter: `action`, `entity_type`, `limit`, `offset`) |

---

## SDK-Workflow Position

```
seq 4700: Academy (Compliance Academy — manuelle Schulungen)
seq 4800: Training Engine (KI-generierte Schulungen, Matrix, Quiz)
```

Das Training-Modul erweitert die Academy um KI-generierte Inhalte. Waehrend die Academy einfache Schulungseinheiten verwaltet, bietet die Training Engine automatische Inhaltsgenerierung, eine Rollenmatrix und eine vollstaendige Quiz-Engine.

---

## Media (TTS-Service)

KI-generierte Inhalte werden via `compliance-tts-service` (Port 8095) in Audio und Video umgewandelt:

- **Audio:** Piper TTS → MP3 (Modell: `de_DE-thorsten-high.onnx`)
- **Video:** FFmpeg → MP4 (Skript + Stimme + Untertitel)
- **Storage:** S3-kompatibles Object Storage (Hetzner, TLS)
- **Streaming:** `/media/:id/stream` → 307 Redirect zu MinIO Presigned URL

```
AudioPlayer → /sdk/v1/training/media/:mediaId/stream
VideoPlayer → /sdk/v1/training/media/:mediaId/stream
TTS Service → POST /presigned-url (returns pre-signed MinIO URL)
```

---

## Frontend

### Admin-Frontend

**URL:** `https://macmini:3007/sdk/training`

6-Tab-Oberflaeche mit:
- Statistik-Dashboard (Abschlussquote, offene Schulungen, Deadlines)
- Modul-CRUD mit Regulierungs-Badges und Loeschfunktion
- Interaktive Rollenmatrix (Checkboxen)
- Fortschritts-Balken pro Assignment
- Eingebetteter Audio/Video-Player fuer KI-generierte Inhalte

### Learner-Portal

**URL:** `https://macmini:3007/sdk/training/learner`

4-Tab-Oberflaeche fuer Mitarbeiter:
- Meine Schulungen: Zuweisungsliste mit Status, Fortschritt, Deadline
- Schulungsinhalt: Markdown-Rendering, Audio-Player, Video-Player
- Quiz: Multiple-Choice mit Timer, Ergebnis-Anzeige, Bestehens-Logik
- Zertifikate: Uebersicht abgeschlossener Schulungen, PDF-Download

---

## Datenbankschema (Go — ai-compliance-sdk)

Die Training Engine verwendet eigene Tabellen im `compliance` Schema:

```sql
training_modules           -- Schulungsmodule (title, regulation, frequency, ...)
training_matrix            -- Rollen-Modul-Zuordnungen (CTM)
training_assignments       -- Zuweisungen (user, module, status, progress, deadline, certificate_id)
training_content           -- KI-generierter Inhalt (markdown, summary, llm_model)
training_quiz_questions    -- Quiz-Fragen pro Modul (options JSONB, correct_index)
training_quiz_attempts     -- Eingereichte Antworten + Score
training_media             -- Audio/Video-Dateien (bucket, object_key, status)
training_audit_log         -- Unveraenderliches Audit-Log
training_block_configs     -- Block-Konfigurationen (Filter, Prefix, Frequenz)
training_block_controls    -- Verlinkte Canonical Controls pro Block
```

---

## Tests

```bash
# Handler-Tests (47 Tests)
cd ai-compliance-sdk && go test -v ./internal/api/handlers/ -run "TestGet|TestCreate|TestUpdate|TestDelete|..."

# Escalation + Content Generator Tests (43 Tests)
cd ai-compliance-sdk && go test -v ./internal/training/ -run "TestEscalation|TestBuildContent|TestParseQuiz|..."

# Block Generator Tests (14 Tests)
cd ai-compliance-sdk && go test -v ./internal/training/ -run "TestBlock"
```