From 1f20faf650e4513d236d7e73717725520a8513f3 Mon Sep 17 00:00:00 2001 From: Madhura68 Date: Thu, 14 May 2026 22:23:09 +0200 Subject: [PATCH] =?UTF-8?q?docs(T-1017):=20PB-workflow=20doc=20=E2=80=94?= =?UTF-8?q?=20gap-analyse,=20aanbevelingen=20en=20docs-wiring?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Slotlaag van het Product Backlog page workflow-doc (PBI-88 / ST-1363): gap-analyse (G1-G6, incl. de oorspronkelijke switcher-FOUT), niet-bindende aanbevelingen, en verwante-docs sectie. Haakt het doc in via de architecture.md breadcrumb en een cross-link vanuit functional.md F-04. npm run docs groen: INDEX geregenereerd, alle doc-links valide. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/architecture.md | 1 + docs/architecture/product-backlog-workflow.md | 30 +++++++++++++++++++ docs/specs/functional.md | 2 ++ 3 files changed, 33 insertions(+) diff --git a/docs/architecture.md b/docs/architecture.md index b64e501..5387082 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -19,3 +19,4 @@ last_updated: 2026-05-03 | Claude ↔ User vraag-kanaal | [architecture/claude-question-channel.md](./architecture/claude-question-channel.md) | | Projectstructuur, Stores, Realtime, Job queue | [architecture/project-structure.md](./architecture/project-structure.md) | | Sprint execution modes (PER_TASK vs SPRINT_BATCH) | [architecture/sprint-execution-modes.md](./architecture/sprint-execution-modes.md) | +| Product Backlog page — workflow & states | [architecture/product-backlog-workflow.md](./architecture/product-backlog-workflow.md) | diff --git a/docs/architecture/product-backlog-workflow.md b/docs/architecture/product-backlog-workflow.md index 6fc0470..8c28784 100644 --- a/docs/architecture/product-backlog-workflow.md +++ b/docs/architecture/product-backlog-workflow.md @@ -252,3 +252,33 @@ Ontwerp-uitgangspunten: - **Eén plek voor "in welke state zit ik".** Vandaag zit die afleiding verspreid over `page.tsx`, `sprint-switcher.tsx`, `new-sprint-trigger.tsx` en `save-sprint-button.tsx`; componenten schakelen straks over op één `switch (screenState.kind)`. - **Leeft als selector/util** naast `stores/product-workspace/selectors.ts` — testbaar in isolatie (pure input → output). - `PRODUCT_NOT_ACTIVE` en `DEMO_MODE` blijven **buiten** `ScreenState`: het zijn gates die de UI al apart als booleans heeft, geen knopen in de machine. + +## Gap-analyse + +Wat verschilt tussen de as-is werkelijkheid en het doelbeeld: + +| # | Gap | Huidige situatie | Doelbeeld / divergentie | +|---|---|---|---| +| G1 | Geen expliciete schermstaat | De state wordt per render ad-hoc afgeleid; die logica zit verspreid over `page.tsx`, `sprint-switcher.tsx`, `new-sprint-trigger.tsx` en `save-sprint-button.tsx` | Eén `deriveScreenState()` als single source of truth | +| G2 | Geen `READY_TO_START` | `createSprintWithSelectionAction` maakt de sprint én activeert 'm in één stap | Voorstel-state vervalt bewust — vastleggen, niet "fixen" | +| G3 | `ERROR` niet gemodelleerd | Server-action-fout → `toast.error`, scherm blijft in de huidige state | Geen expliciete ERROR-state; afweging of dat wenselijk is bij falende commit / SSE-verlies | +| G4 | `DEMO_MODE` / `PRODUCT_NOT_ACTIVE` zijn geen states | Cross-cutting booleans, los van de state-afleiding | Bewust buiten `ScreenState` — gates, geen knopen | +| G5 | Draft onzichtbaar op de switcher-trigger | De `SprintSwitcher`-knop toont alleen `activeSprint.code` of "Selecteer sprint"; de "⚙ Concept"-regel zit alleen in de (disabled) dropdown | In `DRAFT` zou de trigger de concept-status moeten tonen — dit was de **oorspronkelijke "FOUT"-melding** die tot dit doc leidde | +| G6 | Draft te starten op niet-actief product | `NewSprintTrigger` is alleen demo-gated, niet `isActiveProduct`-gated | Een draft op een niet-actief product is verwarrend; overweeg de trigger ook achter `isActiveProduct` te zetten | + +## Aanbevelingen + +Geprioriteerd en **niet-bindend** — input voor latere PBI's, geen scope van dit doc: + +1. **`deriveScreenState()` introduceren** (G1) — grootste hefboom: maakt de UI testbaar en de overige gaps adresseerbaar vanuit één plek. +2. **Draft-indicatie op de switcher-trigger** (G5) — kleine, zichtbare UX-fix die de oorspronkelijke melding direct oplost. +3. **`NewSprintTrigger` achter `isActiveProduct`** (G6) — kleine guard-toevoeging. +4. **`ERROR`-state overwegen** (G3) — grotere afweging; alleen oppakken als falende commits of SSE-verlies een echt UX-probleem blijken. + +## Verwante docs + +- [functional.md](../specs/functional.md) — F-04..F-06: layout van de 3-pane Product Backlog page +- [workspace-store.md](../patterns/workspace-store.md) — het bounded-context store-patroon (PBI-74) +- [realtime-notify-payload.md](../patterns/realtime-notify-payload.md) — payload-contract van de NOTIFY-triggers +- [sprint-execution-modes.md](./sprint-execution-modes.md) — de sprint-flow ná dit scherm +- [project-structure.md](./project-structure.md) — stores, realtime en projectopbouw in het groot diff --git a/docs/specs/functional.md b/docs/specs/functional.md index 436fafe..7def620 100644 --- a/docs/specs/functional.md +++ b/docs/specs/functional.md @@ -210,6 +210,8 @@ Gebruikers kunnen producten aanmaken, bewerken en archiveren. Een product is het **Omschrijving:** De Product Backlog wordt weergegeven als een 3-paneels gesplitst scherm: PBI's (links) | Stories (midden) | Taken (rechts). De splitters zijn versleepbaar. Selectie cascadeert: klikken op een PBI toont de bijbehorende stories; klikken op een story toont de bijbehorende taken. Elk paneel heeft een eigen navigatiebar met acties. +> **Workflow & states:** dit spec beschrijft de *layout*. Voor het *gedrag* — architectuur-lagen, de impliciete workflow-states, transitions en de to-be state machine — zie [architecture/product-backlog-workflow.md](../architecture/product-backlog-workflow.md). + **Acceptatiecriteria:** - [ ] Standaard splitverhouding is 20/45/35 (PBI's / Stories / Taken) - [ ] Splitters zijn versleepbaar; positie wordt opgeslagen in een cookie (`sp:backlog-{id}`)