chore(docs): füge ADRs 0025–0027 und Wizard-DSL-Referenz hinzu, aktualisiere Roadmap und ADR-Index

Signed-off-by: StefanMoCoAt <stefan.mo.co@gmail.com>
2026-04-21 16:21:19 +02:00 · 2026-04-21 16:21:19 +02:00 · ec124e9acd
commit ec124e9acd
parent 0ab1807235
7 changed files with 281 additions and 1 deletions
--- a/docs/01_Architecture/MASTER_ROADMAP.md
+++ b/docs/01_Architecture/MASTER_ROADMAP.md
@ -2,7 +2,7 @@
 type: Roadmap
 status: ACTIVE
 owner: Lead Architect
-last_update: 2026-04-20
+last_update: 2026-04-21
 ---

 # MASTER ROADMAP: Meldestelle
@ -175,6 +175,58 @@ und über definierte Schnittstellen kommunizieren.

 ---

+## 3. Initiative: Wizard-Orchestrator & Offline-Drafts (Q2/Q3 2026)
+
+🏗️ Verantwortlich: Lead Architect · 🎨 Frontend · 🖌️ UI/UX · 👷 Backend · 🧐 QA · 🧹 Curator
+
+Ziel: Konsolidierung aller „Wizards“ auf ein deklaratives Orchestrierungs-Framework (Graph + Guards + Effects), vereinheitlichte Validierung und Offline-Draft-Fähigkeit inkl. Delta‑Sync. Desktop-first, tastaturbedienbar, testbar.
+
+### 3.1 Kernbausteine
+- Orchestrator Runtime & DSL: `StepId`, `WizardContext`, `WizardState`, `Guard`, `Transition`, `StepEffects`.
+- WizardScaffold: Breadcrumb, Kontext-Chips, Footer mit Hotkeys (Enter/Shift+Enter/Alt+S), Fehler-Summary.
+- DraftStore: Autosave pro Step (`onLeave`), Resume, `flowVersion`, Konfliktanzeige.
+- DevTools: strukturierte Transition-Logs, Graph-Export (DOT/PlantUML).
+
+Referenzen/Dokumente:
+- ADR‑0025: Wizard-Orchestrator (State‑Machine, DSL, Guards, Effects) → `docs/01_Architecture/adr/0025-wizard-orchestrator-de.md`
+- ADR‑0026: Step-Validation-Policy (sync vs. async, Fehlersichtbarkeit, Hotkeys) → `docs/01_Architecture/adr/0026-validation-policy-de.md`
+- ADR‑0027: Draft-Domain & Delta‑Sync (Versionierung, Konfliktlösung, Idempotenz) → `docs/01_Architecture/adr/0027-draft-domain-and-delta-sync-de.md`
+- Reference: Wizard‑DSL README (Beispiel-Flow Event) → `docs/01_Architecture/Reference/Wizard-DSL-README.md`
+
+### 3.2 Migrationsstrategie (Strangler)
+1) Parallelbetrieb: Neuer Orchestrator in `frontend/core/wizard`; bestehende VMs delegieren schrittweise.
+2) Inkrement 1: Event‑Flow – zunächst 2 Steps (ZNS_CHECK, VERANSTALTER_SELECTION), dann alle 6 Steps.
+3) Feature‑Flag `WizardRuntimeEnabled` für risikoarmen Rollout.
+
+### 3.3 Phasenplanung (Auszug)
+- Phase 1 (Core & Tooling, 2–3 Wochen): Runtime/DSL, DevLogs, Graph‑Export, Scaffold‑MVP, Unit‑Tests.
+- Phase 2 (Event‑Flow, 2–3 Wochen): `EventStep/Acc/Guards`, Flow‑DSL, VM‑Delegation, Validierung, Autosave/Resume.
+- Phase 3 (Backend, 2–4 Wochen): Draft-/Validate‑APIs, Offline‑Queue, Delta‑Sync für Turniere.
+- Phase 4 (Skalierung, 6–10 Wochen, parallel): Weitere Flows je Bounded Context.
+- Phase 5–7 (2–3 + 1–2 + 1–2 Wochen): UX‑Härtung, Observability/Rollout‑Gates, Stabilisierung & Abschaltung Altlogik.
+
+Grobe Gesamtdauer: 17–29 Wochen je nach Parallelisierung.
+
+### 3.4 Akzeptanzkriterien (DoD Initiative)
+- Alle priorisierten Flows laufen über Orchestrator; Next/Back/History deterministisch; Graph‑Export aktuell.
+- DraftStore produktiv; Resume deterministisch; Delta‑Sync idempotent; Konflikte nicht‑blockierend sichtbar.
+- Validierungs‑Policy konsistent; Tastatur‑Bedienung vollständig; Performance‑Gates eingehalten.
+- ADR‑0025/0026/0027 veröffentlicht; Wizard‑DSL‑Reference vorhanden; CI grün; Metriken/Alerts aktiv.
+
+### 3.5 10‑Tage‑Startplan
+- Tag 1–2: Runtime/DSL‑Skelett, Scaffold‑MVP, Feature‑Flag, README Skeleton.
+- Tag 3: EventStep/Acc/Guards, EventFlow (2 Steps), VM‑Delegation minimal.
+- Tag 4: Tests Runtime/Guards, Graph‑Export, Dev‑Logs.
+- Tag 5–6: META_DATA/ANSPRECHPERSON migrieren, Validierungs‑API, Fehler‑Summary.
+- Tag 7: DraftStore lokal (Autosave/Resume), Property‑Test Resume.
+- Tag 8: TURNIER_ANLAGE einbetten, Sync via `onComplete`.
+- Tag 9: SUMMARY + Finalisierung, Offload in Offline‑Queue (Stub).
+- Tag 10: ADR‑0025/0026/0027 Review+Merge; Journal‑Eintrag.
+
+Journal: `docs/99_Journal/2026-04-21_Wizard-Orchestrator_Roadmap_Anchoring.md`
+
+---
+
 ## 3. Aktuelle Phase

 ### PHASE 5: P2-Contexts & Integration ✅ ABGESCHLOSSEN
--- a/docs/01_Architecture/Reference/Wizard-DSL-README.md
+++ b/docs/01_Architecture/Reference/Wizard-DSL-README.md
@ -0,0 +1,107 @@
+---
+type: Reference
+status: ACTIVE
+owner: Lead Architect
+date: 2026-04-21
+---
+
+# Wizard‑DSL & Orchestrator – Referenz
+
+## Ziel
+Deklarative Beschreibung von Wizard‑Flows als Graph (Steps, Guards, Transitions) mit klaren Side‑Effects und Offline‑Draft‑Unterstützung.
+
+## Kern‑Interfaces (Skizze)
+```kotlin
+interface StepId
+
+data class WizardContext(
+  val origin: AppScreen,
+  val role: String?,
+  val isOnline: Boolean,
+  val stats: MasterdataStats?
+)
+
+data class WizardState<S: StepId, A>(
+  val current: S,
+  val history: List<S> = emptyList(),
+  val acc: A,
+  val errors: List<String> = emptyList()
+)
+
+typealias Guard<S, A> = (WizardContext, A) -> Boolean
+
+data class Transition<S: StepId>(val target: S, val guard: Guard<S, *>? = null, val id: String)
+
+interface StepEffects<S: StepId, A> {
+  suspend fun onEnter(ctx: WizardContext, state: WizardState<S, A>) {}
+  suspend fun onLeave(ctx: WizardContext, state: WizardState<S, A>) {}
+  suspend fun onComplete(ctx: WizardContext, state: WizardState<S, A>) {}
+}
+```
+
+## DSL (Skizze)
+```kotlin
+class FlowBuilder<S: StepId, A> {
+  fun step(id: S, block: StepBuilder<S, A>.() -> Unit) { /* … */ }
+}
+class StepBuilder<S: StepId, A> {
+  fun onEnter(block: suspend (WizardContext, WizardState<S, A>) -> Unit) { /* … */ }
+  fun whenGuard(id: String, g: Guard<S, A>, go: S) { /* … */ }
+  fun otherwise(go: S) { /* … */ }
+}
+fun <S: StepId, A> flow(start: S, build: FlowBuilder<S, A>.() -> Unit): WizardRuntime<S, A> { /* … */ }
+```
+
+## Beispiel – Event‑Flow (Auszug)
+```kotlin
+sealed interface EventStep: StepId {
+  data object ZnsCheck: EventStep
+  data object VeranstalterSelection: EventStep
+  data object AnsprechpersonMapping: EventStep
+  data object MetaData: EventStep
+  data object TurnierAnlage: EventStep
+  data object Summary: EventStep
+}
+
+data class EventAcc(
+  val veranstalterId: Uuid? = null,
+  val veranstalterNr: String = "",
+  val veranstalterName: String = "",
+  val ansprechpersonSatznr: String = "",
+  val name: String = "",
+  val ort: String = "",
+  val start: LocalDate? = null,
+  val end: LocalDate? = null,
+  val turniere: List<TurnierEntry> = emptyList()
+)
+
+object EventGuards {
+  val hasZns: Guard<EventStep, EventAcc> = { ctx, _ -> (ctx.stats?.vereinCount ?: 0) > 0 }
+  val needsContactPerson: Guard<EventStep, EventAcc> = { _, acc -> acc.veranstalterId == null || acc.veranstalterNr.startsWith("ORG-") }
+}
+
+val EventFlow = flow<EventStep, EventAcc>(start = EventStep.ZnsCheck) {
+  step(EventStep.ZnsCheck) {
+    onEnter { ctx, _ -> /* prefetch stats */ }
+    whenGuard("hasZns", EventGuards.hasZns, go = EventStep.VeranstalterSelection)
+    otherwise(go = EventStep.VeranstalterSelection)
+  }
+  step(EventStep.VeranstalterSelection) {
+    whenGuard("needsContact", EventGuards.needsContactPerson, go = EventStep.AnsprechpersonMapping)
+    otherwise(go = EventStep.MetaData)
+  }
+}
+```
+
+## DevTools
+- Strukturierte Logs je Transition (from, to, guard-id, result, duration).
+- Graph‑Export (DOT/PlantUML) aus der DSL für Doku & Reviews.
+
+## Tests (Empfehlungen)
+- Unit: Guards (100% Branch‑Abdeckung), Runtime‑History.
+- Property: Resume‑Determinismus (Draft → korrekter Step).
+- Snapshot: Compose‑Panels mit Beispielkontexten.
+
+## Verweise
+- ADR‑0025 Orchestrator · ADR‑0026 Validation‑Policy · ADR‑0027 Draft‑Domain & Delta‑Sync
+- Roadmap: `docs/01_Architecture/MASTER_ROADMAP.md#3-initiative-wizard-orchestrator--offline-drafts-q2q3-2026`
--- a/docs/01_Architecture/adr/0025-wizard-orchestrator-de.md
+++ b/docs/01_Architecture/adr/0025-wizard-orchestrator-de.md
@ -0,0 +1,30 @@
+---
+type: ADR
+status: PROPOSED
+owner: Lead Architect
+date: 2026-04-21
+---
+
+# ADR-0025 — Wizard-Orchestrator (State-Machine, DSL, Guards, Effects)
+
+## Kontext
+- Aktuelle Wizard-Implementierungen sind linear (`next/previous`) und hart verdrahtet in ViewModels.
+- Anforderungen: Kontextabhängige Pfade, Offline‑First (Autosave/Resume), testbare Regeln, einheitliche UX.
+
+## Entscheidung
+- Einführung eines generischen Orchestrators mit deklarativem Flow:
+  - `StepId` (typsicher je Flow), `WizardContext`, `WizardState`, `Guard`, `Transition`, `StepEffects`.
+  - Kotlin‑DSL: `flow { step { whenGuard(id) go target; otherwise go … } }`.
+  - Side‑Effects an Hooks (`onEnter/onLeave/onComplete`) für Prefetch, Autosave, Finalisierung.
+
+## Konsequenzen
+- Vorteile: zentrale, testbare Navigationslogik; konsistente Draft‑Policy; bessere Übersicht/Erweiterbarkeit.
+- Risiken: Initialer Overhead, Lernkurve, Guard‑Sprawl; mitigiert durch README, DevTools, Linting/Namenskonventionen.
+
+## Umsetzung
+- Modul `frontend/core/wizard` (runtime, dsl, devtools, draft) und `WizardScaffold` (Breadcrumb, Footer, Hotkeys).
+- Strangler‑Migration beginnend mit Event‑Flow; Feature‑Flag `WizardRuntimeEnabled`.
+
+## Verweise
+- Roadmap‑Abschnitt: `docs/01_Architecture/MASTER_ROADMAP.md#3-initiative-wizard-orchestrator--offline-drafts-q2q3-2026`
+- Reference: `docs/01_Architecture/Reference/Wizard-DSL-README.md`
--- a/docs/01_Architecture/adr/0026-validation-policy-de.md
+++ b/docs/01_Architecture/adr/0026-validation-policy-de.md
@ -0,0 +1,28 @@
+---
+type: ADR
+status: PROPOSED
+owner: Lead Architect
+date: 2026-04-21
+---
+
+# ADR-0026 — Step-Validation-Policy (Sync vs. Async, Fehlersichtbarkeit, Hotkeys)
+
+## Kontext
+- Validierungen sind heute uneinheitlich verteilt (UI/Backend) und nicht klar priorisiert (blockierend vs. Hinweis).
+
+## Entscheidung
+- Sync-Validierung pro Step als pure Funktion (schnell, offline, blockierend für „Weiter“).
+- Async-Validierungen (Server/DB) als nicht-blockierende Hinweise mit Retry; Ergebnisse im Footer aggregiert.
+- Einheitliche Hotkeys: Enter=Weiter, Shift+Enter=Zurück, Alt+S=Speichern (Draft), Alt+J=Step-Sprung.
+
+## Konsequenzen
+- Konsistente Nutzererwartung, klare Trennung von Fehlerklassen, bessere Testbarkeit.
+- Erfordert Footer-Fehlersummary und Dev-Overlay (Guard/Validation-Trace).
+
+## Umsetzung
+- API `validate(accumulator): ValidationResult` je Step.
+- Async-Pipeline mit Debounce (250ms) und Status-Pills; keine UI-Blocker bei Netzwerkfehlern.
+
+## Verweise
+- Roadmap‑Abschnitt: `docs/01_Architecture/MASTER_ROADMAP.md#3-initiative-wizard-orchestrator--offline-drafts-q2q3-2026`
+- Reference: `docs/01_Architecture/Reference/Wizard-DSL-README.md`
--- a/docs/01_Architecture/adr/0027-draft-domain-and-delta-sync-de.md
+++ b/docs/01_Architecture/adr/0027-draft-domain-and-delta-sync-de.md
@ -0,0 +1,31 @@
+---
+type: ADR
+status: PROPOSED
+owner: Lead Architect
+date: 2026-04-21
+---
+
+# ADR-0027 — Draft-Domain & Delta‑Sync (Versionierung, Konfliktlösung, Idempotenz)
+
+## Kontext
+- Offline‑First verlangt lokale Drafts, Resume‑Fähigkeit und robuste Synchronisation bei instabiler Konnektivität.
+- Heute: kein einheitliches Draft‑Modell, keine standardisierte Schritt‑weise Speicherung.
+
+## Entscheidung
+- Einführung einer Draft‑Domain mit Version/ETag und Schritt‑Patchs:
+  - `POST /api/events/drafts` (idempotent über Idempotency‑Key) erstellt/vereinigt Drafts.
+  - `PATCH /api/events/drafts/{id}` speichert step‑weise Deltas (nur geänderte Felder seit `version`).
+  - `POST /api/events` finalisiert (Server‑Validierung, Erstellung `veranstaltungId`).
+- Client Offline‑Queue mit Retry/Backoff; Konflikte als nicht‑blockierende Hinweise.
+
+## Konsequenzen
+- Reproduzierbare, idempotente Speicherung; geringere Payloads; klare Konfliktauflösung.
+- Erfordert Versionierung im DraftStore und Migrationspfade bei Flow‑Änderungen (`flowVersion`).
+
+## Umsetzung
+- Frontend: DraftStore (Autosave `onLeave`), Delta‑Builder je Step, Queue mit Idempotency‑Key.
+- Backend: Versionsverwaltung, If‑Match/ETag Unterstützung, Conflict‑Detect (409) mit Merge‑Hinweisen.
+
+## Verweise
+- Roadmap‑Abschnitt: `docs/01_Architecture/MASTER_ROADMAP.md#3-initiative-wizard-orchestrator--offline-drafts-q2q3-2026`
+- Contracts: folgen nach API‑Skizzierung (`contracts/` Verzeichnis)
--- a/docs/01_Architecture/adr/README.md
+++ b/docs/01_Architecture/adr/README.md
@ -19,4 +19,8 @@ Namensschema: ADR-XXX-title.md mit fortlaufender Nummerierung.
 - ADR-0016 API-Design & Anti-Corruption Layer (ACL)
 - ADR-0020 Lokale Netzwerk-Kommunikation und Daten-Isolierung

+- ADR-0025 Wizard-Orchestrator (State-Machine, DSL, Guards, Effects)
+- ADR-0026 Step-Validation-Policy (Sync vs. Async, Fehlersichtbarkeit, Hotkeys)
+- ADR-0027 Draft-Domain & Delta‑Sync (Versionierung, Konfliktlösung, Idempotenz)
+
 Siehe Template: ADR-000-template.md.
--- a/docs/99_Journal/2026-04-21_Wizard-Orchestrator_Roadmap_Anchoring.md
+++ b/docs/99_Journal/2026-04-21_Wizard-Orchestrator_Roadmap_Anchoring.md
@ -0,0 +1,28 @@
+---
+type: Journal
+status: DONE
+owner: Curator
+date: 2026-04-21
+---
+
+# Journal — Roadmap „Wizard‑Orchestrator & Offline‑Drafts“ verankert
+
+## Kontext
+Die in der Session ausgearbeitete Roadmap zur Migration auf einen Wizard‑Orchestrator wurde in `docs/` verankert.
+
+## Artefakte
+- MASTER_ROADMAP aktualisiert (Initiative Abschnitt):
+  - `docs/01_Architecture/MASTER_ROADMAP.md#3-initiative-wizard-orchestrator--offline-drafts-q2q3-2026`
+- Neue ADRs (Status: PROPOSED):
+  - ADR‑0025 Wizard‑Orchestrator → `docs/01_Architecture/adr/0025-wizard-orchestrator-de.md`
+  - ADR‑0026 Step‑Validation‑Policy → `docs/01_Architecture/adr/0026-validation-policy-de.md`
+  - ADR‑0027 Draft‑Domain & Delta‑Sync → `docs/01_Architecture/adr/0027-draft-domain-and-delta-sync-de.md`
+- Referenz:
+  - Wizard‑DSL README → `docs/01_Architecture/Reference/Wizard-DSL-README.md`
+- ADR‑Index ergänzt:
+  - `docs/01_Architecture/adr/README.md`
+
+## Nächste Schritte (Review)
+- Lead Architect: ADR‑0025/26/27 Review & Nummernfreigabe.
+- Frontend: Spike „Runtime/DSL‑Skelett“ gemäß Roadmap (Tag 1–2).
+- Backend: API‑Skizzen für Drafts/Validate in `contracts/` vorbereiten.