Benjamin_Boenisch/breakpilot-compliance
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
breakpilot-compliance/docs-src/services/sdk-modules/training.md
Benjamin Admin 4f6bc8f6f6
Some checks failed
CI/CD / go-lint (push) Has been skipped
Details
CI/CD / python-lint (push) Has been skipped
Details
CI/CD / nodejs-lint (push) Has been skipped
Details
CI/CD / test-go-ai-compliance (push) Failing after 37s
Details
CI/CD / test-python-backend-compliance (push) Successful in 39s
Details
CI/CD / test-python-document-crawler (push) Successful in 26s
Details
CI/CD / test-python-dsms-gateway (push) Successful in 23s
Details
CI/CD / validate-canonical-controls (push) Successful in 12s
Details
CI/CD / Deploy (push) Has been skipped
Details
feat(training+controls): interactive video pipeline, training blocks, control generator, CE libraries 
Interactive Training Videos (CP-TRAIN):
- DB migration 022: training_checkpoints + checkpoint_progress tables
- NarratorScript generation via Anthropic (AI Teacher persona, German)
- TTS batch synthesis + interactive video pipeline (slides + checkpoint slides + FFmpeg)
- 4 new API endpoints: generate-interactive, interactive-manifest, checkpoint submit, checkpoint progress
- InteractiveVideoPlayer component (HTML5 Video, quiz overlay, seek protection, progress tracking)
- Learner portal integration with automatic completion on all checkpoints passed
- 30 new tests (handler validation + grading logic + manifest/progress + seek protection)

Training Blocks:
- Block generator, block store, block config CRUD + preview/generate endpoints
- Migration 021: training_blocks schema

Control Generator + Canonical Library:
- Control generator routes + service enhancements
- Canonical control library helpers, sidebar entry
- Citation backfill service + tests
- CE libraries data (hazard, protection, evidence, lifecycle, components)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-16 21:41:48 +01:00

278 lines
11 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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"
```
Reference in New Issue View Git Blame Copy Permalink