# QA: Control Quality Pipeline

## Übersicht

Die Control Quality Pipeline prüft und verbessert die ~9.000 Canonical Controls der Compliance-Bibliothek. Sie nutzt **PDF-basierte Verifizierung** als Ground Truth — jeder Control-Originaltext wird direkt im Quelldokument (PDF) lokalisiert.

## Architektur

```
Original-PDFs (~/rag-ingestion/pdfs/)
        ↓
  PDF Text-Extraktion (PyMuPDF)
        ↓
  Artikel-Index aufbauen
  (Erwägungsgründe → Artikel → Anhänge)
        ↓
  source_original_text im PDF suchen
  (Substring-Match, normalisiert)
        ↓
  Artikel/§/Section zuordnen + article_type setzen
        ↓
  Duplikat-Erkennung
  (Preamble vs. Artikel: Artikel hat Vorrang)
```

## PDF-basierte Artikelzuordnung

### Konzept

Jeder Control hat ein Feld `source_original_text` — der Chunk-Text aus dem Quelldokument. Statt über Qdrant-Hashes wird dieser Text **direkt im Original-PDF gesucht**. Die Position im PDF bestimmt den Artikel.

### Dokumenttypen

| Typ | Struktur | Beispiel |
|-----|----------|---------|
| EU-Verordnung | Erwägungsgründe → Artikel → Anhänge | DSGVO, KI-VO, CRA |
| Deutsches Gesetz | §-Paragraphen | BDSG, GewO, HGB |
| NIST | Control Families (AC-1, SC-7) | SP 800-53, CSF 2.0 |
| OWASP | Kategorien (A01:2021, V1.1) | Top 10, ASVS, MASVS |
| EDPB/ENISA | Nummerierte Abschnitte | Leitlinien, Guidelines |

### Article Types

| article_type | Bedeutung | Beispiel |
|---|---|---|
| `article` | Gesetzesartikel / Paragraph | Artikel 25 DSGVO |
| `preamble` | Erwägungsgrund | Erwägungsgrund (78) |
| `annex` | Anhang | Anhang III |
| `control` | NIST Control Family | AC-6, SA-7 |
| `section` | Nummerierter Abschnitt | Section 2.1 |
| `category` | OWASP Kategorie | A01:2021 |
| `requirement` | OWASP Requirement | V1.1, MASVS-STORAGE-1 |

### Ergebnisse (Stand 2026-03-20)

| Metrik | Wert |
|---|---|
| Controls mit source_original_text | 7.943 |
| Im PDF lokalisiert | **6.259 (79%)** |
| Nicht gefunden (Sprachmismatch) | 1.651 |
| Kein PDF vorhanden | 33 |
| 100% Match-Rate | 19 Regulations (inkl. DSGVO, KI-VO, NIS2, NIST 800-53) |

### Nicht-matchende Controls

| Ursache | Controls | Erklärung |
|---|---|---|
| Blue Guide EN vs. DE PDF | ~562 | Controls aus englischem PDF, wir haben nur deutsches |
| OWASP multilingual | ~632 | Controls aus PT/AR/ID/ES-Übersetzungen |
| CRA Encoding | ~76 | PDF-Ligaturen/Sonderzeichen-Differenzen |
| CISA Secure by Design | ~113 | Falsches PDF (ENISA statt CISA) |

## Brute-Force-Suche

Für Controls mit unbekannter Quelle: Text gegen **alle ~100 PDFs** suchen. Findet:
- Korrekte Quelldokument-Zuordnung
- Falsche Source-Zuordnungen (44 entdeckt)

## Erwägungsgrund-Controls (Wettbewerbsvorteil)

Controls aus Erwägungsgründen (`article_type = preamble`) sind **kein Nachteil**. Sie decken Aspekte ab, die reine Artikel-basierte Compliance-Tools übersehen.

**Duplikat-Regel:** Wenn ein Preamble-Control das gleiche Thema wie ein Artikel-Control behandelt (Jaccard-Ähnlichkeit ≥ 0.40), hat der **Artikel Vorrang**. Das Preamble-Control wird als `duplicate` markiert.

### Ergebnis der Preamble-Dedup

| Metrik | Wert |
|---|---|
| Preamble-Controls geprüft | 838 |
| Als Duplikat markiert | 190 |
| **Unique Preamble-Controls** | **648** |

## Pipeline-Versionen

| Version | Controls | Mit Originaltext | Beschreibung |
|---|---|---|---|
| v1 | 5.332 | 4.137 (78%) | Automatisch + manuell erstellt |
| v2 | 2.258 | 2.258 (100%) | Automatisch aus Chunks |
| v3 | 1.570 | 1.548 (99%) | Neueste Pipeline |

Die 1.195 v1-Controls **ohne** Originaltext sind manuell erstellt (`strategy=ungrouped`) und haben keine Chunk-Referenz.

## DB-Status (Stand 2026-03-20)

| release_state | Count |
|---|---|
| draft | 5.365 |
| needs_review | 818 |
| duplicate | 2.674 |
| too_close | 303 |
| **Aktiv** | **6.183** |

## Scripts

Alle QA-Scripts liegen in `scripts/qa/`:

| Script | Beschreibung |
|---|---|
| `pdf_qa_all.py` | Haupt-QA: Controls gegen PDFs matchen |
| `pdf_qa_inventory.py` | Inventar: Regulations, Controls, PDFs |
| `apply_pdf_qa_results.py` | Ergebnisse in DB schreiben |
| `preamble_dedup.py` | Preamble vs. Artikel Duplikat-Erkennung |
| `qa_dedup_controls.py` | Jaccard-basierte Titel-Dedup |
| `qa_normalize_sources.py` | Source-Namen normalisieren |
| `db_status.py` | DB-Status-Übersicht |

## Nächste Schritte

1. **Blue Guide EN-PDF** beschaffen → +562 Controls matchen
2. **CISA Secure by Design** echtes PDF finden → +113 Controls
3. **Brute-Force Ergebnisse anwenden** — 44 falsche Source-Zuordnungen korrigieren
4. **Frontend-Anzeige** — `article_type` im Control-Detail anzeigen
5. **Continuous QA** — Bei neuen Controls automatisch PDF-Match prüfen