Benjamin_Boenisch/breakpilot-pwa
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
This repository has been archived on 2026-02-15. You can view files and clone it. You cannot open issues or pull requests or push a commit.
Files
cf01db2c3cb2be5cdda32ba63c852e397722da32
breakpilot-pwa/ai-compliance-sdk/docs/ARCHITECTURE.md
Benjamin Admin 21a844cb8a 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

1099 lines
60 KiB
Markdown
Raw Blame History

# UCCA - Use-Case Compliance & Feasibility Advisor
## Systemarchitektur
### 1. Übersicht
Das UCCA-System ist ein **deterministisches Compliance-Bewertungssystem** für KI-Anwendungsfälle. Es kombiniert regelbasierte Evaluation mit optionaler LLM-Erklärung und semantischer Rechtstextsuche.
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ UCCA System │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Frontend │───>│ SDK API │───>│ PostgreSQL │ │
│ │ (Next.js) │ │ (Go) │ │ Database │ │
│ └──────────────┘ └──────┬───────┘ └──────────────┘ │
│ │ │
│ ┌────────────────────┼────────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Policy │ │ Escalation │ │ Legal RAG │ │
│ │ Engine │ │ Workflow │ │ (Qdrant) │ │
│ │ (45 Regeln) │ │ (E0-E3) │ │ 2,274 Chunks │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ └────────────────────┴────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ LLM Provider │ │
│ │ (Ollama/API) │ │
│ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
### 2. Kernprinzip
> **"LLM ist NICHT die Quelle der Wahrheit. Wahrheit = Regeln + Evidenz. LLM = Übersetzer + Subsumptionshelfer"**
Das System folgt einem strikten **Human-in-the-Loop** Ansatz:
1. **Deterministische Regeln** treffen alle Compliance-Entscheidungen
2. **LLM** erklärt nur Ergebnisse, überschreibt nie BLOCK-Entscheidungen
3. **Menschen** (DSB, Legal) treffen finale Entscheidungen bei kritischen Fällen
---
## 3. Komponenten
### 3.1 Policy Engine (`internal/ucca/rules.go`)
Die Policy Engine evaluiert Use-Cases gegen ~45 deterministische Regeln.
```
┌─────────────────────────────────────────────────────────────────┐
│ Policy Engine │
├─────────────────────────────────────────────────────────────────┤
│ │
│ UseCaseIntake ──────────────────────────────────────────────> │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Regelkategorien (A-J) │ │
│ ├─────────────────────────────────────────────────────────────┤ │
│ │ A. Datenklassifikation │ R-001 bis R-006 │ 6 Regeln │ │
│ │ B. Zweck & Kontext │ R-010 bis R-013 │ 4 Regeln │ │
│ │ C. Automatisierung │ R-020 bis R-025 │ 6 Regeln │ │
│ │ D. Training vs Nutzung │ R-030 bis R-035 │ 6 Regeln │ │
│ │ E. Speicherung │ R-040 bis R-042 │ 3 Regeln │ │
│ │ F. Hosting │ R-050 bis R-052 │ 3 Regeln │ │
│ │ G. Transparenz │ R-060 bis R-062 │ 3 Regeln │ │
│ │ H. Domain-spezifisch │ R-070 bis R-074 │ 5 Regeln │ │
│ │ I. Aggregation │ R-090 bis R-092 │ 3 Regeln │ │
│ │ J. Erklärung │ R-100 │ 1 Regel │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ AssessmentResult │
│ ├── feasibility: YES | CONDITIONAL | NO │
│ ├── risk_score: 0-100 │
│ ├── risk_level: MINIMAL | LOW | MEDIUM | HIGH | CRITICAL │
│ ├── triggered_rules: []TriggeredRule │
│ ├── required_controls: []RequiredControl │
│ ├── recommended_architecture: []PatternRecommendation │
│ └── forbidden_patterns: []ForbiddenPattern │
│ │
└─────────────────────────────────────────────────────────────────┘
```
**Regel-Severities:**
- `INFO`: Informativ, kein Risiko-Impact
- `WARN`: Warnung, erhöht Risk Score
- `BLOCK`: Kritisch, führt zu `feasibility=NO`
### 3.2 Escalation Workflow (`internal/ucca/escalation_*.go`)
Das Eskalationssystem routet kritische Assessments zur menschlichen Prüfung.
```
┌─────────────────────────────────────────────────────────────────┐
│ Escalation Workflow │
├─────────────────────────────────────────────────────────────────┤
│ │
│ AssessmentResult ─────────────────────────────────────────────> │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Escalation Level Determination │ │
│ ├─────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ E0: Nur INFO-Regeln, Risk < 20 │ │
│ │ → Auto-Approve, keine menschliche Prüfung │ │
│ │ │ │
│ │ E1: WARN-Regeln, Risk 20-39 │ │
│ │ → Team-Lead Review (SLA: 24h) │ │
│ │ │ │
│ │ E2: Art.9 Daten ODER Risk 40-59 ODER DSFA empfohlen │ │
│ │ → DSB Consultation (SLA: 8h) │ │
│ │ │ │
│ │ E3: BLOCK-Regel ODER Risk ≥60 ODER Art.22 Risiko │ │
│ │ → DSB + Legal Review (SLA: 4h) │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ DSB Pool Assignment │ │
│ ├─────────────────────────────────────────────────────────────┤ │
│ │ Role │ Level │ Max Concurrent │ Auto-Assign │ │
│ │ ──────────────┼───────┼────────────────┼────────────────── │ │
│ │ team_lead │ E1 │ 10 │ Round-Robin │ │
│ │ dsb │ E2,E3 │ 5 │ Workload-Based │ │
│ │ legal │ E3 │ 3 │ Workload-Based │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Escalation Status Flow: │
│ │
│ pending → assigned → in_review → approved/rejected/returned │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### 3.3 Legal RAG (`internal/llm/legal_rag.go`)
Semantische Suche in 19 EU-Regulierungen für kontextbasierte Erklärungen.
```
┌─────────────────────────────────────────────────────────────────┐
│ Legal RAG System │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Explain Request ──────────────────────────────────────────────> │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Qdrant Vector DB │ │
│ │ Collection: bp_legal_corpus │ │
│ │ 2,274 Chunks, 1024-dim BGE-M3 │ │
│ ├─────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ EU-Verordnungen: │ │
│ │ ├── DSGVO (128) ├── AI Act (96) ├── NIS2 (128) │ │
│ │ ├── CRA (256) ├── Data Act (256) ├── DSA (256) │ │
│ │ ├── DGA (32) ├── EUCSA (32) ├── DPF (714) │ │
│ │ └── ... │ │
│ │ │ │
│ │ Deutsche Gesetze: │ │
│ │ ├── TDDDG (1) ├── SCC (32) ├── ... │ │
│ │ │ │
│ │ BSI-Standards: │ │
│ │ ├── TR-03161-1 (6) ├── TR-03161-2 (6) ├── TR-03161-3 │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ │ Hybrid Search (Dense + Sparse) │
│ │ Re-Ranking (Cross-Encoder) │
│ ▼ │
│ Top-K Relevant Passages ─────────────────────────────────────> │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ LLM Explanation │ │
│ │ Provider: Ollama (local) / Anthropic (fallback) │ │
│ │ Prompt: Assessment + Legal Context → Erklärung │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
```
---
## 4. Datenfluss
### 4.1 Assessment-Erstellung
```
User Input (Frontend)
│
▼
POST /sdk/v1/ucca/assess
│
├──────────────────────────────────────────┐
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ Policy │ │ Escalation │
│ Engine │ │ Trigger │
│ Evaluation │ │ Check │
└──────┬───────┘ └──────┬───────┘
│ │
│ AssessmentResult │ EscalationLevel
│ │
▼ ▼
┌──────────────────────────────────────────────────────┐
│ PostgreSQL │
│ ├── ucca_assessments (Assessment + Result) │
│ └── ucca_escalations (wenn Level > E0) │
└──────────────────────────────────────────────────────┘
│
│ If Level > E0
▼
┌──────────────┐
│ DSB Pool │
│ Auto-Assign │
└──────────────┘
│
▼
Notification (E-Mail/Webhook)
```
### 4.2 Erklärung mit Legal RAG
```
POST /sdk/v1/ucca/assessments/:id/explain
│
▼
┌──────────────┐
│ Load │
│ Assessment │
└──────┬───────┘
│
▼
┌──────────────┐ Query Vector ┌──────────────┐
│ Extract │ ──────────────────>│ Qdrant │
│ Keywords │ │ bp_legal_ │
│ from Rules │<───────────────────│ corpus │
└──────┬───────┘ Top-K Docs └──────────────┘
│
│ Assessment + Legal Context
▼
┌──────────────┐
│ LLM │
│ Provider │
│ Registry │
└──────┬───────┘
│
▼
Explanation (DE) + Legal References
```
---
## 5. Entscheidungsdiagramm
### 5.1 Feasibility-Entscheidung
```
UseCaseIntake
│
▼
┌─────────────────────┐
│ Hat BLOCK-Regeln? │
└──────────┬──────────┘
│ │
Ja Nein
│ │
▼ ▼
┌───────────┐ ┌─────────────────────┐
│ NO │ │ Hat WARN-Regeln? │
│ (blocked) │ └──────────┬──────────┘
└───────────┘ │ │
Ja Nein
│ │
▼ ▼
┌───────────┐ ┌───────────┐
│CONDITIONAL│ │ YES │
│(mit │ │(grünes │
│Auflagen) │ │Licht) │
└───────────┘ └───────────┘
```
### 5.2 Escalation-Level-Entscheidung
```
AssessmentResult
│
▼
┌─────────────────────┐
│ BLOCK-Regel oder │
│ Art.22 Risiko? │
└──────────┬──────────┘
│ │
Ja Nein
│ │
▼ │
┌───────────┐ │
│ E3 │ │
│ DSB+Legal │ │
└───────────┘ ▼
┌─────────────────────┐
│ Risk ≥40 oder │
│ Art.9 Daten oder │
│ DSFA empfohlen? │
└──────────┬──────────┘
│ │
Ja Nein
│ │
▼ │
┌───────────┐ │
│ E2 │ │
│ DSB │ │
└───────────┘ ▼
┌─────────────────────┐
│ Risk ≥20 oder │
│ WARN-Regeln? │
└──────────┬──────────┘
│ │
Ja Nein
│ │
▼ ▼
┌───────────┐ ┌───────────┐
│ E1 │ │ E0 │
│ Team-Lead │ │ Auto-OK │
└───────────┘ └───────────┘
```
---
## 6. Datenbank-Schema
### 6.1 ucca_assessments
```sql
CREATE TABLE ucca_assessments (
id UUID PRIMARY KEY,
tenant_id UUID NOT NULL,
namespace_id UUID,
title VARCHAR(500),
policy_version VARCHAR(50) NOT NULL,
status VARCHAR(50) DEFAULT 'completed',
-- Input
intake JSONB NOT NULL,
use_case_text_stored BOOLEAN DEFAULT FALSE,
use_case_text_hash VARCHAR(64),
domain VARCHAR(50),
-- Result
feasibility VARCHAR(20) NOT NULL,
risk_level VARCHAR(20) NOT NULL,
risk_score INT NOT NULL DEFAULT 0,
triggered_rules JSONB DEFAULT '[]',
required_controls JSONB DEFAULT '[]',
recommended_architecture JSONB DEFAULT '[]',
forbidden_patterns JSONB DEFAULT '[]',
example_matches JSONB DEFAULT '[]',
-- Flags
dsfa_recommended BOOLEAN DEFAULT FALSE,
art22_risk BOOLEAN DEFAULT FALSE,
training_allowed VARCHAR(50),
-- Explanation
explanation_text TEXT,
explanation_generated_at TIMESTAMPTZ,
explanation_model VARCHAR(100),
-- Audit
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW(),
created_by UUID NOT NULL
);
```
### 6.2 ucca_escalations
```sql
CREATE TABLE ucca_escalations (
id UUID PRIMARY KEY,
tenant_id UUID NOT NULL,
assessment_id UUID NOT NULL REFERENCES ucca_assessments(id),
-- Level & Status
escalation_level VARCHAR(10) NOT NULL,
escalation_reason TEXT,
status VARCHAR(50) NOT NULL DEFAULT 'pending',
-- Assignment
assigned_to UUID,
assigned_role VARCHAR(50),
assigned_at TIMESTAMPTZ,
-- Review
reviewer_id UUID,
reviewer_notes TEXT,
reviewed_at TIMESTAMPTZ,
-- Decision
decision VARCHAR(50),
decision_notes TEXT,
decision_at TIMESTAMPTZ,
conditions JSONB DEFAULT '[]',
-- SLA
due_date TIMESTAMPTZ,
notification_sent BOOLEAN DEFAULT FALSE,
notification_sent_at TIMESTAMPTZ,
-- Audit
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW()
);
```
### 6.3 ucca_dsb_pool
```sql
CREATE TABLE ucca_dsb_pool (
id UUID PRIMARY KEY,
tenant_id UUID NOT NULL,
user_id UUID NOT NULL,
user_name VARCHAR(255) NOT NULL,
user_email VARCHAR(255) NOT NULL,
role VARCHAR(50) NOT NULL,
is_active BOOLEAN DEFAULT TRUE,
max_concurrent_reviews INT DEFAULT 10,
current_reviews INT DEFAULT 0,
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW()
);
```
---
## 7. API-Endpunkte
### 7.1 Assessment
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| POST | `/sdk/v1/ucca/assess` | Assessment erstellen |
| GET | `/sdk/v1/ucca/assessments` | Assessments auflisten |
| GET | `/sdk/v1/ucca/assessments/:id` | Assessment abrufen |
| DELETE | `/sdk/v1/ucca/assessments/:id` | Assessment löschen |
| POST | `/sdk/v1/ucca/assessments/:id/explain` | LLM-Erklärung generieren |
| GET | `/sdk/v1/ucca/export/:id` | Assessment exportieren |
### 7.2 Kataloge
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/sdk/v1/ucca/patterns` | Architektur-Patterns |
| GET | `/sdk/v1/ucca/examples` | Didaktische Beispiele |
| GET | `/sdk/v1/ucca/rules` | Alle Regeln |
| GET | `/sdk/v1/ucca/controls` | Required Controls |
| GET | `/sdk/v1/ucca/problem-solutions` | Problem-Lösungen |
### 7.3 Eskalation
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/sdk/v1/ucca/escalations` | Eskalationen auflisten |
| GET | `/sdk/v1/ucca/escalations/:id` | Eskalation abrufen |
| POST | `/sdk/v1/ucca/escalations` | Manuelle Eskalation |
| POST | `/sdk/v1/ucca/escalations/:id/assign` | Zuweisen |
| POST | `/sdk/v1/ucca/escalations/:id/review` | Review starten |
| POST | `/sdk/v1/ucca/escalations/:id/decide` | Entscheidung treffen |
| GET | `/sdk/v1/ucca/escalations/stats` | Statistiken |
### 7.4 DSB Pool
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/sdk/v1/ucca/dsb-pool` | Pool-Mitglieder auflisten |
| POST | `/sdk/v1/ucca/dsb-pool` | Mitglied hinzufügen |
---
## 8. Sicherheit
### 8.1 Authentifizierung
- JWT-basierte Authentifizierung
- Header: `X-User-ID`, `X-Tenant-ID`
- Multi-Tenant-Isolation
### 8.2 Autorisierung
- RBAC (Role-Based Access Control)
- Permissions: `ucca:assess`, `ucca:review`, `ucca:admin`
- Namespace-Level Isolation
### 8.3 Datenschutz
- Use-Case-Text optional (Opt-in)
- SHA-256 Hash statt Klartext
- Audit-Trail für alle Operationen
- Legal RAG: `training_allowed: false`
---
## 9. Deployment
### 9.1 Container
```yaml
ai-compliance-sdk:
build: ./ai-compliance-sdk
ports:
- "8090:8090"
environment:
- DATABASE_URL=postgres://...
- OLLAMA_URL=http://ollama:11434
- QDRANT_URL=http://qdrant:6333
depends_on:
- postgres
- qdrant
```
### 9.2 Abhängigkeiten
- PostgreSQL 15+
- Qdrant 1.12+
- Embedding Service (BGE-M3)
- Ollama (optional, für LLM)
---
## 10. Monitoring
### 10.1 Health Check
```
GET /sdk/v1/health
→ {"status": "ok"}
```
### 10.2 Metriken
- Assessment-Durchsatz
- Escalation-SLA-Compliance
- LLM-Latenz
- RAG-Trefferqualität
---
---
## 11. Wizard & Legal Assistant
### 11.1 Wizard-Architektur
Der UCCA-Wizard führt Benutzer durch 9 Schritte zur Erfassung aller relevanten Compliance-Fakten.
```
┌─────────────────────────────────────────────────────────────────┐
│ UCCA Wizard v1.1 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Step 1: Grundlegende Informationen │
│ Step 2: Datenarten (Personal Data, Art. 9, etc.) │
│ Step 3: Verarbeitungszweck (Profiling, Scoring) │
│ Step 4: Hosting & Provider │
│ Step 5: Internationaler Datentransfer (SCC, TIA) │
│ Step 6: KI-Modell und Training │
│ Step 7: Verträge & Compliance (AVV, DSFA) │
│ Step 8: Automatisierung & Human Oversight │
│ Step 9: Standards & Normen (für Maschinenbauer) ← NEU │
│ │
│ Features: │
│ ├── Adaptive Subflows (visible_if Conditions) │
│ ├── Simple/Expert Mode Toggle │
│ ├── Legal Assistant Chat pro Step │
│ └── simple_explanation für Nicht-Juristen │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### 11.2 Legal Assistant (Wizard Chat)
Integrierter Rechtsassistent für Echtzeit-Hilfe bei Wizard-Fragen.
```
┌─────────────────────────────────────────────────────────────────┐
│ Legal Assistant Flow │
├─────────────────────────────────────────────────────────────────┤
│ │
│ User Question ─────────────────────────────────────────────────>│
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ Build RAG Query │ │
│ │ + Step Context │ │
│ └────────┬─────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ Search ┌──────────────────┐ │
│ │ Legal RAG │ ────────────>│ Qdrant │ │
│ │ Client │ │ bp_legal_corpus │ │
│ │ │<────────────│ + SCC Corpus │ │
│ └────────┬─────────┘ Top-5 └──────────────────┘ │
│ │ │
│ │ Question + Legal Context │
│ ▼ │
│ ┌──────────────────┐ │
│ │ Internal 32B LLM │ │
│ │ (Ollama) │ │
│ │ temp=0.3 │ │
│ └────────┬─────────┘ │
│ │ │
│ ▼ │
│ Answer + Sources + Related Fields │
│ │
└─────────────────────────────────────────────────────────────────┘
```
**API-Endpunkte:**
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/sdk/v1/ucca/wizard/schema` | Wizard-Schema abrufen |
| POST | `/sdk/v1/ucca/wizard/ask` | Frage an Legal Assistant |
---
## 12. License Policy Engine (Standards Compliance)
### 12.1 Übersicht
Die License Policy Engine verwaltet die Lizenz-/Urheberrechts-Compliance für Standards und Normen (DIN, ISO, VDI, etc.).
```
┌─────────────────────────────────────────────────────────────────┐
│ License Policy Engine │
├─────────────────────────────────────────────────────────────────┤
│ │
│ LicensedContentFacts ─────────────────────────────────────────>│
│ │ │
│ │ ├── present: bool │
│ │ ├── publisher: DIN_MEDIA | VDI | ISO | ... │
│ │ ├── license_type: SINGLE | NETWORK | ENTERPRISE | AI │
│ │ ├── ai_use_permitted: YES | NO | UNKNOWN │
│ │ ├── operation_mode: LINK | NOTES | FULLTEXT | TRAINING │
│ │ └── proof_uploaded: bool │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ Operation Mode Evaluation ││
│ ├─────────────────────────────────────────────────────────────┤│
│ │ ││
│ │ LINK_ONLY ──────────── Always Allowed ───────────> OK ││
│ │ NOTES_ONLY ─────────── Usually Allowed ──────────> OK ││
│ │ FULLTEXT_RAG ────┬──── ai_use=YES + proof ───────> OK ││
│ │ └──── else ─────────────────────> BLOCK ││
│ │ TRAINING ────────┬──── AI_LICENSE + proof ───────> OK ││
│ │ └──── else ─────────────────────> BLOCK ││
│ │ ││
│ └─────────────────────────────────────────────────────────────┘│
│ │ │
│ ▼ │
│ LicensePolicyResult │
│ ├── allowed: bool │
│ ├── effective_mode: string (may be downgraded) │
│ ├── gaps: []LicenseGap │
│ ├── required_controls: []LicenseControl │
│ ├── stop_line: *StopLine (if hard blocked) │
│ └── output_restrictions: *OutputRestrictions │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### 12.2 Betriebs-Modi (Operation Modes)
| Modus | Beschreibung | Lizenz-Anforderung | Ingest | Output |
|-------|--------------|-------------------|--------|--------|
| **LINK_ONLY** | Nur Verweise & Checklisten | Keine | Metadata only | Keine Zitate |
| **NOTES_ONLY** | Kundeneigene Zusammenfassungen | Standard | Notes only | Paraphrasen |
| **EXCERPT_ONLY** | Kurze Zitate (Zitatrecht) | Standard + Zitatrecht | Notes | Max 150 Zeichen |
| **FULLTEXT_RAG** | Volltext indexiert | AI-Lizenz + Proof | Fulltext | Max 500 Zeichen |
| **TRAINING** | Modell-Training | AI-Training-Lizenz | Fulltext | N/A |
### 12.3 Publisher-spezifische Regeln
**DIN Media (ehem. Beuth):**
- AI-Nutzung aktuell verboten (ohne explizite Genehmigung)
- AI-Lizenzmodell geplant ab Q4/2025
- Crawler/Scraper verboten (AGB)
- TDM-Vorbehalt nach §44b UrhG
### 12.4 Stop-Lines (Hard Deny)
```
STOP_DIN_FULLTEXT_AI_NOT_ALLOWED
WENN: publisher=DIN_MEDIA AND operation_mode in [FULLTEXT_RAG, TRAINING]
AND ai_use_permitted in [NO, UNKNOWN]
DANN: BLOCKIERT
FALLBACK: LINK_ONLY
STOP_TRAINING_WITHOUT_PROOF
WENN: operation_mode=TRAINING AND proof_uploaded=false
DANN: BLOCKIERT
```
---
## 13. SCC & Transfer Impact Assessment
### 13.1 Drittlandtransfer-Bewertung
Das System unterstützt die vollständige Bewertung internationaler Datentransfers.
```
┌─────────────────────────────────────────────────────────────────┐
│ SCC/Transfer Assessment Flow │
├─────────────────────────────────────────────────────────────────┤
│ │
│ hosting.region ─────────────────────────────────────────────── │
│ │ │
│ ├── EU/EWR ────────────────────────────────> OK (no SCC) │
│ │ │
│ ├── Adequacy Country (UK, CH, JP) ─────────> OK (no SCC) │
│ │ │
│ └── Third Country (US, etc.) ──────────────────────────── │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ USA: DPF-Zertifizierung prüfen ││
│ │ ├── Zertifiziert ───> OK (SCC empfohlen als Backup) ││
│ │ └── Nicht zertifiziert ───> SCC + TIA erforderlich ││
│ └─────────────────────────────────────────────────────────┘│
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────┐│
│ │ Transfer Impact Assessment (TIA) ││
│ │ ├── Adequate ─────────────> Transfer OK ││
│ │ ├── Adequate + Measures ──> + Technical Supplementary ││
│ │ ├── Inadequate ───────────> Fix required ││
│ │ └── Not Feasible ─────────> Transfer NOT allowed ││
│ └─────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────────┘
```
### 13.2 SCC-Versionen
- Neue SCC (EU 2021/914) - **erforderlich** seit 27.12.2022
- Alte SCC (vor 2021) - **nicht mehr gültig**
---
## 14. Controls Catalog
### 14.1 Übersicht
Der Controls Catalog enthält ~30 Maßnahmenbausteine mit detaillierten Handlungsanweisungen.
```
┌─────────────────────────────────────────────────────────────────┐
│ Controls Catalog v1.0 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Kategorien: │
│ ├── DSGVO (Rechtsgrundlagen, Betroffenenrechte, Dokumentation) │
│ ├── AI_Act (Transparenz, HITL, Risikoeinstufung) │
│ ├── Technical (Verschlüsselung, Anonymisierung, PII-Gateway) │
│ └── Contractual (AVV, SCC, TIA) │
│ │
│ Struktur pro Control: │
│ ├── id: CTRL-xxx │
│ ├── title: Kurztitel │
│ ├── when_applicable: Wann erforderlich? │
│ ├── what_to_do: Konkrete Handlungsschritte │
│ ├── evidence_needed: Erforderliche Nachweise │
│ ├── effort: low | medium | high │
│ └── gdpr_ref: Rechtsgrundlage │
│ │
└─────────────────────────────────────────────────────────────────┘
```
### 14.2 Beispiel-Controls
| ID | Titel | Kategorie |
|----|-------|-----------|
| CTRL-CONSENT-EXPLICIT | Ausdrückliche Einwilligung | DSGVO |
| CTRL-AI-TRANSPARENCY | KI-Transparenz-Hinweis | AI_Act |
| CTRL-DSFA | Datenschutz-Folgenabschätzung | DSGVO |
| CTRL-SCC | Standardvertragsklauseln | Contractual |
| CTRL-TIA | Transfer Impact Assessment | Contractual |
| CTRL-LICENSE-PROOF | Lizenz-/Rechte-Nachweis | License |
| CTRL-LINK-ONLY-MODE | Evidence Navigator | License |
| CTRL-PII-GATEWAY | PII-Redaction Gateway | Technical |
---
## 15. Policy-Dateien
### 15.1 Dateistruktur
```
policies/
├── ucca_policy_v1.yaml # Haupt-Policy (Regeln, Controls)
├── controls_catalog.yaml # Detaillierter Maßnahmenkatalog
├── gap_mapping.yaml # Facts → Gaps → Controls
├── wizard_schema_v1.yaml # Wizard-Fragen (9 Steps)
├── scc_legal_corpus.yaml # SCC/Transfer Rechtstexte
└── licensed_content_policy.yaml # Normen-Lizenz-Compliance (NEU)
```
### 15.2 Versions-Management
- Jedes Assessment speichert die `policy_version`
- Regeländerungen erzeugen neue Version
- Audit-Trail zeigt welche Policy-Version verwendet wurde
---
---
## 16. Generic Obligations Framework
### 16.1 Übersicht
Das Generic Obligations Framework ermöglicht die automatische Ableitung regulatorischer Pflichten aus mehreren Verordnungen basierend auf Unternehmensfakten.
```
┌─────────────────────────────────────────────────────────────────┐
│ Generic Obligations Framework │
├─────────────────────────────────────────────────────────────────┤
│ │
│ UnifiedFacts ───────────────────────────────────────────────── │
│ │ │
│ │ ├── organization: EmployeeCount, Revenue, Country │
│ │ ├── sector: PrimarySector, IsKRITIS, SpecialServices │
│ │ ├── data_protection: ProcessesPersonalData │
│ │ └── ai_usage: UsesAI, HighRiskCategories, IsGPAI │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ Obligations Registry ││
│ │ (Module Registration & Evaluation) ││
│ └──────────────────────────┬──────────────────────────────────┘│
│ │ │
│ ┌───────────────────┼───────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ NIS2 │ │ DSGVO │ │ AI Act │ │
│ │ Module │ │ Module │ │ Module │ │
│ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ │
│ │ │ │ │
│ └───────────────────┴───────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ ManagementObligationsOverview ││
│ │ ├── ApplicableRegulations[] ││
│ │ ├── Obligations[] (sortiert nach Priorität) ││
│ │ ├── RequiredControls[] ││
│ │ ├── IncidentDeadlines[] ││
│ │ ├── SanctionsSummary ││
│ │ └── ExecutiveSummary ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
└─────────────────────────────────────────────────────────────────┘
```
### 16.2 Regulation Modules
Jede Regulierung wird als eigenständiges Modul implementiert:
```go
// RegulationModule - Interface für alle Regulierungsmodule
type RegulationModule interface {
ID() string // "dsgvo", "nis2", "ai_act"
Name() string // "DSGVO", "NIS2-Richtlinie"
IsApplicable(facts *UnifiedFacts) bool // Prüft Anwendbarkeit
DeriveObligations(facts *UnifiedFacts) []Obligation
DeriveControls(facts *UnifiedFacts) []ObligationControl
DeriveIncidentDeadlines(facts *UnifiedFacts) []IncidentDeadline
GetDecisionTree() *DecisionTree // Optional
}
```
**Implementierte Module:**
| Modul | ID | Datei | Pflichten | Kontrollen |
|-------|-----|-------|-----------|------------|
| NIS2 | `nis2` | `nis2_module.go` | ~15 | ~8 |
| DSGVO | `dsgvo` | `dsgvo_module.go` | ~12 | ~6 |
| AI Act | `ai_act` | `ai_act_module.go` | ~15 | ~6 |
### 16.3 NIS2 Decision Tree
```
UnifiedFacts
│
▼
┌─────────────────────┐
│ Sektor in Anhang I │
│ ODER Anhang II? │
└──────────┬──────────┘
│ │
Ja Nein
│ │
▼ ▼
┌────────────────┐ ┌───────────────┐
│ Größenprüfung │ │ Nicht │
└────────┬───────┘ │ betroffen │
│ └───────────────┘
▼
┌─────────────────────┐
│ >= 250 MA ODER │
│ >= 50 Mio EUR │
│ ODER KRITIS │
│ ODER Spec.Services │
└──────────┬──────────┘
│ │
Ja Nein
│ │
▼ ▼
┌───────────┐ ┌─────────────────────┐
│ Besonders │ │ >= 50 MA ODER │
│ wichtige │ │ >= 10 Mio EUR? │
│ Einricht. │ └──────────┬──────────┘
└───────────┘ │ │
Ja Nein
│ │
▼ ▼
┌───────────┐ ┌───────────┐
│ Wichtige │ │ Nicht │
│ Einricht. │ │ betroffen │
└───────────┘ └───────────┘
```
### 16.4 AI Act Risk Classification
```
UnifiedFacts
│
▼
┌─────────────────────┐
│ Nutzt KI-Systeme? │
└──────────┬──────────┘
│ │
Ja Nein
│ │
▼ ▼
┌────────────────┐ ┌───────────────┐
│ Verbotene │ │ Nicht │
│ Praktik? │ │ anwendbar │
└────────┬───────┘ └───────────────┘
│
┌────┴────┐
Ja Nein
│ │
▼ ▼
┌────────────┐ ┌─────────────────────┐
│ UNACCEPT- │ │ Annex III │
│ ABLE │ │ Hochrisiko- │
│ (verboten) │ │ Kategorie? │
└────────────┘ └──────────┬──────────┘
│ │
Ja Nein
│ │
▼ ▼
┌───────────┐ ┌───────────┐
│ HIGH_RISK │ │ LIMITED/ │
│ │ │ MINIMAL │
└───────────┘ └───────────┘
```
### 16.5 PDF Export
```
┌─────────────────────────────────────────────────────────────────┐
│ PDF Export Flow │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ManagementObligationsOverview ──────────────────────────────── │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ PDFExporter ││
│ │ (gofpdf) ││
│ ├─────────────────────────────────────────────────────────────┤│
│ │ ││
│ │ ExportManagementMemo() ─────> PDF (base64) ││
│ │ ├── Titel & Metadaten ││
│ │ ├── Executive Summary ││
│ │ ├── Anwendbare Regulierungen ││
│ │ ├── Sanktions-Zusammenfassung ││
│ │ ├── Pflichten-Tabelle ││
│ │ └── Incident-Deadlines ││
│ │ ││
│ │ ExportMarkdown() ───────────> Markdown (text) ││
│ │ ││
│ └─────────────────────────────────────────────────────────────┘│
│ │ │
│ ▼ │
│ ExportMemoResponse │
│ ├── Content (base64/text) │
│ ├── ContentType (application/pdf | text/markdown) │
│ └── Filename │
│ │
└─────────────────────────────────────────────────────────────────┘
```
---
## 17. Obligations API-Endpunkte
### 17.1 Assessment
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| POST | `/sdk/v1/ucca/obligations/assess` | Pflichten-Assessment erstellen |
| GET | `/sdk/v1/ucca/obligations/:id` | Assessment abrufen |
| GET | `/sdk/v1/ucca/obligations` | Assessments auflisten |
### 17.2 Export
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| POST | `/sdk/v1/ucca/obligations/export/memo` | Memo exportieren (gespeichert) |
| POST | `/sdk/v1/ucca/obligations/export/direct` | Direkt-Export ohne Speicherung |
**Request Body (Export):**
```json
{
"overview": { ... },
"format": "pdf", // "pdf" | "markdown"
"language": "de"
}
```
**Response:**
```json
{
"content": "JVBERi0xLjQ...", // base64 für PDF
"content_type": "application/pdf",
"filename": "pflichten-memo-2026-01-29.pdf"
}
```
### 17.3 Regulations
| Method | Endpoint | Beschreibung |
|--------|----------|--------------|
| GET | `/sdk/v1/ucca/regulations` | Liste aller Regulierungsmodule |
| GET | `/sdk/v1/ucca/regulations/:id/decision-tree` | Decision Tree für Regulierung |
---
## 18. Dateien des Obligations Framework
### 18.1 Backend (Go)
```
internal/ucca/
├── obligations_framework.go # Interfaces, Typen, Konstanten
├── obligations_registry.go # Modul-Registry, EvaluateAll()
├── nis2_module.go # NIS2 Decision Tree + Pflichten
├── nis2_module_test.go # NIS2 Tests
├── dsgvo_module.go # DSGVO Pflichten
├── dsgvo_module_test.go # DSGVO Tests
├── ai_act_module.go # AI Act Risk Classification
├── ai_act_module_test.go # AI Act Tests
├── pdf_export.go # PDF/Markdown Export
└── pdf_export_test.go # Export Tests
```
### 18.2 Policy-Dateien (YAML)
```
policies/obligations/
├── nis2_obligations.yaml # ~15 NIS2-Pflichten
├── dsgvo_obligations.yaml # ~12 DSGVO-Pflichten
└── ai_act_obligations.yaml # ~15 AI Act-Pflichten
```
---
*Dokumentation erstellt: 2026-01-29*
*Version: 2.1.0*
Reference in New Issue View Git Blame Copy Permalink