Benjamin_Boenisch/breakpilot-pwa
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: Restore all files lost during destructive rebase

Browse Source 
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>
This commit is contained in:
Benjamin Admin
2026-02-09 09:51:32 +01:00
parent f7487ee240
commit 21a844cb8a
1986 changed files with 744143 additions and 1731 deletions
Download Patch File Download Diff File Expand all files Collapse all files

340
backend/docs/DSGVO_Datenkategorien.html Normal file
View File

@@ -0,0 +1,340 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>DSGVO Datenkategorien</title>
<style>
body { font-family: -apple-system, BlinkMacSystemFont, sans-serif; max-width: 900px; margin: 40px auto; padding: 20px; line-height: 1.6; }
table { border-collapse: collapse; width: 100%; margin: 20px 0; }
th, td { border: 1px solid #ddd; padding: 10px; text-align: left; }
th { background: #f5f5f5; }
tr:nth-child(even) { background: #fafafa; }
code { background: #f0f0f0; padding: 2px 6px; border-radius: 3px; }
h1 { color: #333; border-bottom: 2px solid #2563eb; padding-bottom: 10px; }
h2 { color: #2563eb; margin-top: 30px; }
h3 { color: #555; }
hr { border: none; border-top: 1px solid #eee; margin: 30px 0; }
</style>
</head>
<body>
<h1>DSGVO Datenkategorien &amp; Löschfristen</h1>
<p><strong>BreakPilot - Consent Management System</strong>
<em>Dokumentation für Datenschutzbestimmungen</em></p>
<hr />
<h2>Übersicht</h2>
<p>Diese Dokumentation enthält alle Datenkategorien, die von BreakPilot erfasst werden, sowie deren Löschfristen und Rechtsgrundlagen gemäß DSGVO.</p>
<hr />
<h2>Kategorie A: Essentielle Daten (Pflicht für Betrieb)</h2>
<p>Diese Daten sind für den Betrieb des Dienstes erforderlich und werden ohne zusätzliche Einwilligung verarbeitet.</p>
<table>
<thead>
<tr>
<th>Datenkategorie</th>
<th>Beschreibung</th>
<th>Löschfrist</th>
<th>Rechtsgrundlage</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>Stammdaten</strong></td>
<td>Name, E-Mail-Adresse, Kontoinformationen</td>
<td>Account-Löschung + 30 Tage</td>
<td>Vertragserfüllung (Art. 6 Abs. 1 lit. b DSGVO)</td>
</tr>
<tr>
<td><strong>Einwilligungen</strong></td>
<td>Consent-Entscheidungen, Dokumentversionen</td>
<td>3 Jahre nach Widerruf/Ablauf</td>
<td>Gesetzliche Nachweispflicht (§ 7a UWG)</td>
</tr>
<tr>
<td><strong>IP-Adressen</strong></td>
<td>Technische Protokollierung bei Aktionen</td>
<td>4 Wochen</td>
<td>Berechtigtes Interesse (Art. 6 Abs. 1 lit. f DSGVO)</td>
</tr>
<tr>
<td><strong>Session-Daten</strong></td>
<td>Login-Tokens, Sitzungsinformationen</td>
<td>Nach Sitzungsende oder 24h Inaktivität</td>
<td>Vertragserfüllung (Art. 6 Abs. 1 lit. b DSGVO)</td>
</tr>
<tr>
<td><strong>Audit-Log</strong></td>
<td>Protokoll aller datenschutzrelevanten Aktionen</td>
<td>3 Jahre (personenbezogen)</td>
<td>Berechtigtes Interesse / Compliance</td>
</tr>
<tr>
<td><strong>Passwort-Reset-Tokens</strong></td>
<td>Temporäre Tokens für Passwort-Zurücksetzung</td>
<td>24 Stunden oder nach Nutzung</td>
<td>Vertragserfüllung</td>
</tr>
<tr>
<td><strong>E-Mail-Verifikations-Tokens</strong></td>
<td>Tokens für E-Mail-Bestätigung</td>
<td>7 Tage oder nach Nutzung</td>
<td>Vertragserfüllung</td>
</tr>
<tr>
<td><strong>Export-Anfragen</strong></td>
<td>Anträge auf Datenauskunft</td>
<td>30 Tage nach Abschluss</td>
<td>Vertragserfüllung / DSGVO Art. 15</td>
</tr>
<tr>
<td><strong>Lösch-Anfragen</strong></td>
<td>Anträge auf Datenlöschung (anonymisiert)</td>
<td>3 Jahre (anonymisiert)</td>
<td>Nachweis der Löschung</td>
</tr>
<tr>
<td><strong>Benachrichtigungen</strong></td>
<td>System-Benachrichtigungen an den Nutzer</td>
<td>90 Tage nach Lesen</td>
<td>Vertragserfüllung</td>
</tr>
</tbody>
</table>
<hr />
<h2>Kategorie B: Optionale Daten (Nur bei Einwilligung)</h2>
<p>Diese Daten werden nur bei expliziter Zustimmung des Nutzers erhoben (Opt-in über Cookie-Banner).</p>
<table>
<thead>
<tr>
<th>Datenkategorie</th>
<th>Beschreibung</th>
<th>Cookie-Kategorie</th>
<th>Löschfrist</th>
<th>Rechtsgrundlage</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>Analytics-Daten</strong></td>
<td>Nutzungsstatistiken (Seitenaufrufe, Verweildauer, etc.)</td>
<td><code>analytics</code></td>
<td>26 Monate</td>
<td>Einwilligung (Art. 6 Abs. 1 lit. a DSGVO)</td>
</tr>
<tr>
<td><strong>Marketing-Daten</strong></td>
<td>Werbe-Identifier, Kampagnen-Tracking</td>
<td><code>marketing</code></td>
<td>12 Monate</td>
<td>Einwilligung (Art. 6 Abs. 1 lit. a DSGVO)</td>
</tr>
<tr>
<td><strong>Funktionale Daten</strong></td>
<td>Personalisierung, Präferenzen, UI-Einstellungen</td>
<td><code>functional</code></td>
<td>6 Monate</td>
<td>Einwilligung (Art. 6 Abs. 1 lit. a DSGVO)</td>
</tr>
</tbody>
</table>
<hr />
<h2>Detaillierte Beschreibungen</h2>
<h3>Stammdaten</h3>
<ul>
<li><strong>Erfasste Daten:</strong> Vorname, Nachname (optional), E-Mail-Adresse, Passwort-Hash</li>
<li><strong>Zweck:</strong> Identifikation, Authentifizierung, Kommunikation</li>
<li><strong>Löschung:</strong> Automatisch 30 Tage nach Account-Löschung durch den Nutzer</li>
<li><strong>Ausnahme:</strong> Bei rechtlichen Streitigkeiten kann die Frist verlängert werden</li>
</ul>
<h3>Einwilligungen (Consent Records)</h3>
<ul>
<li><strong>Erfasste Daten:</strong> Dokumenttyp, Version, Zeitstempel der Zustimmung/Ablehnung, IP-Adresse zum Zeitpunkt</li>
<li><strong>Zweck:</strong> Nachweis der erteilten Einwilligungen gegenüber Aufsichtsbehörden</li>
<li><strong>Löschung:</strong> 3 Jahre nach Widerruf oder Ablauf der Einwilligung</li>
<li><strong>Rechtsgrundlage:</strong> § 7a UWG (Beweislast für Einwilligungen)</li>
</ul>
<h3>IP-Adressen</h3>
<ul>
<li><strong>Erfasste Daten:</strong> IPv4/IPv6-Adresse bei Login, Consent-Aktionen, Sicherheitsereignissen</li>
<li><strong>Zweck:</strong> Sicherheit, Missbrauchserkennung, gesetzliche Anforderungen</li>
<li><strong>Löschung:</strong> Automatische Anonymisierung nach 4 Wochen</li>
<li><strong>Anonymisierung:</strong> Letztes Oktett wird auf 0 gesetzt (z.B. 192.168.1.0)</li>
</ul>
<h3>Session-Daten</h3>
<ul>
<li><strong>Erfasste Daten:</strong> JWT-Token, Refresh-Token, Geräte-Fingerprint, User-Agent</li>
<li><strong>Zweck:</strong> Authentifizierung, Geräte-Management</li>
<li><strong>Löschung:</strong> Automatisch bei Logout oder nach 24h Inaktivität</li>
</ul>
<h3>Audit-Log</h3>
<ul>
<li><strong>Erfasste Daten:</strong> Nutzer-ID, Aktion, Zeitstempel, IP-Adresse, User-Agent, Details</li>
<li><strong>Zweck:</strong> Compliance-Nachweis, Sicherheitsüberwachung</li>
<li><strong>Löschung (personenbezogen):</strong> 3 Jahre</li>
<li><strong>Löschung (anonymisiert):</strong> 10 Jahre (für statistische Auswertungen)</li>
</ul>
<h3>Analytics-Daten (Opt-in)</h3>
<ul>
<li><strong>Erfasste Daten:</strong> Seitenaufrufe, Verweildauer, Klickpfade, Geräteinformationen</li>
<li><strong>Zweck:</strong> Verbesserung der Nutzererfahrung, Produktentwicklung</li>
<li><strong>Cookie-Kategorie:</strong> <code>analytics</code></li>
<li><strong>Löschfrist:</strong> 26 Monate (entspricht Google Analytics Standard)</li>
</ul>
<h3>Marketing-Daten (Opt-in)</h3>
<ul>
<li><strong>Erfasste Daten:</strong> Werbe-ID, Kampagnen-Referrer, Conversion-Tracking</li>
<li><strong>Zweck:</strong> Personalisierte Werbung, Erfolgsmessung von Kampagnen</li>
<li><strong>Cookie-Kategorie:</strong> <code>marketing</code></li>
<li><strong>Löschfrist:</strong> 12 Monate</li>
</ul>
<h3>Funktionale Daten (Opt-in)</h3>
<ul>
<li><strong>Erfasste Daten:</strong> UI-Präferenzen, Spracheinstellungen, Theme-Auswahl</li>
<li><strong>Zweck:</strong> Personalisierung der Benutzeroberfläche</li>
<li><strong>Cookie-Kategorie:</strong> <code>functional</code></li>
<li><strong>Löschfrist:</strong> 6 Monate oder bei Account-Löschung</li>
</ul>
<hr />
<h2>Technische Umsetzung</h2>
<h3>Löschfristen in Tagen</h3>
<table>
<thead>
<tr>
<th>Kategorie</th>
<th>Tage</th>
<th>Automatisiert</th>
</tr>
</thead>
<tbody>
<tr>
<td>IP-Adressen</td>
<td>28</td>
<td>✓</td>
</tr>
<tr>
<td>Session-Daten</td>
<td>1</td>
<td>✓</td>
</tr>
<tr>
<td>Passwort-Reset-Tokens</td>
<td>1</td>
<td>✓</td>
</tr>
<tr>
<td>E-Mail-Verifikations-Tokens</td>
<td>7</td>
<td>✓</td>
</tr>
<tr>
<td>Export-Anfragen</td>
<td>30</td>
<td>✓</td>
</tr>
<tr>
<td>Benachrichtigungen</td>
<td>90</td>
<td>✓</td>
</tr>
<tr>
<td>Funktionale Daten</td>
<td>180</td>
<td>✓</td>
</tr>
<tr>
<td>Marketing-Daten</td>
<td>365</td>
<td>✓</td>
</tr>
<tr>
<td>Analytics-Daten</td>
<td>790</td>
<td>✓</td>
</tr>
<tr>
<td>Einwilligungen</td>
<td>1095</td>
<td>✓</td>
</tr>
<tr>
<td>Audit-Log</td>
<td>1095</td>
<td>✓</td>
</tr>
<tr>
<td>Lösch-Anfragen</td>
<td>1095</td>
<td>✓</td>
</tr>
<tr>
<td>Stammdaten</td>
<td>Account-Löschung + 30</td>
<td>Manuell ausgelöst</td>
</tr>
</tbody>
</table>
<h3>API-Endpunkte</h3>
<pre><code>GET /api/consent/privacy/data-categories - Alle Datenkategorien abrufen
GET /api/consent/privacy/data-categories?filter=essential - Nur essentielle
GET /api/consent/privacy/data-categories?filter=optional - Nur optionale
POST /api/consent/privacy/export-pdf - PDF-Datenauskunft (Art. 15)
GET /api/consent/privacy/export-html - HTML-Datenauskunft
POST /api/consent/privacy/request-deletion - Löschantrag (Art. 17)
</code></pre>
<hr />
<h2>Nutzerrechte nach DSGVO</h2>
<table>
<thead>
<tr>
<th>Recht</th>
<th>Artikel</th>
<th>Umsetzung in BreakPilot</th>
</tr>
</thead>
<tbody>
<tr>
<td>Auskunftsrecht</td>
<td>Art. 15</td>
<td>PDF/HTML-Export aller gespeicherten Daten</td>
</tr>
<tr>
<td>Berichtigungsrecht</td>
<td>Art. 16</td>
<td>Profil-Bearbeitung im Account</td>
</tr>
<tr>
<td>Löschungsrecht</td>
<td>Art. 17</td>
<td>Löschantrag über UI oder API</td>
</tr>
<tr>
<td>Einschränkungsrecht</td>
<td>Art. 18</td>
<td>Account-Sperrung auf Anfrage</td>
</tr>
<tr>
<td>Datenübertragbarkeit</td>
<td>Art. 20</td>
<td>JSON/PDF-Export im maschinenlesbaren Format</td>
</tr>
<tr>
<td>Widerspruchsrecht</td>
<td>Art. 21</td>
<td>Widerruf einzelner Einwilligungen</td>
</tr>
</tbody>
</table>
<hr />
<h2>Verantwortlicher &amp; Datenschutzbeauftragter</h2>
<p><strong>Verantwortlicher:</strong>
BreakPilot GmbH
Musterstraße 1
12345 Musterstadt
E-Mail: info@breakpilot.app</p>
<p><strong>Datenschutzbeauftragter:</strong>
E-Mail: datenschutz@breakpilot.app</p>
<p><strong>Aufsichtsbehörde:</strong>
Die zuständige Datenschutz-Aufsichtsbehörde kann bei Beschwerden kontaktiert werden.</p>
<hr />
<p><em>Letzte Aktualisierung: Dezember 2024</em>
<em>Version: 1.0</em></p>
</body>
</html>

159
backend/docs/DSGVO_Datenkategorien.md Normal file
View File

@@ -0,0 +1,159 @@
# DSGVO Datenkategorien & Löschfristen
**BreakPilot - Consent Management System**
*Dokumentation für Datenschutzbestimmungen*
---
## Übersicht
Diese Dokumentation enthält alle Datenkategorien, die von BreakPilot erfasst werden, sowie deren Löschfristen und Rechtsgrundlagen gemäß DSGVO.
---
## Kategorie A: Essentielle Daten (Pflicht für Betrieb)
Diese Daten sind für den Betrieb des Dienstes erforderlich und werden ohne zusätzliche Einwilligung verarbeitet.
| Datenkategorie | Beschreibung | Löschfrist | Rechtsgrundlage |
|----------------|--------------|------------|-----------------|
| **Stammdaten** | Name, E-Mail-Adresse, Kontoinformationen | Account-Löschung + 30 Tage | Vertragserfüllung (Art. 6 Abs. 1 lit. b DSGVO) |
| **Einwilligungen** | Consent-Entscheidungen, Dokumentversionen | 3 Jahre nach Widerruf/Ablauf | Gesetzliche Nachweispflicht (§ 7a UWG) |
| **IP-Adressen** | Technische Protokollierung bei Aktionen | 4 Wochen | Berechtigtes Interesse (Art. 6 Abs. 1 lit. f DSGVO) |
| **Session-Daten** | Login-Tokens, Sitzungsinformationen | Nach Sitzungsende oder 24h Inaktivität | Vertragserfüllung (Art. 6 Abs. 1 lit. b DSGVO) |
| **Audit-Log** | Protokoll aller datenschutzrelevanten Aktionen | 3 Jahre (personenbezogen) | Berechtigtes Interesse / Compliance |
| **Passwort-Reset-Tokens** | Temporäre Tokens für Passwort-Zurücksetzung | 24 Stunden oder nach Nutzung | Vertragserfüllung |
| **E-Mail-Verifikations-Tokens** | Tokens für E-Mail-Bestätigung | 7 Tage oder nach Nutzung | Vertragserfüllung |
| **Export-Anfragen** | Anträge auf Datenauskunft | 30 Tage nach Abschluss | Vertragserfüllung / DSGVO Art. 15 |
| **Lösch-Anfragen** | Anträge auf Datenlöschung (anonymisiert) | 3 Jahre (anonymisiert) | Nachweis der Löschung |
| **Benachrichtigungen** | System-Benachrichtigungen an den Nutzer | 90 Tage nach Lesen | Vertragserfüllung |
---
## Kategorie B: Optionale Daten (Nur bei Einwilligung)
Diese Daten werden nur bei expliziter Zustimmung des Nutzers erhoben (Opt-in über Cookie-Banner).
| Datenkategorie | Beschreibung | Cookie-Kategorie | Löschfrist | Rechtsgrundlage |
|----------------|--------------|------------------|------------|-----------------|
| **Analytics-Daten** | Nutzungsstatistiken (Seitenaufrufe, Verweildauer, etc.) | `analytics` | 26 Monate | Einwilligung (Art. 6 Abs. 1 lit. a DSGVO) |
| **Marketing-Daten** | Werbe-Identifier, Kampagnen-Tracking | `marketing` | 12 Monate | Einwilligung (Art. 6 Abs. 1 lit. a DSGVO) |
| **Funktionale Daten** | Personalisierung, Präferenzen, UI-Einstellungen | `functional` | 6 Monate | Einwilligung (Art. 6 Abs. 1 lit. a DSGVO) |
---
## Detaillierte Beschreibungen
### Stammdaten
- **Erfasste Daten:** Vorname, Nachname (optional), E-Mail-Adresse, Passwort-Hash
- **Zweck:** Identifikation, Authentifizierung, Kommunikation
- **Löschung:** Automatisch 30 Tage nach Account-Löschung durch den Nutzer
- **Ausnahme:** Bei rechtlichen Streitigkeiten kann die Frist verlängert werden
### Einwilligungen (Consent Records)
- **Erfasste Daten:** Dokumenttyp, Version, Zeitstempel der Zustimmung/Ablehnung, IP-Adresse zum Zeitpunkt
- **Zweck:** Nachweis der erteilten Einwilligungen gegenüber Aufsichtsbehörden
- **Löschung:** 3 Jahre nach Widerruf oder Ablauf der Einwilligung
- **Rechtsgrundlage:** § 7a UWG (Beweislast für Einwilligungen)
### IP-Adressen
- **Erfasste Daten:** IPv4/IPv6-Adresse bei Login, Consent-Aktionen, Sicherheitsereignissen
- **Zweck:** Sicherheit, Missbrauchserkennung, gesetzliche Anforderungen
- **Löschung:** Automatische Anonymisierung nach 4 Wochen
- **Anonymisierung:** Letztes Oktett wird auf 0 gesetzt (z.B. 192.168.1.0)
### Session-Daten
- **Erfasste Daten:** JWT-Token, Refresh-Token, Geräte-Fingerprint, User-Agent
- **Zweck:** Authentifizierung, Geräte-Management
- **Löschung:** Automatisch bei Logout oder nach 24h Inaktivität
### Audit-Log
- **Erfasste Daten:** Nutzer-ID, Aktion, Zeitstempel, IP-Adresse, User-Agent, Details
- **Zweck:** Compliance-Nachweis, Sicherheitsüberwachung
- **Löschung (personenbezogen):** 3 Jahre
- **Löschung (anonymisiert):** 10 Jahre (für statistische Auswertungen)
### Analytics-Daten (Opt-in)
- **Erfasste Daten:** Seitenaufrufe, Verweildauer, Klickpfade, Geräteinformationen
- **Zweck:** Verbesserung der Nutzererfahrung, Produktentwicklung
- **Cookie-Kategorie:** `analytics`
- **Löschfrist:** 26 Monate (entspricht Google Analytics Standard)
### Marketing-Daten (Opt-in)
- **Erfasste Daten:** Werbe-ID, Kampagnen-Referrer, Conversion-Tracking
- **Zweck:** Personalisierte Werbung, Erfolgsmessung von Kampagnen
- **Cookie-Kategorie:** `marketing`
- **Löschfrist:** 12 Monate
### Funktionale Daten (Opt-in)
- **Erfasste Daten:** UI-Präferenzen, Spracheinstellungen, Theme-Auswahl
- **Zweck:** Personalisierung der Benutzeroberfläche
- **Cookie-Kategorie:** `functional`
- **Löschfrist:** 6 Monate oder bei Account-Löschung
---
## Technische Umsetzung
### Löschfristen in Tagen
| Kategorie | Tage | Automatisiert |
|-----------|------|---------------|
| IP-Adressen | 28 | ✓ |
| Session-Daten | 1 | ✓ |
| Passwort-Reset-Tokens | 1 | ✓ |
| E-Mail-Verifikations-Tokens | 7 | ✓ |
| Export-Anfragen | 30 | ✓ |
| Benachrichtigungen | 90 | ✓ |
| Funktionale Daten | 180 | ✓ |
| Marketing-Daten | 365 | ✓ |
| Analytics-Daten | 790 | ✓ |
| Einwilligungen | 1095 | ✓ |
| Audit-Log | 1095 | ✓ |
| Lösch-Anfragen | 1095 | ✓ |
| Stammdaten | Account-Löschung + 30 | Manuell ausgelöst |
### API-Endpunkte
```
GET /api/consent/privacy/data-categories - Alle Datenkategorien abrufen
GET /api/consent/privacy/data-categories?filter=essential - Nur essentielle
GET /api/consent/privacy/data-categories?filter=optional - Nur optionale
POST /api/consent/privacy/export-pdf - PDF-Datenauskunft (Art. 15)
GET /api/consent/privacy/export-html - HTML-Datenauskunft
POST /api/consent/privacy/request-deletion - Löschantrag (Art. 17)
```
---
## Nutzerrechte nach DSGVO
| Recht | Artikel | Umsetzung in BreakPilot |
|-------|---------|-------------------------|
| Auskunftsrecht | Art. 15 | PDF/HTML-Export aller gespeicherten Daten |
| Berichtigungsrecht | Art. 16 | Profil-Bearbeitung im Account |
| Löschungsrecht | Art. 17 | Löschantrag über UI oder API |
| Einschränkungsrecht | Art. 18 | Account-Sperrung auf Anfrage |
| Datenübertragbarkeit | Art. 20 | JSON/PDF-Export im maschinenlesbaren Format |
| Widerspruchsrecht | Art. 21 | Widerruf einzelner Einwilligungen |
---
## Verantwortlicher & Datenschutzbeauftragter
**Verantwortlicher:**
BreakPilot GmbH
Musterstraße 1
12345 Musterstadt
E-Mail: info@breakpilot.app
**Datenschutzbeauftragter:**
E-Mail: datenschutz@breakpilot.app
**Aufsichtsbehörde:**
Die zuständige Datenschutz-Aufsichtsbehörde kann bei Beschwerden kontaktiert werden.
---
*Letzte Aktualisierung: Dezember 2024*
*Version: 1.0*

447
backend/docs/compliance_ai_integration.md Normal file
View File

@@ -0,0 +1,447 @@
# Compliance AI Integration - Sprint 4
## Ubersicht
Die Compliance AI Integration bietet KI-gestutzte Funktionen zur automatischen Interpretation von regulatorischen Anforderungen, Vorschlagen von Controls und Risikobewertung fur Breakpilot-Module.
## Architektur
```
Client → FastAPI Routes → AIComplianceAssistant → LLMProvider
├─ AnthropicProvider (Claude API)
├─ SelfHostedProvider (Ollama/vLLM)
└─ MockProvider (Testing)
```
## Komponenten
### 1. LLM Provider Abstraction (`llm_provider.py`)
**Abstrakte Basisklasse**: `LLMProvider`
- `complete()`: Einzelne Completion
- `batch_complete()`: Batch-Verarbeitung mit Rate-Limiting
**Implementierungen**:
#### AnthropicProvider
- Verwendet Claude API (https://api.anthropic.com)
- Empfohlen fur Produktion (beste Qualitat)
- Model: `claude-sonnet-4-20250514` (Standard)
- Benotigt: `ANTHROPIC_API_KEY`
#### SelfHostedProvider
- Unterstutzung fur Ollama, vLLM, LocalAI
- Auto-Detection von API-Formaten (Ollama vs. OpenAI-kompatibel)
- Kostengunstige Alternative fur Self-Hosting
- Benotigt: `SELF_HOSTED_LLM_URL`
#### MockProvider
- Fur Unit-Tests ohne echte API-Calls
- Vordefinierte Antworten moglich
**Factory Function**: `get_llm_provider(config?: LLMConfig) -> LLMProvider`
### 2. AI Compliance Assistant (`ai_compliance_assistant.py`)
Hauptklasse fur alle KI-Funktionen:
```python
from compliance.services.ai_compliance_assistant import get_ai_assistant
assistant = get_ai_assistant()
```
#### Methoden
**interpret_requirement()**
- Ubersetzt rechtliche Anforderungen in technische Anleitung
- Identifiziert betroffene Breakpilot-Module
- Bewertet Risiko-Level
- Gibt Implementierungs-Hinweise
**suggest_controls()**
- Schlagt 1-3 passende Controls vor
- Domain-Zuordnung (priv, iam, sdlc, crypto, ops, ai, cra, gov, aud)
- Gibt Implementierungs-Guidance und Pass-Criteria
- Erkennt automatisierbare Controls
**assess_module_risk()**
- Bewertet Compliance-Risiko fur Service-Module
- Berucksichtigt: PII-Verarbeitung, KI-Komponenten, Kritikalitat
- Identifiziert Compliance-Lucken
- Gibt Empfehlungen zur Risikominderung
**analyze_gap()**
- Analysiert Coverage zwischen Requirements und Controls
- Identifiziert fehlende Abdeckung
- Schlagt konkrete Massnahmen vor
**batch_interpret_requirements()**
- Verarbeitet mehrere Requirements mit Rate-Limiting
- Fur Bulk-Processing von Regulations
### 3. API Endpoints (`routes.py`)
Alle Endpoints unter `/api/v1/compliance/ai/`:
#### GET `/ai/status`
Pruft Status des AI Providers
**Response**:
```json
{
"provider": "anthropic",
"model": "claude-sonnet-4-20250514",
"is_available": true,
"is_mock": false,
"error": null
}
```
#### POST `/ai/interpret`
Interpretiert eine Anforderung
**Request**:
```json
{
"requirement_id": "uuid",
"force_refresh": false
}
```
**Response**:
```json
{
"requirement_id": "uuid",
"summary": "Kurze Zusammenfassung",
"applicability": "Wie dies auf Breakpilot anwendbar ist",
"technical_measures": ["Massnahme 1", "Massnahme 2"],
"affected_modules": ["consent-service", "klausur-service"],
"risk_level": "high",
"implementation_hints": ["Hinweis 1", "Hinweis 2"],
"confidence_score": 0.85,
"error": null
}
```
#### POST `/ai/suggest-controls`
Schlagt Controls fur eine Anforderung vor
**Request**:
```json
{
"requirement_id": "uuid"
}
```
**Response**:
```json
{
"requirement_id": "uuid",
"suggestions": [
{
"control_id": "PRIV-042",
"domain": "priv",
"title": "Verschlusselung personenbezogener Daten",
"description": "...",
"pass_criteria": "Alle PII sind AES-256 verschlusselt",
"implementation_guidance": "...",
"is_automated": true,
"automation_tool": "SOPS + Age",
"priority": "high",
"confidence_score": 0.9
}
]
}
```
#### POST `/ai/assess-risk`
Bewertet Risiko fur ein Modul
**Request**:
```json
{
"module_id": "consent-service"
}
```
**Response**:
```json
{
"module_name": "consent-service",
"overall_risk": "high",
"risk_factors": [
{
"factor": "Verarbeitet personenbezogene Daten",
"severity": "high",
"likelihood": "high"
}
],
"recommendations": ["Empfehlung 1", "Empfehlung 2"],
"compliance_gaps": ["Lucke 1", "Lucke 2"],
"confidence_score": 0.8
}
```
#### POST `/ai/gap-analysis`
Analysiert Coverage-Lucken
**Request**:
```json
{
"requirement_id": "uuid"
}
```
**Response**:
```json
{
"requirement_id": "uuid",
"requirement_title": "Art. 32 DSGVO - Sicherheit der Verarbeitung",
"coverage_level": "partial",
"existing_controls": ["PRIV-001", "PRIV-002"],
"missing_coverage": ["Fehlende Massnahme 1"],
"suggested_actions": ["Aktion 1", "Aktion 2"]
}
```
#### POST `/ai/batch-interpret`
Batch-Interpretation mehrerer Requirements
**Request**:
```json
{
"requirement_ids": ["uuid1", "uuid2"],
"regulation_code": "GDPR",
"rate_limit": 1.0
}
```
**Response**:
```json
{
"total": 10,
"processed": 10,
"interpretations": [...]
}
```
## Konfiguration
### Environment Variables
#### Grundeinstellungen
```bash
# Provider-Auswahl
COMPLIANCE_LLM_PROVIDER=anthropic # oder: self_hosted, mock
# LLM-Parameter
COMPLIANCE_LLM_MAX_TOKENS=4096
COMPLIANCE_LLM_TEMPERATURE=0.3
COMPLIANCE_LLM_TIMEOUT=60.0
```
#### Anthropic Claude (empfohlen)
```bash
ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_MODEL=claude-sonnet-4-20250514
```
#### Self-Hosted Alternative
```bash
COMPLIANCE_LLM_PROVIDER=self_hosted
SELF_HOSTED_LLM_URL=http://localhost:11434
SELF_HOSTED_LLM_MODEL=llama3.1:8b
SELF_HOSTED_LLM_KEY=optional-api-key
```
### Prompts
Alle Prompts sind auf **Deutsch** und **Breakpilot-spezifisch**:
- Berucksichtigt EdTech-Kontext (Schulverwaltung, Noten, Zeugnisse)
- Kennt KI-Funktionen (Klausurkorrektur, Feedback)
- Berucksichtigt DSGVO-Anforderungen
- Versteht Breakpilot-Module (consent-service, klausur-service, etc.)
## Verwendung
### Beispiel 1: Requirement interpretieren
```python
from compliance.services.ai_compliance_assistant import get_ai_assistant
assistant = get_ai_assistant()
result = await assistant.interpret_requirement(
requirement_id="req-123",
article="Art. 32",
title="Sicherheit der Verarbeitung",
requirement_text="Der Verantwortliche muss...",
regulation_code="GDPR",
regulation_name="DSGVO"
)
print(f"Risiko: {result.risk_level}")
print(f"Betroffene Module: {', '.join(result.affected_modules)}")
```
### Beispiel 2: Controls vorschlagen
```python
suggestions = await assistant.suggest_controls(
requirement_title="Verschlusselung in Ruhe und bei Ubertragung",
requirement_text="Personenbezogene Daten mussen...",
regulation_name="DSGVO",
affected_modules=["consent-service", "klausur-service"]
)
for control in suggestions:
print(f"{control.control_id}: {control.title}")
print(f" Domain: {control.domain}")
print(f" Automatisierbar: {control.is_automated}")
```
### Beispiel 3: Batch-Processing
```python
requirements = [
{"id": "req-1", "article": "Art. 32", ...},
{"id": "req-2", "article": "Art. 33", ...},
]
results = await assistant.batch_interpret_requirements(
requirements=requirements,
rate_limit=1.0 # 1 Sekunde zwischen Calls
)
for r in results:
if r.error:
print(f"Fehler bei {r.requirement_id}: {r.error}")
else:
print(f"{r.requirement_id}: {r.summary}")
```
## Rate Limiting
- **Anthropic**: 1 Request/Sekunde (Standard)
- **Self-Hosted**: 0.5 Sekunden (kann schneller sein)
- Konfigurierbar uber `rate_limit` Parameter
## Error Handling
Alle Methoden fangen Exceptions ab und geben valide Responses zuruck:
```python
result = await assistant.interpret_requirement(...)
if result.error:
print(f"Fehler aufgetreten: {result.error}")
print(f"Confidence: {result.confidence_score}") # 0.0 bei Fehler
else:
print(f"Erfolgreich: {result.summary}")
```
## Testing
### Unit Tests mit MockProvider
```python
from compliance.services.llm_provider import MockProvider, LLMConfig, LLMProviderType
# Mock-Provider erstellen
config = LLMConfig(provider_type=LLMProviderType.MOCK)
provider = MockProvider(config)
# Vordefinierte Antworten
provider.set_responses([
'{"summary": "Test-Antwort", "risk_level": "low"}'
])
# AI Assistant mit Mock
assistant = AIComplianceAssistant(llm_provider=provider)
result = await assistant.interpret_requirement(...)
```
### Integration Tests
```bash
# Mock-Provider verwenden
export COMPLIANCE_LLM_PROVIDER=mock
# Backend starten
cd backend && uvicorn main:app --reload
# Tests ausfuhren
pytest tests/test_compliance_ai.py -v
```
## Best Practices
### 1. Provider-Auswahl
- **Produktion**: Anthropic Claude (beste Qualitat)
- **Entwicklung**: Self-Hosted Ollama (kostenlos)
- **Tests**: MockProvider (schnell, deterministisch)
### 2. Caching
Die AI-Interpretationen sollten gecached werden:
- Speichere `result.raw_response` in DB
- Setze `force_refresh=True` nur bei Bedarf
- Reduziert API-Kosten erheblich
### 3. Batch-Processing
Fur initiales Setup von Regulations:
- Verwende `batch_interpret_requirements()`
- Setze rate_limit entsprechend Provider
- Verarbeite maximal 50 Requirements pro Batch
### 4. Fehlerbehandlung
Immer `result.error` prufen:
```python
if result.error:
logger.warning(f"AI failed, using fallback: {result.error}")
# Fallback-Logik
else:
# Verwende AI-Ergebnis
```
### 5. Monitoring
Tracke folgende Metriken:
- Response Times
- Error Rates
- Confidence Scores
- Token Usage (bei Anthropic)
## Roadmap
### Bereits implementiert (Sprint 4)
- [x] LLM Provider Abstraction
- [x] Anthropic + Self-Hosted Support
- [x] AI Compliance Assistant
- [x] Alle API Endpoints
- [x] Batch-Processing
### Geplant (Sprint 5+)
- [ ] Response Caching in DB
- [ ] Background Job Queue fur Batch-Processing
- [ ] Webhook-Support fur Async Processing
- [ ] Fine-Tuning auf Breakpilot-Daten
- [ ] Multi-Model Ensemble (kombiniert mehrere LLMs)
- [ ] Automatisches Re-Training basierend auf Auditor-Feedback
## Support
Bei Fragen oder Problemen:
1. Prufe `/api/v1/compliance/ai/status`
2. Prufe Logs: `docker logs breakpilot-backend`
3. Teste mit MockProvider: `COMPLIANCE_LLM_PROVIDER=mock`
## Lizenz
Teil des BreakPilot Compliance Frameworks.
Alle Rechte vorbehalten.

385
backend/docs/llm-platform/api/vast-ai-api.md Normal file
View File

@@ -0,0 +1,385 @@
# vast.ai GPU Infrastructure API Dokumentation
**Version:** 0.1.0
**Base URL:** `/infra/vast`
---
## Übersicht
Die vast.ai Infrastructure API ermöglicht die Steuerung von GPU-Instanzen direkt aus dem Admin Panel. Features:
- **Start/Stop**: GPU-Instanz ein- und ausschalten
- **Auto-Shutdown**: Automatisches Stoppen bei Inaktivität (Kostenkontrolle)
- **Kosten-Tracking**: Laufzeit und Kosten pro Session
- **Audit-Log**: Protokollierung aller Aktionen
---
## Authentifizierung
Alle Endpoints erfordern den `CONTROL_API_KEY` im Header:
```
X-API-Key: <CONTROL_API_KEY>
```
---
## Endpoints
### GET /infra/vast/status
Gibt den aktuellen Status der vast.ai Instanz zurück.
**Response (200):**
```json
{
"instance_id": 12345,
"status": "running",
"gpu_name": "RTX 3090",
"dph_total": 0.45,
"endpoint_base_url": "http://10.0.0.1:8001",
"last_activity": "2024-01-15T10:30:00Z",
"auto_shutdown_in_minutes": 25,
"total_runtime_hours": 2.5,
"total_cost_usd": 1.12,
"message": null
}
```
**Status-Werte:**
| Status | Beschreibung |
|--------|--------------|
| `running` | Instanz läuft |
| `stopped` | Instanz gestoppt (Disk bleibt) |
| `exited` | Instanz beendet |
| `loading` | Instanz startet |
| `scheduling` | Wartet auf GPU-Zuweisung |
| `creating` | Wird erstellt |
| `unconfigured` | VAST_API_KEY nicht gesetzt |
| `not_found` | Instance ID nicht gefunden |
---
### POST /infra/vast/power/on
Startet die vast.ai Instanz.
**Request Body:**
```json
{
"wait_for_health": true,
"health_path": "/health",
"health_port": 8001
}
```
**Parameter:**
| Parameter | Typ | Default | Beschreibung |
|-----------|-----|---------|--------------|
| `wait_for_health` | boolean | true | Warten bis LLM-Server erreichbar |
| `health_path` | string | "/health" | Health-Check Endpoint |
| `health_port` | integer | 8001 | Port für Health-Check |
**Response (200):**
```json
{
"status": "running",
"instance_id": 12345,
"endpoint_base_url": "http://10.0.0.1:8001",
"health_url": "http://10.0.0.1:8001/health",
"message": "Instance running and healthy"
}
```
**Errors:**
| Code | Beschreibung |
|------|--------------|
| 401 | Unauthorized (falscher API Key) |
| 500 | VAST_API_KEY oder VAST_INSTANCE_ID nicht konfiguriert |
| 502 | vast.ai API Fehler |
| 504 | Health-Check Timeout |
---
### POST /infra/vast/power/off
Stoppt die vast.ai Instanz (Disk bleibt erhalten).
**Request Body:**
```json
{}
```
**Response (200):**
```json
{
"status": "stopped",
"session_runtime_minutes": 45.5,
"session_cost_usd": 0.34,
"message": "Instance stopped. Session: 45.5 min, $0.340"
}
```
---
### POST /infra/vast/activity
Zeichnet Aktivität auf und verzögert den Auto-Shutdown Timer.
**Verwendung:** Sollte vom LLM Gateway bei jedem Request aufgerufen werden.
**Response (200):**
```json
{
"status": "recorded",
"last_activity": "2024-01-15T10:30:00Z"
}
```
---
### GET /infra/vast/costs
Gibt Kosten-Statistiken zurück.
**Response (200):**
```json
{
"total_runtime_hours": 12.5,
"total_cost_usd": 5.62,
"sessions_count": 5,
"avg_session_minutes": 150.0
}
```
---
### GET /infra/vast/audit
Gibt die letzten Audit-Log Einträge zurück.
**Query Parameter:**
| Parameter | Typ | Default | Beschreibung |
|-----------|-----|---------|--------------|
| `limit` | integer | 50 | Max. Anzahl Einträge |
**Response (200):**
```json
[
{
"ts": "2024-01-15T10:30:00Z",
"event": "power_on_complete",
"actor": "system",
"meta": {
"instance_id": 12345,
"endpoint": "http://10.0.0.1:8001"
}
},
{
"ts": "2024-01-15T09:00:00Z",
"event": "auto_shutdown",
"actor": "system",
"meta": {
"inactive_minutes": 30.5
}
}
]
```
**Event-Typen:**
| Event | Beschreibung |
|-------|--------------|
| `power_on_requested` | Start angefordert |
| `power_on_complete` | Start abgeschlossen |
| `power_on_health_timeout` | Health-Check fehlgeschlagen |
| `power_off_requested` | Stop angefordert |
| `power_off_complete` | Stop abgeschlossen |
| `auto_shutdown` | Automatischer Stop wegen Inaktivität |
| `auto_shutdown_complete` | Auto-Stop abgeschlossen |
---
## Auto-Shutdown
Der Auto-Shutdown Mechanismus stoppt die Instanz automatisch bei Inaktivität:
1. Bei jedem LLM-Request wird `/activity` aufgerufen
2. Ein Hintergrund-Task prüft alle 60s die letzte Aktivität
3. Nach `VAST_AUTO_SHUTDOWN_MINUTES` ohne Aktivität wird gestoppt
4. Session-Kosten werden berechnet und geloggt
**Konfiguration:**
```bash
VAST_AUTO_SHUTDOWN=true # Feature aktivieren
VAST_AUTO_SHUTDOWN_MINUTES=30 # Timeout in Minuten
```
---
## Konfiguration
Umgebungsvariablen in `.env`:
```bash
# vast.ai Credentials
VAST_API_KEY=your-vast-api-key # von https://cloud.vast.ai/cli/
VAST_INSTANCE_ID=12345 # numerische Instance ID
# Admin-Schutz
CONTROL_API_KEY=your-control-key # generieren mit: openssl rand -hex 32
# Health Check
VAST_HEALTH_PORT=8001 # Port auf der Instanz
VAST_HEALTH_PATH=/health # Health-Endpoint
VAST_WAIT_TIMEOUT_S=600 # Timeout beim Start (10 min)
# Auto-Shutdown
VAST_AUTO_SHUTDOWN=true
VAST_AUTO_SHUTDOWN_MINUTES=30
# State Persistence (optional)
VAST_STATE_PATH=./vast_state.json
VAST_AUDIT_PATH=./vast_audit.log
```
---
## Architektur
```
┌─────────────────────────────────────────────────────────────────┐
│ Admin Panel (Browser) │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ GPU Infra Tab │ │
│ │ [Start] [Stop] [Refresh] Status: Running │ │
│ │ GPU: RTX 3090 Cost: $0.45/h Session: 25 min │ │
│ │ Auto-Shutdown in: 5 min │ │
│ └─────────────────────────────────────────────────────────┘ │
└────────────────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Breakpilot Backend │
│ ┌───────────────────┐ ┌───────────────────┐ │
│ │ /infra/vast/* │ │ Auto-Shutdown │ │
│ │ (FastAPI Router) │ │ Background Task │ │
│ └─────────┬─────────┘ └─────────┬─────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────────────┐ │
│ │ VastAIClient │ │
│ │ (REST API zu vast.ai Console) │ │
│ └─────────────────────────────────────────────┘ │
└────────────────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ vast.ai Cloud API │
│ https://console.vast.ai/api/v0/ │
└────────────────────────────┬────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ vast.ai GPU Instance │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ Docker Container: vLLM │ │
│ │ - Model: Mistral-7B-Instruct │ │
│ │ - Port 8000: /v1/chat/completions │ │
│ │ - Port 8001: /health (nginx proxy) │ │
│ └───────────────────────────────────────────────────────┘ │
│ GPU: RTX 3090 (24GB VRAM) │
└─────────────────────────────────────────────────────────────────┘
```
---
## vast.ai Instance Setup
### 1. Instance buchen
- Typ: **On-Demand** (nicht Contract)
- GPU: **RTX 3090** (24GB) oder **RTX 4090**
- RAM: >= 32 GB
- Disk: >= 150 GB
- Interruptible: **Nein** (Non-interruptible)
### 2. vLLM mit systemd autostart
Auf der vast.ai Instanz:
```bash
# Docker Compose erstellen
mkdir -p ~/llm-stack
cd ~/llm-stack
# docker-compose.yml und health-nginx.conf erstellen
# (siehe vast.ai Implementierung.docx)
# Systemd Service erstellen
sudo tee /etc/systemd/system/llm-stack.service > /dev/null <<'EOF'
[Unit]
Description=LLM Stack via Docker Compose
After=docker.service
[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/home/ubuntu/llm-stack
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl enable llm-stack.service
sudo systemctl start llm-stack.service
```
### 3. Backend konfigurieren
```bash
# .env
VAST_API_KEY=vast_...
VAST_INSTANCE_ID=12345
CONTROL_API_KEY=$(openssl rand -hex 32)
```
---
## Fehlerbehandlung
| Fehler | Ursache | Lösung |
|--------|---------|--------|
| 500: VAST_API_KEY not configured | ENV nicht gesetzt | `.env` prüfen |
| 502: vast CLI failed | vast.ai API Fehler | Instance ID prüfen |
| 504: Health check timeout | vLLM startet nicht | SSH auf Instanz, Logs prüfen |
| Instance stuck in scheduling | GPU nicht verfügbar | Andere GPU wählen |
---
## Kosten-Beispiele
| GPU | $/Stunde | 1h Test | 8h Tag |
|-----|----------|---------|--------|
| RTX 3090 | ~$0.45 | $0.45 | $3.60 |
| RTX 4090 | ~$0.75 | $0.75 | $6.00 |
**Mit Auto-Shutdown (30 min):**
- Vergessen auszuschalten: max. $0.23 (3090) bzw. $0.38 (4090) extra