# ADR 024: QAF→Value-Stream-Integration (QVS) **Status**: Accepted **Date**: 2026-07-17 **Deciders**: Operator (Kais), QVS-Programm (Epic KAR-968) --- ## Context QAF-Vergleich (`lib/qaf-differences`) und Wertstrom/VSM (`components/wertstrom`, `lib/vsm-types.ts`) sind zwei vollständig getrennte Pipelines ohne jede Verbindung — obwohl jede QAF-Datei mit Fertigungskosten-Sheet strukturell genau die Prozessschritt-Daten enthält, die ein VSM braucht (Prozessname, Zykluszeit, Mitarbeiterzahl, Kosten). Heute tippen Nutzer diese Daten manuell aus dem QAF in den VSM-Editor ab — fehleranfällig, ohne Herkunftsnachweis, ohne Abgleich bei Reimport. Das Programm „QAF to Value Stream Integration" (QVS, Spec 17.07.2026) schließt diese Lücke: ein Klick „Als Wertstrom übernehmen" aus jeder QAF mit verlässlichen Fertigungsdaten — capability-basiert (kein G60-/INPUT-Zwang), additiv zum bestehenden Wertstrom-Modul, mit feldgenauer Source-Lineage. Vollständige Ist-Analyse, Gap-Klassifikation (13 Gaps A/B/C) und die Zielarchitektur mit Modul-Layout, Datenmodell und Phasenplan P0–P7 stehen in `reports/qaf-value-stream-current-state.md`, `reports/qaf-value-stream-gap-analysis.md` und **`reports/qaf-value-stream-architecture.md`** (P0, docs-only, bereits gemerged — #334). Diese ADR hält nur die Leitentscheidungen E1–E7 aus jenem Report als verbindliche Architektur-Entscheidung fest; sie kommt mit dem ersten Code-PR (P1, KAR-970) statt mit dem Doku-PR (P0), weil eine ADR eine Architektur-Entscheidung für Code ist, kein Analyse-Ergebnis. ## Decision Wir übernehmen die sieben Leitentscheidungen E1–E7 aus `reports/qaf-value-stream-architecture.md` §1 (dort mit vollem Wortlaut, hier kompakt): - **E1 — Aus der Haupt-Engine lesen, nicht neu parsen.** Quelle der Prozessschritte ist `qaf_manufacturing_step` (relational, mit `raw_values/normalized/source_cells`) plus `qaf_file.g60_meta.capability_matrix`. Kein neuer Parser, kein Lesen aus dem Legacy-Pfad `qaf_uploads.parsed_data`. - **E2 — Additives VSM-Datenmodell, kein Bruch.** Alle neuen `VsmNode`-Felder sind optional im bestehenden `nodes`-JSONB; bestehende Wertströme bleiben byte-kompatibel gültig. Keine Umstellung auf relationale Node-Tabellen. - **E3 — Ein neues Audit-/Import-Objekt statt Dokument-Versionierung.** `value_stream_imports` (P2-Migration) trägt Quelle, Hash, Versionen, Zählwerte, Warnungen und einen Import-Snapshot — volle VSM-Versionierung bleibt bewusstes Follow-up (Gap G9). - **E4 — Projekt-Scope erzwungen.** Ein aus QAF erzeugter Wertstrom übernimmt zwingend die `project_id` der QAF-Quelle. Kein projektloser Import (RLS-Scope-Verlust für Kosten-Daten). - **E5 — Feature-Flag `qafValueStream`, überall `false` bis zur Korpus-Validierung.** Muster wie der Multi-QAF-Rollout: Phasen mergen flag-off, Flag-ON als eigener Mini-PR nach P6-Evidenz, Rollback = ein Zeilen-Revert. - **E6 — Fabrikations-Verbot operationalisiert.** Nur real extrahierte Werte landen in Nodes; fehlende Werte bleiben `undefined` mit dokumentiertem Grund (`missingFieldReasons`). Nie 0/`null` stopfen, nie synthetische Schritt-Zeiten für Varianten ohne Schritt-Ebene. - **E7 — Diese ADR.** Architektur-Entscheidungen brauchen eine ADR (Repo-Regel) — E1–E6 sind ab KAR-970 (P1) verbindlich für den gesamten QVS-Phasenplan (P1–P7). Zusätzlich, als direkte Konsequenz aus E1/E2 für die Code-Struktur: - **Modul-Layout** `lib/qaf-value-stream/` nach ADR-019 (Golden Path): `mapper.ts` (pur, versioniert über `MAPPING_VERSION`), `manufacturing-capability.ts` (pur, kein DB-Zugriff), `va-classification.ts` (konservativ, nie automatisch `'va'`), `naming.ts`, später `preview.ts`/`duplicates.ts`/`creation.ts`/`sync.ts` (P2+). Server-Wiring als eigene Server Actions (`app/wertstrom/qaf-actions.ts`), nie direkt in den bestehenden 4700-Zeilen `app/qaf-differences/actions.ts`. - **Feld-Vertrag versioniert und maschinenlesbar.** `mappings/qaf-to-value-stream-mapping.yaml` (`version: qvs-1`) ist der verbindliche Vertrag zwischen `QAFRowValues` (22 kanonische `mfg_*`-Felder) und `VsmNode`; `schemas/value-stream-process-source.schema.json` definiert die Node-Lineage-Form (`VsmNodeQafSource`). Drift zwischen YAML und Mapper-Implementierung ist testpflichtig (mapping-drift-Test). ## Rules this decision creates 1. Jede neue QVS-Phase (P2–P7) hält sich an E1–E6, ohne diese ADR erneut zu diskutieren — Änderungen an E1–E6 brauchen eine neue ADR, die diese supersedet (nicht editiert). 2. Kosten-Felder werden nie in Zeit-Felder gemappt (E6-Spezialfall, `setupCostPerUnit` ≠ `setupTimeSec`) — das ist ein harter Test-Gate in jeder Phase, die den Mapper berührt. 3. `qafValueStream` bleibt in allen Profilen `false`, bis ein dedizierter Flag-ON-PR (P7) mit Korpus-Validierungs-Evidenz (P6) das Gegenteil belegt. 4. Neue QVS-Datenbank-Objekte (`value_stream_imports`, P2) bekommen `_own`+`_admin`-RLS ab Tag 1, exakt nach dem etablierten `qaf_*`-Muster. ## Consequences ### Forbidden - Ein neuer QAF-Parser oder ein zweiter Lese-Pfad neben `qaf_manufacturing_step` für den VSM-Import (E1). - Automatische `vaClass: 'va'`-Zuweisung irgendwo im Mapper oder in Folge-Phasen ohne explizite menschliche Bestätigung (bricht mit dem historischen Excel-Import-Fehler, den dieses Programm korrigiert). - Synthetische/geratene Werte für fehlende Felder (Zeit-Split, Kapazität, Varianten-Schritt-Zeiten) — Limitationen werden dokumentiert (`reports/qaf-value-stream-corpus-evidence.md`), nicht kompensiert. - Ein aus QAF erzeugter Wertstrom ohne `project_id` (E4). ### Accepted - Zusätzliche Ceremony pro Phase (Modul-Erweiterung statt Ad-hoc-Code) — bewusster Trade-off für Nachvollziehbarkeit in einem kosten-/compliance-sensiblen Datenpfad. - `value_stream_maps` bekommt über den gesamten Phasenplan keine neue Spalte (Verknüpfung ausschließlich über `value_stream_imports.value_stream_id`, E3) — 1 VSM : N Imports über die Zeit ist die akzeptierte Konsequenz. ## Related - `reports/qaf-value-stream-architecture.md` — vollständiger Wortlaut E1–E7, Modul-Layout, Datenmodell-Details (§3), API/Server-Boundary (§4), Phasenplan P0–P7 (§7). - `reports/qaf-value-stream-field-mapping.md` + `mappings/qaf-to-value-stream-mapping.yaml` (`qvs-1`) — der verbindliche Feld-Vertrag. - `reports/qaf-value-stream-corpus-evidence.md` (P1) — Korpus-Evidenz für die Zeit-/Kapazitäts-Feld-Entscheidungen hinter E6. - `schemas/value-stream-process-source.schema.json` — `VsmNodeQafSource`-Vertrag. - ADR 010 (Product-Core-vs-Customer-Adapter), ADR 013 (Composition Profiles — trägt das `qafValueStream`-Flag), ADR 019 (New Module Golden Path — trägt `lib/qaf-value-stream/`). - KAR-970 (P1 — dieser PR), KAR-968 (QVS-Epic). --- ## Status-Nachtrag (P7, 2026-07-18, PR #341, Review-Fix) Die in Rule 3 genannte Bedingung ist eingetreten: `qafValueStream` ist seit diesem PR `true` in `default`+`bmw` (`_template` bleibt `false`, kein reales Deployment — kein drittes produktives Profil existiert im Repo) — die P6-Korpus-Validierungs-Evidenz (`reports/qaf-value-stream-validation-results.md`) hat den Flag-ON-Schritt getragen. Rule 3 selbst bleibt oben unverändert als historische Aufzeichnung der Vorbedingung stehen (ADR-Konvention: kein Rewrite bestehender Regeln, neue Entscheidungen supersedieren statt editieren) — dieser Nachtrag dokumentiert nur, dass die Bedingung erfüllt und der PR gemerged wurde. Rollback-Runbook: `docs/runbooks/qaf-value-stream-rollout.md` (Zwei-Zeilen-Flag-Revert, kein Schema-Eingriff).