breakpilot-compliance/docs-src/services/sdk-modules/vvt.md

# VVT — Verzeichnis von Verarbeitungstaetigkeiten (Art. 30 DSGVO)

Das VVT-Modul implementiert das Verarbeitungsverzeichnis gemaess Art. 30 DSGVO mit einer
3-Schichten-Architektur: **Master-Libraries** (globale Stammdaten) + **Prozess-Templates**
(vorgefertigte Verarbeitungsvorlagen) + **Tenant-Instanzen** (individuelle Verarbeitungstaetigkeiten).

**Route:** `/sdk/vvt` | **Backend:** `backend-compliance:8002` | **Migrationen:** `006`, `033`, `035`, `064`-`067`

---

## Uebersicht

| Checkpoint | Reviewer | Rechtsgrundlage | Status |
|-----------|----------|-----------------|--------|
| CP-VVT (REQUIRED) | DSB | Art. 30 DSGVO | Phase 1 abgeschlossen |

**Wann ist ein VVT Pflicht?**

Jeder Verantwortliche und jeder Auftragsverarbeiter muss ein Verzeichnis aller
Verarbeitungstaetigkeiten fuehren (Art. 30 Abs. 1 und Abs. 2 DSGVO). Ausnahmen gelten
nur fuer Unternehmen mit weniger als 250 Beschaeftigten — und auch nur dann, wenn die
Verarbeitung kein Risiko birgt, nur gelegentlich erfolgt und keine besonderen Datenkategorien
(Art. 9/10 DSGVO) betroffen sind. In der Praxis entfaellt die Ausnahme fast nie.

---

## 3-Schichten-Architektur

Das VVT-Modul arbeitet mit drei Abstraktionsebenen:

```mermaid
graph TD
    A[Ebene A: Master-Libraries] -->|IDs referenzieren| B[Ebene B: Prozess-Templates]
    B -->|Instanziierung| C[Ebene C: Tenant-Aktivitaeten]
    A -->|Direkte Auswahl| C
```

### Ebene A — Master-Libraries (Global)

8 globale Referenztabellen, die **ohne `tenant_id`** arbeiten und allen Mandanten zur Verfuegung stehen:

| Library | Tabelle | Eintraege | Beschreibung |
|---------|---------|-----------|-------------|
| Betroffenenkategorien | `vvt_lib_data_subjects` | 15 | Mitarbeiter, Kunden, Bewerber, ... |
| Datenkategorien | `vvt_lib_data_categories` | 35 | Hierarchisch mit Parent/Child (9 Oberkategorien + 26 Unterkategorien) |
| Empfaenger | `vvt_lib_recipients` | 15 | Intern, Auftragsverarbeiter, Behoerden |
| Rechtsgrundlagen | `vvt_lib_legal_bases` | 12 | Art. 6, Art. 9, BDSG, UWG |
| Loeschfristen | `vvt_lib_retention_rules` | 12 | HGB 10J, AO 6J/10J, AGG 6M, ... |
| Transfermechanismen | `vvt_lib_transfer_mechanisms` | 8 | Angemessenheit, SCC, BCR, DPF, ... |
| Verarbeitungszwecke | `vvt_lib_purposes` | 20 | Personalverwaltung, CRM, Analytics, ... |
| TOMs | `vvt_lib_toms` | 20 | RBAC, MFA, Verschluesselung, Backup, ... |

#### Datenkategorien-Hierarchie

Die Datenkategorien sind zweistufig organisiert:

| Oberkategorie | Unterkategorien | Art. 9 |
|--------------|----------------|--------|
| Identifikationsdaten | Name, Geburtsdatum, Ausweisnummer, SV-Nummer | Nein |
| Kontaktdaten | Anschrift, Kontaktinformationen | Nein |
| Finanzdaten | Steuer-ID, Bankverbindung, Zahlungsdaten, Gehaltsdaten | Nein |
| Beschaeftigungsdaten | Arbeitsvertragsdaten, Ausbildungsdaten | Nein |
| Digitale Identitaet | IP-Adresse, Geraete-ID, Zugangsdaten, Nutzungsdaten | Nein |
| Kommunikationsdaten | Korrespondenz, Vertragsdaten | Nein |
| Medien- und Standortdaten | Bild/Video, Standortdaten | Nein |
| Besondere Kategorien (Art. 9) | Gesundheit, Genetik, Biometrie, Ethnische Herkunft, Politische Meinungen, Religion, Gewerkschaft, Sexualleben | **Ja** |
| Strafrechtliche Daten (Art. 10) | Verurteilungen, Straftaten | Art. 10 |

### Ebene B — Prozess-Templates (System + Tenant)

18 vorgefertigte Prozess-Templates, die Library-IDs referenzieren und mit einem Klick
in eine VVT-Aktivitaet instanziiert werden koennen:

| Template-ID | Name | Business Function | Loeschfrist |
|-------------|------|-------------------|-------------|
| `hr-mitarbeiterverwaltung` | Mitarbeiterverwaltung | Personal | 10 Jahre (HGB) |
| `hr-gehaltsabrechnung` | Gehaltsabrechnung | Personal | 10 Jahre (AO) |
| `hr-bewerbermanagement` | Bewerbermanagement | Personal | 6 Monate (AGG) |
| `hr-zeiterfassung` | Zeiterfassung | Personal | 2 Jahre (ArbZG) |
| `finance-buchhaltung` | Buchhaltung | Finanzen | 10 Jahre (HGB) |
| `finance-zahlungsverkehr` | Zahlungsverkehr | Finanzen | 10 Jahre (HGB) |
| `sales-kundenverwaltung` | Kundenverwaltung | Vertrieb | 3 Jahre (BGB) |
| `sales-vertriebssteuerung` | Vertriebssteuerung | Vertrieb | 3 Jahre (BGB) |
| `marketing-newsletter` | Newsletter-Versand | Marketing | Bis Widerruf |
| `marketing-website-analytics` | Website-Analyse | Marketing | 14 Monate |
| `marketing-social-media` | Social-Media-Marketing | Marketing | Bis Zweckerfuellung |
| `support-ticketsystem` | Ticketsystem | Support | 3 Jahre (BGB) |
| `it-systemadministration` | IT-Systemadministration | IT | 90 Tage |
| `it-backup` | Datensicherung | IT | 90 Tage |
| `it-logging` | Logging und Ueberwachung | IT | 90 Tage |
| `it-iam` | Identitaetsmanagement | IT | 6 Monate (AGG) |
| `other-videokonferenz` | Videokonferenz | Sonstiges | Bis Zweckerfuellung |
| `other-besuchermanagement` | Besuchermanagement | Sonstiges | 30 Tage |

### Ebene C — Tenant-Aktivitaeten

Individuelle Verarbeitungstaetigkeiten pro Mandant. Jede Aktivitaet kann sowohl
**Freitext-Felder** (bestehendes Schema) als auch **Library-Referenzen** (neue `*_refs`-Felder)
enthalten. Beide existieren parallel — die Library-Referenzen ergaenzen die Freitext-Felder
fuer strukturierte Auswertungen und Cross-Modul-Verknuepfungen.

---

## Funktionen

- **CRUD-Operationen:** Anlegen, Lesen, Aktualisieren, Loeschen von VVT-Aktivitaeten
- **Organisations-Header:** DSB-Kontakt, VVT-Version, Pruefintervall
- **Template-Instanziierung:** Neue Aktivitaet aus Prozess-Template erstellen (inkl. automatischer Freitext-Befuellung)
- **Library-Referenzen:** Strukturierte Auswahl aus 8 Master-Libraries (parallel zu Freitext)
- **Art. 30 Completeness-Check:** Automatische Bewertung der Pflichtfelder-Vollstaendigkeit
- **Scope-basierte Generierung:** Automatische Erstellung von Aktivitaeten aus Compliance-Scope-Antworten
- **Status-Workflow:** `DRAFT` -> `REVIEW` -> `APPROVED` / `ARCHIVED`
- **Export:** JSON und CSV (Excel-kompatibel mit BOM, Semikolon-getrennt)
- **Audit-Log:** Protokollierung aller Aktionen (CREATE / UPDATE / DELETE / EXPORT)
- **Statistiken:** Zaehler nach Status, Geschaeftsbereich, DSFA-Pflicht, Drittlandtransfers
- **Cross-Modul-Links:** Verknuepfung zu Loeschfristen und TOM-Massnahmen (Phase 2)

---

## API-Endpoints

### Aktivitaeten (CRUD)

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/vvt/activities` | Liste (Filter: status, business_function, search, review_overdue) |
| `POST` | `/vvt/activities` | Neue Aktivitaet anlegen -> HTTP 201 |
| `GET` | `/vvt/activities/{id}` | Einzelne Aktivitaet abrufen |
| `PUT` | `/vvt/activities/{id}` | Aktivitaet aktualisieren |
| `DELETE` | `/vvt/activities/{id}` | Aktivitaet loeschen |
| `GET` | `/vvt/activities/{id}/completeness` | Art. 30 Vollstaendigkeits-Check |
| `GET` | `/vvt/activities/{id}/versions` | Versionshistorie |

### Organisation

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/vvt/organization` | Organisations-Header laden |
| `PUT` | `/vvt/organization` | Organisations-Header speichern (Upsert) |

### Export & Statistik

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/vvt/export?format=json` | JSON-Export aller Aktivitaeten |
| `GET` | `/vvt/export?format=csv` | CSV-Export (Semikolon, UTF-8 BOM) |
| `GET` | `/vvt/stats` | Statistik-Zusammenfassung |
| `GET` | `/vvt/audit-log` | Audit-Trail (limit, offset) |

### Master-Libraries (read-only, global)

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/vvt/libraries` | Uebersicht: alle 8 Library-Typen mit Anzahl |
| `GET` | `/vvt/libraries/data-subjects` | Betroffenenkategorien (Filter: `typical_for`) |
| `GET` | `/vvt/libraries/data-categories` | Datenkategorien — hierarchisch oder `?flat=true` (Filter: `parent_id`, `is_art9`) |
| `GET` | `/vvt/libraries/recipients` | Empfaenger (Filter: `type`) |
| `GET` | `/vvt/libraries/legal-bases` | Rechtsgrundlagen (Filter: `is_art9`, `type`) |
| `GET` | `/vvt/libraries/retention-rules` | Loeschfristen mit Dauer, Einheit, Rechtsgrundlage |
| `GET` | `/vvt/libraries/transfer-mechanisms` | Uebermittlungsmechanismen |
| `GET` | `/vvt/libraries/purposes` | Verarbeitungszwecke (Filter: `typical_for`) |
| `GET` | `/vvt/libraries/toms` | Technisch-Organisatorische Massnahmen (Filter: `category`) |

### Prozess-Templates

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/vvt/templates` | Alle Templates (Filter: `business_function`, `search`) |
| `GET` | `/vvt/templates/{id}` | Einzelnes Template mit aufgeloesten Library-Labels |
| `POST` | `/vvt/templates/{id}/instantiate` | VVT-Aktivitaet aus Template erstellen -> HTTP 201 |

!!! info "Proxy-Route (Frontend)"
    Das Admin-Frontend ruft die Endpoints ueber den Next.js-Proxy auf:
    `/api/sdk/v1/compliance/vvt/**` -> `backend-compliance:8002/api/compliance/vvt/**`

---

## Datenfluss: Template-Instanziierung

```mermaid
sequenceDiagram
    participant F as Frontend
    participant B as Backend
    participant DB as PostgreSQL

    F->>B: POST /vvt/templates/hr-mitarbeiterverwaltung/instantiate
    B->>DB: SELECT FROM vvt_process_templates WHERE id = 'hr-mitarbeiterverwaltung'
    DB-->>B: Template mit Library-Referenzen

    Note over B: Fuer jeden ref-Typ:<br/>Library-IDs -> Labels aufloesen

    B->>DB: SELECT FROM vvt_lib_purposes WHERE id IN ('EMPLOYMENT_ADMIN', 'PAYROLL')
    DB-->>B: Labels: "Personalverwaltung", "Gehaltsabrechnung"

    B->>DB: SELECT FROM vvt_lib_retention_rules WHERE id = 'HGB_257_10Y'
    DB-->>B: "10 Jahre (HGB § 257)"

    Note over B: Neue VVT-Aktivitaet erstellen:<br/>- Freitext-Felder mit Labels befuellt<br/>- *_refs-Felder mit Library-IDs

    B->>DB: INSERT INTO compliance_vvt_activities (...)
    B->>DB: INSERT INTO compliance_vvt_audit_log (action='CREATE', ...)
    DB-->>B: Neue Aktivitaet mit UUID

    B-->>F: 201 Created + VVTActivityResponse
    F->>F: Wechsel zu Editor-Tab
```

---

## Datenmodell

### VVT-Aktivitaet (Response) — vollstaendig

```json
{
  "id": "uuid",
  "vvt_id": "VVT-0001",
  "name": "Mitarbeiterverwaltung",
  "description": "Verwaltung des Beschaeftigungsverhaeltnisses",
  "status": "DRAFT",
  "business_function": "hr",

  "purposes": ["Personalverwaltung", "Gehaltsabrechnung"],
  "legal_bases": [{"type": "BDSG_26", "description": "Beschaeftigtenverhaeltnis"}],
  "data_subject_categories": ["Beschaeftigte"],
  "personal_data_categories": ["Name", "Geburtsdatum", "Bankverbindung"],
  "recipient_categories": [{"type": "INTERNAL", "name": "Personalabteilung"}],
  "third_country_transfers": [],
  "retention_period": {
    "description": "10 Jahre (HGB § 257)",
    "legalBasis": "HGB § 257",
    "deletionProcedure": "Vernichtung",
    "duration": 10,
    "durationUnit": "YEARS"
  },
  "tom_description": "Rollenbasierte Zugriffskontrolle, Verschluesselung",
  "structured_toms": {
    "accessControl": ["RBAC", "Need-to-Know"],
    "confidentiality": ["Verschluesselung ruhender Daten"],
    "integrity": ["Audit-Logging"],
    "availability": [],
    "separation": ["Mandantentrennung"]
  },

  "systems": [{"systemId": "HR-Software", "name": "HR-Software"}],
  "deployment_model": "cloud",
  "protection_level": "HIGH",
  "dpia_required": true,
  "responsible": "Max Mustermann",
  "owner": "Personalabteilung",

  "purpose_refs": ["EMPLOYMENT_ADMIN", "PAYROLL"],
  "legal_basis_refs": ["BDSG_26", "ART6_1B"],
  "data_subject_refs": ["EMPLOYEES"],
  "data_category_refs": ["NAME", "DOB", "ADDRESS", "BANK_ACCOUNT", "EMPLOYMENT_DATA"],
  "recipient_refs": ["INTERNAL_HR", "INTERNAL_FINANCE", "PROCESSOR_PAYROLL"],
  "retention_rule_ref": "HGB_257_10Y",
  "transfer_mechanism_refs": null,
  "tom_refs": ["AC_RBAC", "AC_NEED_TO_KNOW", "CONF_ENCRYPTION_REST", "INT_AUDIT_LOG"],
  "source_template_id": "hr-mitarbeiterverwaltung",
  "risk_score": 3,
  "linked_loeschfristen_ids": null,
  "linked_tom_measure_ids": null,
  "art30_completeness": {
    "score": 90,
    "missing": ["responsible"],
    "warnings": [],
    "passed": 9,
    "total": 10
  },

  "created_at": "2026-03-19T10:00:00Z",
  "updated_at": "2026-03-19T12:30:00Z"
}
```

!!! warning "Dual-Schema: Freitext + Library-Referenzen"
    Jede Aktivitaet hat **zwei parallele Repraesentationen** fuer Datenkategorien,
    Betroffene, Zwecke etc.: Die bestehenden Freitext-Felder (`purposes`, `legal_bases`, ...)
    und die neuen Library-Referenz-Felder (`purpose_refs`, `legal_basis_refs`, ...).
    Beide existieren parallel. Bei Template-Instanziierung werden beide automatisch befuellt.
    Bestehende Aktivitaeten ohne `*_refs` bleiben voll funktionsfaehig.

### Art. 30 Completeness-Check

Der Completeness-Endpoint prueft 10 Pflichtfelder nach Art. 30 Abs. 1 DSGVO:

| Nr. | Pruefung | Quelle |
|-----|---------|--------|
| 1 | Name der Verarbeitung | `name` |
| 2 | Verarbeitungszweck(e) | `purposes` ODER `purpose_refs` |
| 3 | Rechtsgrundlage | `legal_bases` ODER `legal_basis_refs` |
| 4 | Betroffenenkategorien | `data_subject_categories` ODER `data_subject_refs` |
| 5 | Datenkategorien | `personal_data_categories` ODER `data_category_refs` |
| 6 | Empfaenger | `recipient_categories` ODER `recipient_refs` |
| 7 | Drittland-Uebermittlung | Immer bestanden (kein Transfer ist valide) |
| 8 | Loeschfristen | `retention_period.description` ODER `retention_rule_ref` |
| 9 | TOM-Beschreibung | `tom_description` ODER `tom_refs` ODER `structured_toms` |
| 10 | Verantwortlicher | `responsible` |

**Warnings** (nicht im Score, aber angezeigt):

- `dpia_required_but_no_dsfa_linked` — DSFA erforderlich, aber keine DSFA verknuepft
- `third_country_transfer_without_mechanism` — Drittlandtransfer ohne Transfermechanismus

```json
{
  "score": 80,
  "missing": ["retention_period", "responsible"],
  "warnings": ["dpia_required_but_no_dsfa_linked"],
  "passed": 8,
  "total": 10
}
```

---

## Library-Datenmodell

### Master-Library-Eintrag (allgemein)

```json
{
  "id": "EMPLOYEES",
  "label_de": "Beschaeftigte",
  "description_de": "Aktuelle Mitarbeiterinnen und Mitarbeiter",
  "sort_order": 1
}
```

### Datenkategorie (hierarchisch)

```json
{
  "id": "IDENTIFICATION",
  "label_de": "Identifikationsdaten",
  "children": [
    {
      "id": "NAME",
      "parent_id": "IDENTIFICATION",
      "label_de": "Name",
      "is_art9": false,
      "risk_weight": 1
    },
    {
      "id": "DOB",
      "parent_id": "IDENTIFICATION",
      "label_de": "Geburtsdatum",
      "is_art9": false,
      "risk_weight": 2
    }
  ]
}
```

### Loeschfrist (Retention Rule)

```json
{
  "id": "HGB_257_10Y",
  "label_de": "10 Jahre (HGB § 257)",
  "legal_basis": "HGB § 257",
  "duration": 10,
  "duration_unit": "YEARS",
  "start_event": "Ende des Kalenderjahres",
  "deletion_procedure": "Vernichtung nach Ablauf der Aufbewahrungsfrist"
}
```

### Prozess-Template

```json
{
  "id": "hr-mitarbeiterverwaltung",
  "name": "Mitarbeiterverwaltung",
  "business_function": "hr",
  "purpose_refs": ["EMPLOYMENT_ADMIN", "PAYROLL"],
  "legal_basis_refs": ["BDSG_26", "ART6_1B"],
  "data_subject_refs": ["EMPLOYEES"],
  "data_category_refs": ["NAME", "DOB", "ADDRESS", "CONTACT", "SOCIAL_SECURITY", "BANK_ACCOUNT", "EMPLOYMENT_DATA", "HEALTH_DATA"],
  "recipient_refs": ["INTERNAL_HR", "INTERNAL_FINANCE", "PROCESSOR_PAYROLL"],
  "tom_refs": ["AC_RBAC", "AC_NEED_TO_KNOW", "CONF_ENCRYPTION_REST", "INT_AUDIT_LOG"],
  "retention_rule_ref": "HGB_257_10Y",
  "typical_systems": ["HR-Software", "Personalakte (digital)"],
  "protection_level": "HIGH",
  "dpia_required": true,
  "risk_score": 3,
  "tags": ["personal", "pflicht"]
}
```

---

## Status-Workflow

```mermaid
stateDiagram-v2
    [*] --> DRAFT : Neue Aktivitaet
    DRAFT --> REVIEW : Zur Pruefung
    REVIEW --> APPROVED : Genehmigt
    REVIEW --> DRAFT : Zurueck zu Entwurf
    APPROVED --> REVIEW : Erneute Pruefung
    APPROVED --> ARCHIVED : Archivieren
    ARCHIVED --> DRAFT : Reaktivieren
```

---

## DB-Tabellen

### Migrationshistorie

| Migration | Datei | Inhalt |
|-----------|-------|--------|
| 006 | `006_vvt.sql` | Initiale VVT-Tabellen (organization, activities, audit_log) |
| 033 | `033_vvt_consolidation.sql` | Schema-Konsolidierung |
| 035 | `035_vvt_tenant_isolation.sql` | Tenant-Isolation |
| **064** | `064_vvt_master_libraries.sql` | 8 Library-Tabellen (global) |
| **065** | `065_vvt_library_seed.sql` | Seed-Daten (~150 Eintraege) |
| **066** | `066_vvt_process_templates.sql` | Template-Tabelle + 13 neue Spalten auf `compliance_vvt_activities` |
| **067** | `067_vvt_process_templates_seed.sql` | 18 Prozess-Templates |

### Tabellen-Uebersicht

| Tabelle | Typ | Tenant-scoped | Eintraege |
|---------|-----|--------------|-----------|
| `compliance_vvt_organization` | Daten | Ja | 1 pro Tenant |
| `compliance_vvt_activities` | Daten | Ja | n pro Tenant |
| `compliance_vvt_audit_log` | Audit | Ja | Unbegrenzt |
| `vvt_lib_data_subjects` | Library | **Nein** (global) | 15 |
| `vvt_lib_data_categories` | Library | **Nein** (global) | 35 |
| `vvt_lib_recipients` | Library | **Nein** (global) | 15 |
| `vvt_lib_legal_bases` | Library | **Nein** (global) | 12 |
| `vvt_lib_retention_rules` | Library | **Nein** (global) | 12 |
| `vvt_lib_transfer_mechanisms` | Library | **Nein** (global) | 8 |
| `vvt_lib_purposes` | Library | **Nein** (global) | 20 |
| `vvt_lib_toms` | Library | **Nein** (global) | 20 |
| `vvt_process_templates` | Hybrid | System + Tenant | 18 (System) |

---

## Datei-Uebersicht

### Backend

| Datei | Beschreibung |
|-------|-------------|
| `compliance/db/vvt_models.py` | SQLAlchemy Models: Organization, Activity, AuditLog |
| `compliance/db/vvt_library_models.py` | SQLAlchemy Models: 8 Libraries + ProcessTemplate |
| `compliance/api/vvt_routes.py` | Activity CRUD, Export, Stats, Completeness |
| `compliance/api/vvt_library_routes.py` | Library GET-Endpoints, Template CRUD + Instantiate |
| `compliance/api/schemas.py` | Pydantic Schemas (VVTActivityCreate/Update/Response) |

### Frontend

| Datei | Beschreibung |
|-------|-------------|
| `admin-compliance/app/sdk/vvt/page.tsx` | VVT-Seite (3 Tabs: Verzeichnis, Editor, Export) |
| `admin-compliance/lib/sdk/vvt-types.ts` | TypeScript-Typen, Library-Interfaces, Helper |
| `admin-compliance/lib/sdk/vvt-profiling.ts` | Scope-basierte Generierung |

### Migrationen

| Datei | Beschreibung |
|-------|-------------|
| `migrations/064_vvt_master_libraries.sql` | 8 Library-Tabellen |
| `migrations/065_vvt_library_seed.sql` | Seed: ~150 Eintraege |
| `migrations/066_vvt_process_templates.sql` | Template-Tabelle + 13 Spalten auf Activities |
| `migrations/067_vvt_process_templates_seed.sql` | Seed: 18 Prozess-Templates |

---

## Tests

```bash
# Backend: Alle VVT-Tests (Library + Routes)
cd backend-compliance && python3 -m pytest tests/test_vvt_library_routes.py tests/test_vvt_routes.py -v

# Backend: Nur Library-Tests (54 Tests)
python3 -m pytest tests/test_vvt_library_routes.py -v

# Backend: Nur bestehende VVT-Tests (49 Tests)
python3 -m pytest tests/test_vvt_routes.py -v

# Frontend: Scope → VVT Integration (35 Tests)
cd admin-compliance && npx vitest run lib/sdk/__tests__/vvt-scope-integration.test.ts
```

### Testabdeckung

| Testdatei | Tests | Abdeckung |
|-----------|-------|-----------|
| `test_vvt_library_routes.py` | 54 | Models, Helpers, Endpoints, Completeness, Schema-Compat |
| `test_vvt_routes.py` | 49 | CRUD, Export, Stats, Audit, Organization |
| `vvt-scope-integration.test.ts` | 35 | Profile→Scope Prefill, Scope→VVT Export, Generator, Full Pipeline, Dept. Data Categories, Block 9 Mapping |
| **Gesamt** | **138** | |

---

## Frontend: 5-Tab-Aufbau

### Tab 1: Verzeichnis

- **Statistik-Kacheln:** Gesamt, Genehmigt, Entwurf, Drittland, Art. 9
- **Filter:** Status, Drittland, Art. 9
- **Suche:** VVT-ID, Name, Beschreibung
- **Sortierung:** Name, Datum, Status
- **"Aus Vorlage erstellen":** Template-Picker-Modal mit 18 Templates, filterbar nach Geschaeftsbereich
- **"Neue Verarbeitung":** Leere Aktivitaet erstellen
- **"Aus Scope generieren":** Automatische Generierung aus Compliance-Scope-Antworten

### Tab 2: Editor

- **Formular-Sections:** Grunddaten, Zwecke, Rechtsgrundlagen, Betroffene, Datenkategorien, Empfaenger, Drittlandtransfers, Loeschfristen, TOMs, Systeme, Datenquellen, Datenfluesse
- **Library-Unterstuetzung:** Dropdown-Auswahl aus Master-Libraries fuer alle strukturierten Felder
- **Freitext-Fallback:** Manuelle Eingabe bleibt immer moeglich

### Tab 3: Export & Compliance

- **Compliance-Check:** Pruefung aller Pflichtfelder nach Art. 30 DSGVO
- **Art. 30 Vollstaendigkeit:** Pro-Aktivitaet-Fortschrittsbalken
- **Organisations-Header:** DSB-Kontakt, Version, Pruefintervall
- **JSON-Export:** Vollstaendiger Export aller Aktivitaeten + Metadaten
- **CSV-Export:** Excel-kompatibel (Semikolon, UTF-8 BOM)
- **Statistik:** Zaehler nach Geschaeftsbereichen und Datenkategorien

### Tab 4: VVT-Dokument (Druckansicht)

Generiert ein vollstaendiges, druckbares VVT-Dokument gemaess Art. 30 Abs. 1 DSGVO:

- **Deckblatt:** Organisation, DSB-Kontakt, Versionierung, Pruefintervall, Erstellungsdatum
- **Inhaltsverzeichnis:** Automatisch nummerierte Eintraege aller Verarbeitungstaetigkeiten
- **Aktivitaeten-Tabellen:** Pro Aktivitaet eine zweispaltige Tabelle mit allen Pflichtfeldern:
    - Zweck der Verarbeitung, Rechtsgrundlagen, Betroffene Personen
    - Datenkategorien (mit Art. 9/10 Kennzeichnung), Empfaengerkategorien
    - Drittlandtransfers mit Transfermechanismus
    - Loeschfristen, TOMs, Systeme, Schutzbedarfsstufe
- **Library-Aufloesung:** IDs werden automatisch zu deutschen Labels aufgeloest (DATA_SUBJECT_CATEGORY_META, PERSONAL_DATA_CATEGORY_META, LEGAL_BASIS_META, TRANSFER_MECHANISM_META)
- **PDF-Druck:** Via `window.open()` + `window.print()` — eigenstaendiges HTML mit Inline-CSS und `@media print`-Regeln fuer Seitenumbrueche
- **HTML-Download:** Vollstaendiges Dokument als HTML-Datei speicherbar

### Tab 5: Auftragsverarbeiter (Art. 30 Abs. 2)

Eigenstaendiges Verzeichnis fuer Auftragsverarbeiter-Taetigkeiten gemaess Art. 30 Abs. 2 DSGVO:

- **Pflichtfelder (Art. 30 Abs. 2):**
    - Name und Kontakt des Auftragsverarbeiters
    - Kategorien der Verarbeitungen (fuer jeden Verantwortlichen)
    - Unterauftragsverarbeiter-Kette (Name, Zweck, Land, Drittland-Kennzeichnung)
    - Drittlandtransfers mit Transfermechanismen
    - Technisch-Organisatorische Massnahmen (TOMs)
- **Editor:** Vollstaendiges Formular mit FormSection/FormField-Komponenten
- **Listenansicht:** Karten mit Auftraggeber, Anzahl Kategorien, Unterauftragnehmer, Status-Badge
- **Status-Workflow:** DRAFT → REVIEW → APPROVED → ARCHIVED
- **PDF-Druck:** Eigene Druckfunktion fuer das Auftragsverarbeiter-Verzeichnis
- **Rechtshinweis:** Infobox mit Erlaeuterung der Art. 30 Abs. 2 Anforderungen

!!! note "Datenhaltung"
    Auftragsverarbeiter-Eintraege werden aktuell im Frontend-State verwaltet.
    Backend-Persistenz (eigene DB-Tabelle + API-Endpoints) ist fuer Phase 2 geplant.

---

## Compliance-Kontext

| Verknuepftes Modul | Beziehung |
|-------------------|-----------|
| **Company Profile** | Stammdaten (DSB, Branche, Mitarbeiter, Angebote) fliessen via Scope in VVT |
| **Compliance Scope** | Scope-Antworten (Block 8+9) generieren VVT-Aktivitaeten per Knopfdruck |
| **DSFA** (Art. 35) | VVT-Aktivitaet referenziert DSFA ueber `dsfa_id` |
| **Loeschfristen** | Cross-Modul-Link ueber `linked_loeschfristen_ids` (Phase 2) |
| **TOM** (Art. 32) | Cross-Modul-Link ueber `linked_tom_measure_ids` (Phase 2) |

---

## Datenfluss: Company Profile → Compliance Scope → VVT Generator

Das VVT-Modul bezieht seine Daten aus einer **3-stufigen Pipeline**, in der keine Daten doppelt
abgefragt werden. Das Company Profile (`/sdk/company-profile`) dient als Single Source of Truth
fuer Stammdaten. Der Compliance Scope (`/sdk/compliance-scope`) fungiert als impliziter
**Daten-Verteilungs-Agent** — jede Scope-Frage deklariert per `mapsToVVTQuestion`-Eigenschaft,
welche VVT-Frage sie befuellt.

### Gesamtablauf

```mermaid
sequenceDiagram
    participant CP as Company Profile
    participant SE as Compliance Scope<br/>(Block 1-9)
    participant VG as VVT Generator
    participant DB as PostgreSQL

    Note over CP: Stammdaten:<br/>DSB, Branche, Mitarbeiter,<br/>Angebote, Geschaeftsmodell

    CP->>SE: prefillFromCompanyProfile(profile)<br/>+ getAutoFilledScoringAnswers(profile)
    Note over SE: Auto-Prefill:<br/>dpoName → org_has_dsb<br/>offerings → prod_type<br/>employeeCount → org_employee_count

    SE->>SE: Block 8: Abteilungswahl<br/>(personal, finanzen, marketing, ...)
    SE->>SE: Block 9: Datenkategorien pro Abteilung<br/>(dk_dept_hr → NAME, SALARY_DATA, ...)

    SE->>VG: exportToVVTAnswers(scopeAnswers)<br/>→ mapsToVVTQuestion-Mapping
    Note over VG: prefillFromScopeAnswers():<br/>Scope-Antworten → ProfilingAnswers

    VG->>VG: generateActivities(profilingAnswers)<br/>→ Template-Triggering + Enrichment

    VG->>DB: POST /vvt/activities (je Aktivitaet)
    Note over DB: VVT-Aktivitaeten gespeichert<br/>mit Library-Refs + Freitext
```

### Stufe 1: Company Profile → Scope (automatisches Prefill)

Beim Oeffnen des Compliance-Scope-Moduls werden Stammdaten aus dem Company Profile automatisch
in Scope-Antworten ueberfuehrt — der Nutzer muss diese Daten nicht erneut eingeben.

**Funktion:** `prefillFromCompanyProfile()` (`compliance-scope-profiling.ts:764`)

| Company Profile Feld | Scope-Frage | Mapping |
|----------------------|-------------|---------|
| `dpoName` (nicht leer) | `org_has_dsb` | `true` |
| `offerings` (WebApp) | `prod_type` | `['webapp']` |
| `offerings` (SaaS) | `prod_type` | `['saas']` |
| `offerings` (Webshop) | `prod_webshop` | `true` |

**Funktion:** `getAutoFilledScoringAnswers()` (`compliance-scope-profiling.ts:844`)

| Company Profile Feld | Scope-Frage | Zweck |
|----------------------|-------------|-------|
| `employeeCount` | `org_employee_count` | Scoring + Art. 30 Abs. 5 Pruefung |
| `annualRevenue` | `org_annual_revenue` | Scoring |
| `industry` | `org_industry` | Scoring + Branchenkontext |
| `businessModel` | `org_business_model` | Scoring |

### Stufe 2: Compliance Scope — Block 8 + Block 9

#### Block 8: Verarbeitungstaetigkeiten (Abteilungswahl)

Die Frage `vvt_departments` (Multi-Choice) bestimmt, welche Abteilungen personenbezogene Daten verarbeiten:

| Auswahl-Wert | Department-Key(s) | Beschreibung |
|--------------|-------------------|-------------|
| `personal` | `dept_hr`, `dept_recruiting` | Personal + Bewerbermanagement |
| `finanzen` | `dept_finance` | Finanzen & Buchhaltung |
| `vertrieb` | `dept_sales` | Vertrieb & CRM |
| `marketing` | `dept_marketing` | Marketing |
| `it` | `dept_it` | IT / Administration |
| `recht` | `dept_recht` | Recht / Compliance |
| `kundenservice` | `dept_support` | Kundenservice / Support |
| `produktion` | `dept_produktion` | Produktion / Fertigung |
| `logistik` | `dept_logistik` | Logistik / Versand |
| `einkauf` | `dept_einkauf` | Einkauf / Beschaffung |
| `facility` | `dept_facility` | Facility Management |

Das Mapping erfolgt in `ScopeWizardTab.tsx` ueber `DEPT_VALUE_TO_KEY`.

#### Block 9: Datenkategorien pro Abteilung

Fuer jede in Block 8 gewaehlte Abteilung wird eine eigene Frage mit spezifischen Datenkategorien angezeigt.
Die Datenkategorien stammen aus `DEPARTMENT_DATA_CATEGORIES` (`vvt-profiling.ts:306`).

**12 Abteilungen mit insgesamt ~80 Datenkategorien:**

| Abteilung | Scope-Frage | VVT-Mapping | Kategorien (Auswahl) | Art. 9 |
|-----------|-------------|-------------|---------------------|--------|
| Personal (HR) | `dk_dept_hr` | `dept_hr_categories` | Stammdaten, Gehalt, SV-Nr., Bankverbindung, Gesundheit, Religion | Gesundheit, Religion |
| Recruiting | `dk_dept_recruiting` | `dept_recruiting_categories` | Bewerberstammdaten, Bewerbungsunterlagen, Qualifikationen | Gesundheit |
| Finanzen | `dk_dept_finance` | `dept_finance_categories` | Kunden-/Lieferantendaten, Bankverbindungen, Steuer-IDs, Rechnungen | — |
| Vertrieb | `dk_dept_sales` | `dept_sales_categories` | Kontaktdaten, CRM-Daten, Kommunikation, Vertragsdaten | — |
| Marketing | `dk_dept_marketing` | `dept_marketing_categories` | E-Mail, Tracking, Consent, Social-Media, Interessenprofil | — |
| Support | `dk_dept_support` | `dept_support_categories` | Kundenstammdaten, Tickets, Kommunikation, Vertragsdaten | — |
| IT | `dk_dept_it` | `dept_it_categories` | Benutzerkonten, Logs, Geraete, Netzwerk, E-Mail, Backups | — |
| Recht | `dk_dept_recht` | `dept_recht_categories` | Vertraege, Compliance-Daten, Vorfaelle, Strafrechtliche Daten | Strafrechtlich |
| Produktion | `dk_dept_produktion` | `dept_produktion_categories` | Schichtplaene, Mitarbeiterdaten, Arbeitsschutz, Zugang | Gesundheit |
| Logistik | `dk_dept_logistik` | `dept_logistik_categories` | Empfaenger, Versandadressen, Sendungsverfolgung, Fahrer | — |
| Einkauf | `dk_dept_einkauf` | `dept_einkauf_categories` | Lieferantenkontakte, Vertraege, Bankverbindungen | — |
| Facility | `dk_dept_facility` | `dept_facility_categories` | Zutrittsdaten, Dienstleister, Videoueberwachung, Besucher | Gesundheit |

**Smart Auto-Prefill:** Beim erstmaligen Aufklappen einer Abteilungskarte werden automatisch
alle Kategorien mit `isTypical: true` vorausgewaehlt. Art.-9-Kategorien werden orange hervorgehoben.

### Stufe 3: Scope → VVT Generator

**Funktion:** `exportToVVTAnswers()` (`compliance-scope-profiling.ts:987`)

Jede Scope-Frage, die ein `mapsToVVTQuestion`-Attribut traegt, wird in das VVT-Antwort-Format
ueberfuehrt. Das Mapping ist **deklarativ** — kein imperativer Verteilungscode.

**Funktion:** `generateActivities()` (`vvt-profiling.ts:459`)

1. **Template-Triggering:** Jede VVT-Profiling-Frage hat ein `triggersTemplates`-Array. Wird eine Boolean-Frage mit `true` beantwortet, werden alle referenzierten Templates aktiviert.
2. **IT-Baseline:** Die 4 IT-Templates (Systemadministration, Backup, Logging, IAM) werden **immer** generiert.
3. **Enrichment:** `enrichActivityFromAnswers()` reichert Aktivitaeten an:
   - `transfer_cloud_us = true` → US-Drittlandtransfer mit SCC + TIA auf jede Aktivitaet
   - `data_health = true` → `HEALTH_DATA` + Art. 9 Rechtsgrundlage auf HR-Aktivitaeten
   - `data_minors = true` → `MINORS` als Betroffenenkategorie auf Support/Engineering
   - `special_ai / special_video_surveillance` → `dpiaRequired = true`
4. **Art. 30 Abs. 5 Pruefung:** `< 250 Mitarbeiter UND keine besonderen Kategorien → Ausnahme moeglich`

### 16 vorbefuellte Fragen (SCOPE_PREFILLED_VVT_QUESTIONS)

Diese VVT-Profiling-Fragen werden automatisch aus Scope-Antworten befuellt,
sodass der Nutzer sie nicht doppelt beantworten muss:

| VVT-Frage | Quelle (Scope-Block) |
|-----------|---------------------|
| `org_industry` | Block 1 (Organisation) |
| `org_employees` | Company Profile |
| `org_b2b_b2c` | Block 1 |
| `dept_hr` | Block 2/8 (Abteilungen) |
| `dept_finance` | Block 2/8 |
| `dept_marketing` | Block 2/8 |
| `data_health` | Block 2/4 (Datenkategorien) |
| `data_minors` | Block 2/4 |
| `data_biometric` | Block 2/4 |
| `data_criminal` | Block 2/4 |
| `special_ai` | Block 3/7 (Besondere Verarbeitungen) |
| `special_video_surveillance` | Block 3/4 |
| `special_tracking` | Block 3/4 |
| `transfer_cloud_us` | Block 4 (Drittland) |
| `transfer_subprocessor` | Block 4 |
| `transfer_support_non_eu` | Block 4 |

### Cross-Modul-Datenverteilung

Dasselbe deklarative Muster wird auch fuer andere Module verwendet:

| Modul | Export-Funktion | Mapping-Attribut |
|-------|----------------|-----------------|
| VVT | `exportToVVTAnswers()` | `mapsToVVTQuestion` |
| Loeschfristen | `exportToLoeschfristenAnswers()` | `mapsToLFQuestion` |
| TOM Generator | `exportToTOMProfile()` | (direkte Ableitung) |

**Bidirektionale Mappings:** `prefillFromVVTAnswers()` und `prefillFromLoeschfristenAnswers()`
ermoeglichen auch den Rueckfluss: Wenn ein Nutzer zuerst das VVT-Modul verwendet, koennen
diese Antworten in den Scope uebernommen werden.

---

## Datei-Uebersicht: Scope-Integration

| Datei | Beschreibung |
|-------|-------------|
| `lib/sdk/compliance-scope-profiling.ts` | Scope Engine: 9 Bloecke, Export-Funktionen, Company-Profile-Prefill |
| `lib/sdk/vvt-profiling.ts` | VVT-Profiling: 25 Fragen, 12 Abteilungs-Datenkategorien, Generator |
| `lib/sdk/vvt-baseline-catalog.ts` | 18 Baseline-Templates mit Freitext-Feldern |
| `components/sdk/compliance-scope/ScopeWizardTab.tsx` | Block-9-UI: Accordion, Auto-Prefill, Art.-9-Badges |
| `lib/sdk/__tests__/vvt-scope-integration.test.ts` | 35 Integrationstests fuer die gesamte Pipeline |

---

## Phase 2 — Geplante Erweiterungen

| Feature | Beschreibung |
|---------|-------------|
| Processor Records Backend | DB-Tabelle + API-Endpoints fuer Art. 30 Abs. 2 Auftragsverarbeiter |
| Link-Tabellen | M:N-Verknuepfungen VVT <-> Loeschfristen und VVT <-> TOM |
| Bidirektionaler Sync | Link-Operation aktualisiert auch Ziel-Modul |
| VVT Generator Service | Backend-basierte Auto-Fill Engine mit Company Profile + Templates |
| LibraryAutocomplete-Komponente | Wiederverwendbare Frontend-Komponente fuer alle Library-Felder |
| Word/DOCX-Export | Ergaenzung des PDF-Drucks um nativen Word-Export |