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
parent 0ab1807235
commit ec124e9acd
7 changed files with 281 additions and 1 deletions
@@ -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`
@@ -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`
@@ -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)
@@ -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.