From 2a0449c9b777f4aa0ec2f4a13b8ed61bb4121ca9 Mon Sep 17 00:00:00 2001 From: Benjamin Admin Date: Fri, 20 Mar 2026 08:16:07 +0100 Subject: [PATCH] docs(qa): add Control Quality Pipeline documentation QA process, article types, match rates, preamble dedup rules, and next steps documented in MkDocs under Entwicklung. Co-Authored-By: Claude Opus 4.6 --- docs-src/development/qa-control-quality.md | 133 +++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 134 insertions(+) create mode 100644 docs-src/development/qa-control-quality.md diff --git a/docs-src/development/qa-control-quality.md b/docs-src/development/qa-control-quality.md new file mode 100644 index 0000000..7b26c43 --- /dev/null +++ b/docs-src/development/qa-control-quality.md @@ -0,0 +1,133 @@ +# 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 diff --git a/mkdocs.yml b/mkdocs.yml index 6af017b..76949f5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -114,3 +114,4 @@ nav: - Testing: development/testing.md - Dokumentation: development/documentation.md - CI/CD Pipeline: development/ci-cd-pipeline.md + - QA Control Quality: development/qa-control-quality.md