---
title: QAF-Differences — Implementation Diary
type: project
tags: [kadi-v2, qaf, KAR-799]
date: 2026-06-25
status: aktiv
---

# QAF-Differences — Diary (KAR-799)

## 2026-06-25 — Phase 1A abgeschlossen
- Spec von Kais per Telegram-Doc empfangen (`QAF-Differences_Aria-Prompt_FINAL.md`).
- Repo `/root/projekte/Kadi-v2` lokalisiert. gstack OK.
- 3 read-only Analyse-Subagents → Reports in `state/sub-agent-context/qaf-differences/`.
- **Kern-Erkenntnis:** Kein Greenfield — QAF-Stack aus KAR-90/101/102/103/339/340/341 existiert. Auftrag = Konsolidierung + Engine-Härtung + eigene Seite.
- KAR-799 angelegt (In Progress). Architekturplan + task-list + diary geschrieben.
- **3 Konflikte an Kais geflaggt (Telegram msg 7448):** Referenzdatei fehlt, Single-Tenant-vs-Spec, DDL-operator-applied.
- Telegram-Plan-Summary an Kais gesendet.

### Offen / wartet auf Kais
- Referenzdatei `QAF_Fertigungskosten_Vergleich_260608.xlsx` (+2-3 echte QAFs).
- Bestätigung Single-Tenant-Interpretation (ownership-RLS, kein Multi-Tenant).

### Phase 1B Fortschritt (25.06.2026, abends)
Branch `feature/qaf-differences` von origin/main (63fec47). Modul gescaffolded (`new:module qaf-differences --with-route --with-ui`).
- **Commit 2c80bb0:** types + normalizer (DE/EN-Zahlen, leer≠0, Pos-als-Text) + differ (abs/%/%-Punkte, B13-Status). 29 Tests.
- **Commit 226f77e:** matcher 5-Stufen-Kaskade (Pflichtkern B3) — safe/probable/possible_structure/candidate + new/removed, confidence/match_method/matched+conflicting fields/requires_review (cost-divergence-Trigger). 10 Tests (D4-Matrix). Reuse `scoreCandidate`.
- Gesamt: 39 Unit-Tests grün, tsc clean, check:boundaries + check:forbidden clean.

### Offen Phase 1B (nächste Session)
- Comparison-Orchestrator (assembliert matchSteps+diffSteps je Sachnummer → strukturiertes Ergebnis)
- Root-Cause (B8, deterministisch) — braucht Orchestrator-Output
- Plausi-Check (B12)
- Parser-Extend: Zusammenfassung-Blatt + Source-Cell-Tracking — **braucht Referenzdatei für exakte Zelladressen** (I8/C8/I5/M5/M8 aus Spec als Start)

### Update 25.06. spät — 7 Echt-QAFs erhalten + Summary-Parser
Kais schickte 7 echte QAF v8.7/8.8 (DE+EN). Lokal verifiziert (ExcelJS), **NICHT committet** (vertraulich). Struktur-Note: `02-Wissen/kadi-v2/qaf-zusammenfassung-verified-structure-2026-06-25.md`.
- Bestätigt: FK-Header Zeile 11/Daten ab 13 (bestehender Parser ok); Zusammenfassung-Layout Label-Spalten B/F/L → Werte C/I/M; Sachnummer I8 unzuverlässig (alphanum/leer in EN) → Label-Fallback nötig.
- **Commit 58dfb2f:** `summary-parser` — parseSummary (Standardzelle → Label-Scan-Fallback, DE+EN, Source-Cell pro Feld), neutrale Feldnamen (check:forbidden clean). 8 Tests.
- Anmerkung: das fertige Vergleichs-Output-Excel (`QAF_Fertigungskosten_Vergleich_260608.xlsx`, 8 Blätter) fehlt weiter — nur für Export-Treue relevant, bei Kais offen angefragt.

### Stand Engine (lib/qaf-differences) — 47 Unit-Tests grün, tsc/boundaries/forbidden clean
normalizer ✓ · differ ✓ · matcher (5-Stufen) ✓ · summary-parser ✓

### Offen Phase 1B (nächste Session)
- **Comparison-Orchestrator**: assembliert pro Sachnummer Baseline-Wahl + matchSteps + diffSteps + summary-diff → strukturiertes QafComparison-Ergebnis. (Connective tissue, danach UI/Export/Persistenz mappbar.)
- **Plausi-Check** (B12) — braucht Summary + Steps (jetzt verfügbar).
- **Root-Cause** (B8) — braucht Orchestrator-Output.
- Baseline-Logik (B5) als eigene Funktion (älteste/neueste/manuell, Status „Baseline Review").
- FK-Parser um Source-Cell-Tracking erweitern (aktuell nur Werte) — für Export-Quellenrefs.

### Update 25.06. ~22:35 — Engine-Logik KOMPLETT (Phase 1B done)
Commit 43601b6: baseline (B5) + plausibility (B12) + root-cause (B8) + compare-Orchestrator.
**8 Engine-Module, 72 Unit-Tests grün, tsc + boundaries + forbidden clean.**
Pipeline: parse → normalize → selectBaseline → matchSteps → diffSteps → structureChanges → checkPlausibility → computeRootCause, zusammengesetzt von `compareQafPair`.
Commits gesamt: 2c80bb0, 226f77e, 58dfb2f, 43601b6 (+ scaffold).

**Phase 1B = abgeschlossen.** Zwei Enhancements bewusst nach hinten (mit Export/Persistenz):
- FK-Parser Source-Cell-Tracking (für Export-Quellenrefs)
- Summary-Metric-Parser (Materialkosten/Herstellkosten-Totals → Summary-Diff + FK-Sum-Plausi B12)

### Nächste Phase 1C — Datenmodell + RLS
- 14 Qaf*-Tabellen als `supabase/migrations/supabase-migration-qaf-differences-*.sql` (+ rollback), flache Konvention, BEGIN/COMMIT, idempotent, MIGRATIONS.md-Katalog.
- Ownership-RLS `_own` + `_admin` (project_id→projects.user_id, `current_user_role()`), `qaf_process_mappings`-RLS-Schwäche mitfixen.
- RLS-Iso-Test `__tests__/security/rls-qaf-differences-isolation.test.ts` (raw pg.Client, USER_A/B, 4 Assertions, skipIf(!DB_URL)).
- ⚠ Kais spielt SQL im SQL-Editor ein (operator-applied, B15.1).

### Update 25.06. ~22:46 — Phase 1C Datenmodell + RLS verifiziert
- Commit e13e42d: `supabase-migration-qaf-differences.sql` — 14 Tabellen + `_own`/`_admin`-RLS per DO-Loop, paired rollback, MIGRATIONS.md #101/R29.
  - **Gegen Postgres 17 validiert** (Wegwerf-Container): 14 Tabellen, 2 Policies/Tabelle, idempotent, Rollback sauber.
- Commit e285694: RLS-Iso-Test `rls-qaf-differences-isolation.test.ts` + run.sh/setup.sql-Wiring.
  - **Full Harness grün: 3 Files, 17 Tests** auf echtem PG17 inkl. komplettem Prod-Schema. user_b kann user_a-qaf_comparison nicht lesen/ändern/löschen, Foreign-INSERT von RLS abgelehnt.
- ⚠ **Kais muss `supabase-migration-qaf-differences.sql` im Supabase-SQL-Editor einspielen** (Staging zuerst, BEGIN…ROLLBACK inspizieren) bevor Staging-Verify möglich ist. Service-Key kann kein DDL.

**Commits gesamt (feature/qaf-differences):** scaffold, 2c80bb0, 226f77e, 58dfb2f, 43601b6, e13e42d, e285694.

### Update 25.06. ~23:00 — 1D angefangen: Workbook-Adapter
- Commit e52f750: `workbook-adapter.ts` — `worksheetToGrid` (ExcelJS→2D, Formel/.result/Hyperlink) + `parseSummaryFromWorkbook(buffer)`. 4 Tests via in-memory ExcelJS-Workbook. 76 Modul-Tests, tsc + Gates clean.
- Migration-SQL + Rollback an Kais per Telegram geschickt (msg 7465-7467); wartet auf Apply im SQL-Editor.
- **Commits gesamt:** scaffold, 2c80bb0, 226f77e, 58dfb2f, 43601b6, e13e42d, e285694, e52f750.

### Update 25.06. ~23:12 — Migration LIVE + verifiziert
Kais hat `supabase-migration-qaf-differences.sql` im SQL-Editor eingespielt („Success. No rows returned"). Aria read-only gegen die echte Kadi-v2-DB (`db.nghepoidagwamsesrcdl.supabase.co`, URL in `/root/.kadi-v2-prod-db-url`) gegengeprüft:
- **14 neue qaf_*-Tabellen live, RLS aktiv, je 2 Policies (_own/_admin).** ✓
- Drift-Fund: Live-DB hat zusätzlich `qaf_summary` + `qaf_process_mapping` (singular), NICHT im Repo-Schema. Kollidiert nicht (ich nutze qaf_summary_metric/_diff). Bestätigt Memory `project_kadi_v2_migrations_catalog_stale` erneut.
- Datenmodell steht in der DB → Persistenz-Code kann jetzt schreiben.

### Update 25.06. ~23:37 — Phase 1D Backend KOMPLETT
Commits seit Migration-Live: 9504b45 (persistence-mapper), 4475578 (parseQafFile), 6fa47b8 (batch), 0a6461c (server action `analyzeQafBatch`).
- Ganze Backend-Kette steht: Upload → parseQafFile → buildBatchComparisons (Gruppierung nach Sachnummer) → compareQafPair → buildComparisonRowset → DB-Insert via RLS-scoped server client (qaf_file/steps/part/comparison/step_match/diff/structure/plausi/root_cause/audit), per-File-Error-Isolation, file_hash-Dedup.
- **87 Unit-Tests grün, tsc + eslint + check:portability(strict) clean.**
- Server-Action `tdd-guard:skip` (DB-Glue; komponierte Logik ist unit-getestet, Validierung via RLS-Harness + Staging-E2E).
- **Raw-File-Storage als KAR-800 ausgelagert** (Bucket-Provisioning + Storage-RLS = eigener operator-Schritt). V1 persistiert file_hash + parsed data.
- **Commits gesamt:** scaffold, 2c80bb0, 226f77e, 58dfb2f, 43601b6, e13e42d, e285694, e52f750, 9504b45, 4475578, 6fa47b8, 0a6461c. (12)

### Update 26.06. ~00:00 — Phase 1E UI-Spine steht (Commit ba4f6ce)
- Nav-Eintrag „QAF-Vergleiche" (GitCompareArrows) in app-shell BASE_ITEMS + i18n de/en/es/zh.
- `app/qaf-differences/page.tsx` (auth-guard, lädt projects + recent comparisons).
- `qaf-differences-client.tsx`: Projekt-Select + Multi-File-Upload → `analyzeQafBatch` → Ergebnis-Summary + Liste.
- Semantic Tokens only (check:hardcoded-colors clean). `next build` kompiliert sauber (nur env-var-Validation failt lokal, nicht der Code).
- **Vertikaler Slice end-to-end funktional:** Upload → Analyse → Persistenz → Anzeige. 13 Commits gesamt.

### Update 26.06. ~23:50 — 1F Export-Builder (Commit 8c8b796)
- `buildQafExportWorkbook`: 8 Referenz-Blätter (README/Import_Log/Zusammenfassung_Vergleich/Fertigungskosten_Vergleich/Neu_Entfallen/Delta_Highlights/Top_Treiber_Prozess/Plausibilitätscheck), frozen header + autofilter + Zahl-/Prozent-Format + Brand-CI-Status-Fills (ARGB). 4 Tests (Workbook-Round-Trip). 91 Tests gesamt.
- ⚠ Selbstkorrektur: erst committet, dann Gate-Output gelesen → tsc(2)+forbidden(BMW im Kommentar) → sofort gefixt + amended. Lehre: Gates VOR commit lesen (verstößt gegen feedback_read_exit_code_before_claiming_green).
- **Commits gesamt: 14.**

### Offen für merge-fähigen PR (Rest 1E/1F + 1G)
- Export-Download-Route `app/api/qaf-differences/export/route.ts` (DB qaf_* → QafExportInput-Adapter → buildQafExportWorkbook → Buffer-Response). Adapter DB→QafComparisonResult/Input fehlt noch.
- Reiche Detail-UI: Fertigungskosten-Diff-Tabelle, **Matching-Review** (Pflicht, D5), Neu/Entfallen, Plausi-Liste, Root-Cause-Fazit, Drilldown, Farben. (Akzeptanzkriterien D5.)
- 1G: E2E, /review Security, Perf ≥100 QAFs, check:portability(strict)+next build+vitest, Staging-Deploy, PR mit C6-Beschreibung, „Bereit zum Prod-Merge".

### Phase 1E Rest + 1F/1G offen
- Reiche Vergleichs-Detailansicht: Fertigungskosten-Diff-Tabelle, **Matching-Review** (Pflicht, unsichere Matches bestätigen), Neu/Entfallen, Plausi-Liste, Root-Cause-Fazit, Drilldown, Farben (rot Anstieg/grün Senkung/blau neu/grau entfallen/gelb Plausi). Reuse qaf-comparison-board als Basis.
- **1F Export:** 8-Blatt-ExcelJS server-side (`app/api/qaf-differences/export/route.ts`), reuse `lib/excel/template-helpers.ts`. Testbar.
- **1G:** E2E, Security-Review (/review), Perf (≥100 QAFs), CHECK_FORBIDDEN_LEVEL=error check:portability + next build + vitest, Staging-Deploy, PR.

### Phase 1E — UI (Plan)
- Nav-Eintrag in `components/layout/app-shell.tsx` BASE_ITEMS + i18n (4 Locales `lib/i18n/translations/`).
- Seite `/qaf-differences` (server-guard `getUserSession`/`createClient` → client component).
- Bereiche: Upload, Batch-Übersicht, Import-Log, Baseline, Vergleich (Summary+Fertigung), **Matching-Review** (Pflicht), Neu/Entfallen, Plausi, Root-Cause, Maßnahmen, Export.
- Reuse: `components/qaf/qaf-comparison-board.tsx` als Basis; BMW-CI-Tokens (Petrol #037493, 2px radius), design-lint beachten.

### Phase 1D offen (Rest → KAR-800)
- Persistenz-Write-Layer: compareQafPair-Output → qaf_*-Inserts (server action, user-scoped).
- Upload xlsx/zip, Hash-Dedup, Makro-Schutz, per-File-Error-Isolation, Batch ≥100.
- FK-Step-Parsing aus Buffer (qaf-parser nimmt File; Buffer-Variante nötig) + Source-Cell-Tracking.
- API `app/api/qaf-differences/route.ts` (Platzhalter ersetzen), Storage wie documents-Bucket.

### Original-Plan Phase 1D — Upload/Batch/API + Persistenz
- ExcelJS→grid Adapter (Worksheet→2D, .result auflösen) für FK- + Summary-Parser. ✅ (Summary)
- Persistenz-Layer: Engine-Output (compareQafPair) → qaf_*-Insert (service-role oder user-scoped server action).
- Upload xlsx/zip, validieren, Hash-Dedup, Makro-Schutz, per-File-Error-Isolation, Batch ≥100.
- Server-Action/API `app/api/qaf-differences/route.ts` (Platzhalter ersetzen).
- Storage-Pattern wie `documents`-Bucket (signed URL, storage_key).

### Sample-QAFs (lokal, nicht im Repo)
`/tmp/claude-0/.../scratchpad/qaf-samples/qaf1..7.xlsx` (Session-scratch; bei Bedarf neu aus Telegram-Inbox `/root/.claude/channels/telegram/inbox/17824068*.xlsx`).

## Entscheidungs-Log
- D1: Engine als eigenes `lib/qaf-differences/` Modul (Barrel-Boundary), UI-unabhängig. — 25.06.
- D2: Relationale Normalisierung der QAF-Zeilen (nicht JSONB-Blob weiterführen). — 25.06.
- D3: „Tenant Isolation" = ownership-RLS (project_id→user_id), kein echtes Multi-Tenant (single-tenant-konform, ADR sonst nötig). — 25.06.
- D4: Migration in bestehender flacher Konvention + paired rollback, operator-applied. — 25.06.