From ec124e9acdcd75b1ac90ced6c23a6a40b4bd94e3 Mon Sep 17 00:00:00 2001 From: StefanMoCoAt Date: Tue, 21 Apr 2026 16:21:19 +0200 Subject: [PATCH] =?UTF-8?q?chore(docs):=20f=C3=BCge=20ADRs=200025=E2=80=93?= =?UTF-8?q?0027=20und=20Wizard-DSL-Referenz=20hinzu,=20aktualisiere=20Road?= =?UTF-8?q?map=20und=20ADR-Index?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: StefanMoCoAt --- docs/01_Architecture/MASTER_ROADMAP.md | 54 ++++++++- .../Reference/Wizard-DSL-README.md | 107 ++++++++++++++++++ .../adr/0025-wizard-orchestrator-de.md | 30 +++++ .../adr/0026-validation-policy-de.md | 28 +++++ .../0027-draft-domain-and-delta-sync-de.md | 31 +++++ docs/01_Architecture/adr/README.md | 4 + ...1_Wizard-Orchestrator_Roadmap_Anchoring.md | 28 +++++ 7 files changed, 281 insertions(+), 1 deletion(-) create mode 100644 docs/01_Architecture/Reference/Wizard-DSL-README.md create mode 100644 docs/01_Architecture/adr/0025-wizard-orchestrator-de.md create mode 100644 docs/01_Architecture/adr/0026-validation-policy-de.md create mode 100644 docs/01_Architecture/adr/0027-draft-domain-and-delta-sync-de.md create mode 100644 docs/99_Journal/2026-04-21_Wizard-Orchestrator_Roadmap_Anchoring.md diff --git a/docs/01_Architecture/MASTER_ROADMAP.md b/docs/01_Architecture/MASTER_ROADMAP.md index a448d0b8..49810f66 100644 --- 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 diff --git a/docs/01_Architecture/Reference/Wizard-DSL-README.md b/docs/01_Architecture/Reference/Wizard-DSL-README.md new file mode 100644 index 00000000..114f3f65 --- /dev/null +++ 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( + val current: S, + val history: List = emptyList(), + val acc: A, + val errors: List = emptyList() +) + +typealias Guard = (WizardContext, A) -> Boolean + +data class Transition(val target: S, val guard: Guard? = null, val id: String) + +interface StepEffects { + suspend fun onEnter(ctx: WizardContext, state: WizardState) {} + suspend fun onLeave(ctx: WizardContext, state: WizardState) {} + suspend fun onComplete(ctx: WizardContext, state: WizardState) {} +} +``` + +## DSL (Skizze) +```kotlin +class FlowBuilder { + fun step(id: S, block: StepBuilder.() -> Unit) { /* 
 */ } +} +class StepBuilder { + fun onEnter(block: suspend (WizardContext, WizardState) -> Unit) { /* 
 */ } + fun whenGuard(id: String, g: Guard, go: S) { /* 
 */ } + fun otherwise(go: S) { /* 
 */ } +} +fun flow(start: S, build: FlowBuilder.() -> Unit): WizardRuntime { /* 
 */ } +``` + +## 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 = emptyList() +) + +object EventGuards { + val hasZns: Guard = { ctx, _ -> (ctx.stats?.vereinCount ?: 0) > 0 } + val needsContactPerson: Guard = { _, acc -> acc.veranstalterId == null || acc.veranstalterNr.startsWith("ORG-") } +} + +val EventFlow = flow(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` diff --git a/docs/01_Architecture/adr/0025-wizard-orchestrator-de.md b/docs/01_Architecture/adr/0025-wizard-orchestrator-de.md new file mode 100644 index 00000000..fd74bc09 --- /dev/null +++ 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` diff --git a/docs/01_Architecture/adr/0026-validation-policy-de.md b/docs/01_Architecture/adr/0026-validation-policy-de.md new file mode 100644 index 00000000..c48cadf0 --- /dev/null +++ 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` diff --git 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 new file mode 100644 index 00000000..7fa6f4d9 --- /dev/null +++ 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) diff --git a/docs/01_Architecture/adr/README.md b/docs/01_Architecture/adr/README.md index 51a99878..86901151 100644 --- 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. diff --git a/docs/99_Journal/2026-04-21_Wizard-Orchestrator_Roadmap_Anchoring.md b/docs/99_Journal/2026-04-21_Wizard-Orchestrator_Roadmap_Anchoring.md new file mode 100644 index 00000000..47be0a4f --- /dev/null +++ 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.