feat(PBI-74): Zustand product-workspace rearchitecture (Stories 1-8) (#180)
* feat(PBI-74): product-workspace store skelet + test-infra (Story 1)
Skelet voor de nieuwe `product-workspace-store` die op termijn de gefragmenteerde
`backlog-store`/`planner-store`/`selection-store`/`product-store` vervangt. Deze
PR levert alleen het skelet + tests; UI-consumers worden in latere stories
omgezet.
- vitest naar jsdom + tests/setup.ts (MemoryStorage, default fetch-stub) — G6/G8
- stores/product-workspace/{types,store,selectors,restore}.ts — immer-middleware,
alle slices en acties (hydrate, setActive*, ensure*Loaded met activeRequestId-
guard, applyRealtimeEvent, resyncActiveScopes/loadedScopes, optimistic
mutations). Restore-wiring in setters volgt in Story 4 (T-857/T-858).
- selectors gebruiken module-level EMPTY refs (G1) en documenteren useShallow-
vereiste (G2)
- 34 nieuwe unit-tests dekken §Testing setup-checklist uit het ontwerp:
hydrateSnapshot, selection-cascade, applyRealtimeEvent (I/U/D + parent-move +
ander-product + unknown-entity → resync), delete-cleanup, race-safe loaders,
ensureTaskLoaded _detail-flag, resyncActiveScopes ensure-keten, restore-hints
read/write/clear, optimistic mutation rollback/settle/SSE-echo idempotent
- docs/api/rest-contract.md: audit-sectie met de vier ontbrekende
ensure*Loaded-endpoints (worden toegevoegd in Story 7 / T-870)
Refs: PBI-74, ST-1318, T-837..T-843
Bron-ontwerp: docs/plans/zustand-store-rearchitecture.md
Implementatieplan: docs/plans/zustand-workspace-store-implementation.md
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(PBI-74): dual-dispatch hydratie + realtime naar workspace-store (Story 2)
Story 2 — schaduw-fase: BacklogHydrationWrapper en useBacklogRealtime voeden
nu ook de nieuwe product-workspace-store, terwijl de oude useBacklogStore /
useProductStore leidend blijft voor componenten. Story 3 verschuift consumers
één voor één; Story 8 ruimt de oude stores op.
- T-844: BacklogHydrationWrapper roept naast useBacklogStore.setInitialData
ook useProductWorkspaceStore.hydrateSnapshot aan. Productname-prop optioneel
toegevoegd voor activeProduct-context.
- T-845: useBacklogRealtime onmessage dispatcht events naar zowel oude store
(applyChange) als nieuwe store (applyRealtimeEvent). Geen wijziging aan
reconnect/visibility — Story 5.
- T-846: dev-only logWorkspaceFingerprint helper vergelijkt counts tussen
oude en nieuwe store na hydrate en na elk realtime-event. console.warn bij
mismatch; opt-in debug log via NEXT_PUBLIC_DEBUG_WORKSPACE_FINGERPRINT=1.
Bestand TODO-marked voor verwijdering in Story 8 (T-878).
- T-847: SetCurrentProduct schrijft naast oude useProductStore ook
useProductWorkspaceStore.setActiveProduct({id, name}); cleanup cleart beide.
setActiveProduct triggert ensureProductLoaded — fetch-stub tot Story 7
(T-870) de LIST-endpoints toevoegt.
Verify: lint+typecheck clean, 636/636 tests groen (geen UI-regressie omdat
oude store leidend blijft).
Refs: PBI-74, ST-1319, T-844..T-847
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(PBI-74): migreer backlog-componenten naar workspace-store (Story 3)
Story 3 verplaatst alle UI-consumers van de oude vier stores
(useBacklogStore/usePlannerStore/useSelectionStore/useProductStore) naar de
nieuwe product-workspace-store. De oude stores blijven nog bestaan voor
hydration-wrapper en realtime-hook (dual-dispatch); Story 8 ruimt ze op.
- T-848 backlog-split-pane.tsx: leest activePbiId/activeStoryId uit
context-slice (primitives, geen useShallow nodig).
- T-849 pbi-list.tsx: selectVisiblePbis(useShallow); DnD via
applyOptimisticMutation('pbi-order' + optionele 'entity-patch' bij
cross-priority drag), met settle/rollback per server-result.
- T-850 story-panel.tsx: selectStoriesForActivePbi(useShallow); DnD via
applyOptimisticMutation('story-order' + entity-patch bij priority change).
- T-851 task-panel.tsx: selectTasksForActiveStory(useShallow); DnD via
applyOptimisticMutation('task-order'); detail-view (ensureTaskLoaded +
isDetail) zit in de task-dialog (apart component, niet in deze lijst).
- T-852 start-sprint-button.tsx: selectActivePbi + selectStoriesForActivePbi
voor free-story count.
- T-853 set-current-product.tsx: alleen workspace-store.setActiveProduct
(oude useProductStore-import verwijderd).
- T-854 G1/G2-audit: alle nieuwe selectors gebruiken module-level EMPTY
refs (G1) en useShallow voor lijsten (G2). Geen 'Maximum update depth'-
warnings tijdens npm test.
- T-855 tests bijgewerkt: backlog-split-pane.test, task-panel.test,
integration.test gebruiken nu setState op workspace-store (helpers
resetWorkspace/setActiveStoryAndTasks/selectPbi/selectStory).
Verify: lint+typecheck clean, 636/636 tests groen. UI-consumers van
oude stores zijn nu nul (uitgezonderd dual-dispatch in hydration-wrapper en
realtime-hook + dev-fingerprint-helper, die in Story 8/T-873/T-878 verdwijnen).
Refs: PBI-74, ST-1320, T-848..T-855
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(PBI-74): race-safe loaders + restore-hints + URL-prioriteit (Story 4)
- T-856: activeRequestId-guard zat al in store.ts uit Story 1; bevestigd door
de race-safety test (in-flight ensurePbiLoaded mag niet overschrijven).
- T-857: restore-hint flow toegevoegd in setActiveProduct/setActivePbi/
setActiveStory. Async chain: await ensureXxxLoaded → guard check →
readHints → valideer hint via entities.byId → setActiveYyy(hint).
Geen setTimeout-trick — chain is alleen await-based.
- T-858: writeProductHint/writePbiHint/writeStoryHint/writeTaskHint
aangeroepen direct na set(...) zodat de hint-persistentie altijd
consistent is met de in-store selectie.
- T-859: nieuwe components/backlog/url-task-sync.tsx — leest
?editTask=<id> uit useSearchParams, schrijft de hint en roept
setActiveTask aan zodat de URL wint boven een eerder gepersisteerde
task-hint. Gemount in beide product-pages (desktop + mobile) binnen
BacklogHydrationWrapper.
- T-860: 6 nieuwe vitest-cases — 4 voor hint-persist per setter, 2 voor de
restore-flow chain (hint die niet in entities zit wordt genegeerd; hint
die wel in entities zit wordt toegepast). Bestaande race-safety test
blijft groen.
Verify: lint+typecheck clean, 642/642 tests groen.
Refs: PBI-74, ST-1321, T-856..T-860
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(PBI-74): hidden-tab + reconnect resync (Story 5)
Per ontwerp samen in één commit zodat geen vangnet wegvalt zonder vervanging.
- T-861: useBacklogRealtime sluit niet meer op visibilitychange hidden;
EventSource blijft open zolang browser/netwerk dit toelaten. Reconnect bij
netwerkfout blijft via backoff. visibilitychange fungeert nog wel als
re-connect-trigger als de stream tussentijds is gesloten (b.v. 240s
hard-close server-side).
- T-862: 'ready'-event-handler telt connect-cycles. De eerste 'ready' is de
initial connect (geen resync). Bij latere 'ready' (post-reconnect) wordt
resyncActiveScopes('reconnect') aangeroepen om gemiste events op te halen.
- T-863: nieuwe lib/realtime/use-workspace-resync.ts — luistert op
document.visibilitychange (hidden→visible) en window.online; dispatcht
resyncActiveScopes('visible') resp. 'reconnect'. Mounted in
BacklogHydrationWrapper na useBacklogRealtime.
- T-864: 4 nieuwe vitest-cases voor useWorkspaceResync (jsdom): visible→
visible event, online event, hidden negeren, cleanup-bij-unmount.
Daarnaast lint-cleanup: ongebruikte 'order'-variabelen in pbi-list en
story-panel weggehaald.
Verify: lint+typecheck clean, 646/646 tests groen.
Refs: PBI-74, ST-1322, T-861..T-864
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(PBI-74): unknown-event fallback tests (Story 6)
T-865 (isUnknownEntityEvent filter) en T-866 (resync-trigger in
applyRealtimeEvent) zijn al in Story 1 geïmplementeerd in store.ts;
deze story breidt de test-coverage uit met expliciete negatieve cases
voor het type-veld noise pattern.
T-867 — 5 nieuwe vitest-cases:
- unknown entity met ANDER product_id → geen resync
- claude_job_status (type) → geen resync
- worker_heartbeat (type) → geen resync
- claude_job_enqueued (type) → geen resync
- payload zonder entity en zonder type → genegeerd
- question-entity (entity-veld, geen type, niet pbi/story/task) → resync trigger
Verify: lint+typecheck clean, 651/651 tests groen.
Refs: PBI-74, ST-1323, T-865..T-867
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(PBI-74): cache-headers + LIST endpoints (Story 7)
- T-868: cache: 'no-store' was al ingebouwd in fetchJson helper (Story 1).
Bevestigd door bestaande ensureProductLoaded test die de fetch-init
controleert.
- T-869: force-dynamic toegevoegd op alle vier nieuwe LIST-endpoints.
- T-870: vier nieuwe routes voor ensure*Loaded:
- GET /api/products/:id/backlog → ProductBacklogSnapshot
- GET /api/pbis/:id/stories → BacklogStory[]
- GET /api/stories/:id/tasks → BacklogTask[]
- GET /api/tasks/:id (nieuwe handler naast bestaande PATCH) → TaskDetail
met _detail: true marker
Auth via authenticateApiRequest (Bearer of iron-session); access-control
via productAccessFilter (gebruiker is owner of member van het product).
Statussen worden via taskStatusToApi/storyStatusToApi/pbiStatusToApi
vertaald naar lowercase API-vorm.
- T-871: SSE-route /api/realtime/backlog stuurt al ready-event direct na
LISTEN (regel 106) — geen wijziging nodig.
Verify: lint+typecheck clean, 651/651 tests groen.
Refs: PBI-74, ST-1324, T-868..T-871
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(PBI-74): oude stores opruimen (Story 8)
Workspace-store is nu de enige bron voor product-backlog client-state. De
vier voorgangers en de dual-dispatch-infrastructuur zijn verwijderd.
- T-872: grep over codebase op useBacklogStore/usePlannerStore/
useSelectionStore/useProductStore is leeg.
- T-873..T-876: stores/{backlog,planner,selection,product}-store.ts deleted.
- T-877: __tests__/realtime/payload-contract.test.ts en
__tests__/api/backlog-realtime.test.ts deleted — pbi/story/task I|U|D
payload-handling wordt al gedekt door
__tests__/stores/product-workspace/store.test.ts (incl. parent-move,
idempotent inserts, delete-cleanup).
- T-878: lib/realtime/dev-workspace-fingerprint.ts deleted, dual-dispatch
uit BacklogHydrationWrapper en lib/realtime/use-backlog-realtime.ts
weggehaald. stores/products-store.ts (lijst van producten ≠ active
product) blijft ongewijzigd.
Bijwerkingen:
- BacklogPbi en BacklogStory types in components/backlog/story-panel.tsx en
components/sprint/sprint-backlog.tsx krijgen sort_order zodat ze met de
workspace-types overeenkomen.
- Server-pages /products/[id]/page.tsx (desktop+mobile) en
/products/[id]/sprint/[sprintId]/page.tsx selecteren sort_order op story
en mappen het door in de hydration-payload.
Verify: lint+typecheck clean, 626/626 tests groen (verlies van 25 redundante
oude-store tests; workspace-store tests dekken hetzelfde gedrag).
Refs: PBI-74, ST-1325, T-872..T-878
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(PBI-74): richtlijn workspace-store + realtime patroon
Documenteert het patroon dat in Stories 1-8 is opgeleverd, zodat een
volgende workspace-store (sprint, of een nieuwe bounded context) hetzelfde
recept volgt.
- docs/patterns/workspace-store.md (nieuw): wanneer een workspace-store, de
vijf state-slices, selectors-regels (G1/G2), race-safe ensure*Loaded met
activeRequestId-guard (G4), SSE-hook + applyRealtimeEvent met
unknown-event filter, hidden-tab + reconnect resync via
useWorkspaceResync, restore-hint flow met await-chain en URL-prioriteit,
optimistic mutations (applyOptimisticMutation/rollback/settle), API
endpoint-vereisten (force-dynamic, cache: no-store), test-setup met
MemoryStorage + originalActions snapshot + mockImplementation, gotchas
G1-G8 als comment-template, en het 8-staps migratiepad.
- docs/patterns/zustand-optimistic.md: bijgewerkt voor de nieuwe
workspace-store API; verwijst voor het bredere patroon naar
workspace-store.md. Voorbeelden voor pbi-order + entity-patch.
- CLAUDE.md: patterns quickref aangevuld met workspace-store-rij.
Verify: typecheck clean.
Refs: PBI-74
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(PBI-74): solo + notifications hooks volgen ook hidden-tab/resync patroon
Het uitgangspunt van PBI-74 (robuust tegen gemiste SSE-events, hidden tabs
en onbekende notify-vormen) gold universeel — niet alleen voor
product-workspace. use-solo-realtime en use-notifications-realtime hadden
nog dezelfde bug die use-backlog-realtime in Story 5 al opgelost kreeg:
sluit stream op hidden, geen resync.
Reproductie (zoals gemeld): solo-screen open in tab A, product-backlog
open in tab B; bewerk task-title in tab B → tab A's solo-SSE was gesloten
(hidden) en kreeg het NOTIFY-event nooit. Tab terug naar solo →
EventSource reconnect maar geen resync → oude title persisteert. Postgres
NOTIFY heeft geen replay, dus zonder resync zijn die events permanent
verloren.
Fix in beide hooks (zelfde patroon als Story 5 voor backlog):
- Stream blijft open op visibilitychange hidden — geen close() meer.
- Bij hidden→visible én bij window 'online': router.refresh() zodat de
server-component opnieuw fetcht en de initial-state-prop ververst (wat
voor solo de tasks-record reset via initTasks; voor notifications de
questions-bel-state).
- Bij latere 'ready'-events na reconnect (use-solo-realtime): zelfde
router.refresh() trigger zodat we niet vertrouwen op alleen het
visibility-pad.
Verify: lint + typecheck clean, 626/626 tests groen.
Refs: PBI-74
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs: fix broken links in research-repo plan
docs/plans/lees-de-readme-md-validated-book.md beschrijft een research-
repo migratiepad. De links waren geschreven vanuit het research-repo-
perspectief (paden als stores/data-store.ts, ../Scrum4Me/CLAUDE.md,
docs/plans/zustand-store-rearchitecture.md zonder relative-prefix), wat
de doc-link-checker hier laat falen.
- Header-note toegevoegd dat het document voor de research-repo is.
- Interne refs (zustand-store-rearchitecture.md, CLAUDE.md) → relatieve
paden die in deze repo wél resolven (./zustand-..., ../../CLAUDE.md).
- Research-repo-only refs (stores/data-store.ts,
hooks/use-event-stream.ts, components/*-select.tsx, etc.) → inline
code-tags met "(research-repo)" suffix; de link-checker slaat ze over
en de leesbaarheid blijft.
Verify: npm run docs:check-links → ✓ All doc links valid (118 files).
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Janpeter Visser
GitHub
parent
0d126695db
commit
5df04feb11
46 changed files with 3736 additions and 736 deletions
414
docs/patterns/workspace-store.md
Normal file
414
docs/patterns/workspace-store.md
Normal file
|
|
@ -0,0 +1,414 @@
|
|||
---
|
||||
title: "Workspace-store + realtime — bounded-context patroon"
|
||||
status: active
|
||||
audience: [ai-agent, contributor]
|
||||
language: nl
|
||||
last_updated: 2026-05-10
|
||||
when_to_read: "When adding a new bounded-context client store backed by SSE, or when modifying product/sprint workspace state."
|
||||
---
|
||||
|
||||
# Patroon: workspace-store + realtime
|
||||
|
||||
Sinds PBI-74 is `product-workspace-store` de blueprint voor client-state op een
|
||||
**bounded context** (één coherente workflow). Andere bounded contexts mogen
|
||||
hetzelfde patroon volgen — `sprint-workspace-store`, `solo-store`,
|
||||
`notifications-store`. Dit document beschrijft wanneer je een workspace-store
|
||||
opzet, hoe je 'm structureert, hoe SSE en de store samenwerken, en welke
|
||||
gotchas in code-comments hoort.
|
||||
|
||||
Bron-ontwerp: [zustand-store-rearchitecture.md](../plans/zustand-store-rearchitecture.md).
|
||||
Referentie-implementatie: [stores/product-workspace/](../../stores/product-workspace/).
|
||||
|
||||
---
|
||||
|
||||
## Wanneer een workspace-store
|
||||
|
||||
Eén store **per bounded context**, niet per pagina en niet één megastore.
|
||||
|
||||
| Workflow | Store |
|
||||
|---|---|
|
||||
| Product backlog (PBI/story/task selectie + DnD) | `product-workspace-store` |
|
||||
| Sprint board | `sprint-workspace-store` (toekomstig, PBI > 74) |
|
||||
| Solo execution | `solo-store` |
|
||||
| Notifications/questions | `notifications-store` |
|
||||
| Idea grill/plan-flow | `idea-store` |
|
||||
| Lijst van producten | `products-store` (≠ active product) |
|
||||
|
||||
Splits niet per panel; bundel niet over workflows.
|
||||
|
||||
---
|
||||
|
||||
## State-shape
|
||||
|
||||
Vlak en **genormaliseerd**. Vijf slices:
|
||||
|
||||
```ts
|
||||
{
|
||||
context: { active*Id } // huidige selectie
|
||||
entities: { *ById } // entity-maps per kind
|
||||
relations: { ids[], idsByParent } // gesorteerde id-lijsten
|
||||
loading: { loaded*Ids, activeRequestId } // race-safe markers
|
||||
sync: { realtimeStatus, lastResyncAt, resyncReason }
|
||||
pendingMutations: { [id]: { mutation, createdAt } }
|
||||
}
|
||||
```
|
||||
|
||||
**Acties** zijn in dezelfde store:
|
||||
`hydrateSnapshot`, `setActive*`, `ensure*Loaded`, `applyRealtimeEvent`,
|
||||
`resyncActiveScopes`, `resyncLoadedScopes`,
|
||||
`applyOptimisticMutation`/`rollbackMutation`/`settleMutation`.
|
||||
|
||||
Gebruik `zustand/middleware/immer`. Mutation-style (G3 — return nooit een
|
||||
nieuwe state uit een immer-recipe; muteer de draft).
|
||||
|
||||
---
|
||||
|
||||
## Selectors
|
||||
|
||||
Module-level **`EMPTY`**-refs (G1) en `useShallow` voor lijsten (G2).
|
||||
|
||||
```ts
|
||||
// stores/product-workspace/selectors.ts
|
||||
const EMPTY_PBIS: BacklogPbi[] = []
|
||||
|
||||
export function selectVisiblePbis(s: Store): BacklogPbi[] {
|
||||
if (s.relations.pbiIds.length === 0) return EMPTY_PBIS
|
||||
return s.relations.pbiIds.map((id) => s.entities.pbisById[id]).filter(Boolean)
|
||||
}
|
||||
```
|
||||
|
||||
```tsx
|
||||
// component
|
||||
import { useShallow } from 'zustand/react/shallow'
|
||||
import { selectVisiblePbis } from '@/stores/product-workspace/selectors'
|
||||
|
||||
const pbis = useStore(useShallow(selectVisiblePbis))
|
||||
const activePbiId = useStore((s) => s.context.activePbiId) // primitive — geen useShallow
|
||||
```
|
||||
|
||||
Single-value selectors (`selectActivePbi`) hebben geen `useShallow` nodig.
|
||||
|
||||
---
|
||||
|
||||
## ensure*Loaded — race-safe loaders
|
||||
|
||||
Elke setter genereert een nieuwe `requestId`, schrijft 'm in
|
||||
`loading.activeRequestId`, en triggert de loader. De loader checkt **na de
|
||||
fetch** of de guard nog matcht — anders bail-out.
|
||||
|
||||
```ts
|
||||
setActivePbi(pbiId) {
|
||||
const requestId = newRequestId()
|
||||
set((s) => {
|
||||
s.context.activePbiId = pbiId
|
||||
s.context.activeStoryId = null
|
||||
s.context.activeTaskId = null
|
||||
s.loading.activeRequestId = requestId
|
||||
})
|
||||
if (pbiId) void get().ensurePbiLoaded(pbiId, requestId)
|
||||
}
|
||||
|
||||
async ensurePbiLoaded(pbiId, requestId) {
|
||||
const stories = await fetchJson(`/api/pbis/${pbiId}/stories`)
|
||||
if (requestId && get().loading.activeRequestId !== requestId) return
|
||||
if (!Array.isArray(stories)) return
|
||||
set((s) => { /* apply */ })
|
||||
}
|
||||
```
|
||||
|
||||
**Belangrijke regels:**
|
||||
|
||||
- Gebruik `get().method()` per call (G4) — nooit `state.method()` via een
|
||||
gecaptured snapshot. Method-refs zijn niet stabiel over immer state-versies.
|
||||
- `fetch(url, { cache: 'no-store' })` op alle client-fetches.
|
||||
- Server read-routes: `export const dynamic = 'force-dynamic'`.
|
||||
|
||||
---
|
||||
|
||||
## SSE-hook beheert transport, store beheert betekenis
|
||||
|
||||
```txt
|
||||
useXxxRealtime(activeId)
|
||||
-> opent /api/realtime/xxx?...
|
||||
-> parsed event
|
||||
-> dispatcht naar store.applyRealtimeEvent(event)
|
||||
-> beheert reconnect/backoff/status
|
||||
-> op 'ready' na (re)connect: telt cycles; latere ready triggert resync('reconnect')
|
||||
```
|
||||
|
||||
```ts
|
||||
// applyRealtimeEvent regels
|
||||
known pbi/story/task event
|
||||
→ upsert + sort, parent-move bij wijziging parent_id
|
||||
→ idempotent: bestaande id bij INSERT → return
|
||||
→ DELETE → ruim child entities op + clear actieve selectie als die viel
|
||||
|
||||
unknown entity met matching product_id, geen 'type' veld
|
||||
→ resyncActiveScopes('unknown-event')
|
||||
|
||||
job/worker/heartbeat (heeft 'type' veld)
|
||||
→ negeer
|
||||
```
|
||||
|
||||
**Idempotent:** een event dat al via een optimistic mutation is toegepast,
|
||||
mag geen dubbele insert of verkeerde rollback veroorzaken. INSERTs checken
|
||||
`if (entity exists) return`. UPDATEs zijn altijd merge-into-existing.
|
||||
|
||||
Payload-contract: zie [realtime-notify-payload.md](./realtime-notify-payload.md).
|
||||
|
||||
---
|
||||
|
||||
## Hidden tab + reconnect resync
|
||||
|
||||
EventSource blijft open als de tab `hidden` wordt — gemiste events worden
|
||||
opgehaald via een expliciete resync-laag.
|
||||
|
||||
```ts
|
||||
// In de realtime-hook
|
||||
const onVisibility = () => {
|
||||
if (document.visibilityState === 'visible' && sourceRef.current === null) {
|
||||
connect() // alleen als de stream weg is (b.v. server hard-close na 240s)
|
||||
}
|
||||
}
|
||||
// Geen close() bij hidden.
|
||||
|
||||
source.addEventListener('ready', () => {
|
||||
readyCountRef.current += 1
|
||||
if (readyCountRef.current > 1) {
|
||||
void store.resyncActiveScopes('reconnect')
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
```ts
|
||||
// useWorkspaceResync — visibility + online
|
||||
useEffect(() => {
|
||||
const onVisibility = () => {
|
||||
if (document.visibilityState === 'visible') {
|
||||
void store.resyncActiveScopes('visible')
|
||||
}
|
||||
}
|
||||
const onOnline = () => void store.resyncActiveScopes('reconnect')
|
||||
|
||||
document.addEventListener('visibilitychange', onVisibility)
|
||||
window.addEventListener('online', onOnline)
|
||||
return () => { /* remove */ }
|
||||
}, [])
|
||||
```
|
||||
|
||||
**Mount in dezelfde wrapper als de realtime-hook.** Doe nooit alleen het
|
||||
sluiten-op-hidden weghalen zonder de resync-laag erbij — dan verlies je het
|
||||
vangnet.
|
||||
|
||||
`resyncActiveScopes` triggert alleen de loaders die gekoppeld zijn aan de
|
||||
huidige selectie:
|
||||
|
||||
```ts
|
||||
async resyncActiveScopes(reason) {
|
||||
const ctx = get().context
|
||||
const tasks: Promise<void>[] = []
|
||||
if (ctx.activeProduct?.id) tasks.push(get().ensureProductLoaded(ctx.activeProduct.id))
|
||||
if (ctx.activePbiId) tasks.push(get().ensurePbiLoaded(ctx.activePbiId))
|
||||
if (ctx.activeStoryId) tasks.push(get().ensureStoryLoaded(ctx.activeStoryId))
|
||||
if (ctx.activeTaskId) tasks.push(get().ensureTaskLoaded(ctx.activeTaskId))
|
||||
set((s) => { s.sync.lastResyncAt = Date.now(); s.sync.resyncReason = reason })
|
||||
await Promise.allSettled(tasks)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## LocalStorage = restore-hint, niet waarheid
|
||||
|
||||
Selectie-id's worden gepersisteerd om bij cold reload de vorige selectie te
|
||||
herstellen, **maar de hint wordt pas toegepast nadat ensure-load is gelukt
|
||||
en de hint-id bevestigd is in `entities.byId`**.
|
||||
|
||||
```ts
|
||||
setActiveProduct(product) {
|
||||
set((s) => { s.context.activeProduct = product; ... })
|
||||
writeProductHint(product?.id ?? null)
|
||||
|
||||
if (product) {
|
||||
void (async () => {
|
||||
await get().ensureProductLoaded(product.id, requestId)
|
||||
if (get().loading.activeRequestId !== requestId) return
|
||||
const hint = readHints().perProduct[product.id]?.lastActivePbiId
|
||||
if (hint && get().entities.pbisById[hint]) {
|
||||
get().setActivePbi(hint) // cascade — die doet zelfde voor story
|
||||
}
|
||||
})()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Geen `setTimeout(0)` of microtask-trick.** De fetch is dan nog niet klaar,
|
||||
de validatie `entities.byId[hint]` faalt altijd. Chain altijd `await
|
||||
ensureXxxLoaded` en valideer in dezelfde `requestId`-cycle.
|
||||
|
||||
**URL wint van hint.** Maak een client-component (b.v.
|
||||
[`UrlTaskSync`](../../components/backlog/url-task-sync.tsx)) die op mount
|
||||
`useSearchParams().get('editTask')` leest, de hint overschrijft via
|
||||
`writeTaskHint`, en `setActiveTask` aanroept. De restore-flow leest de
|
||||
task-hint pas na drie ensure-awaits, dus de URL-write komt altijd eerder.
|
||||
|
||||
---
|
||||
|
||||
## Optimistic mutations
|
||||
|
||||
Voor DnD en status-toggles. De store registreert alleen het rollback-snapshot;
|
||||
de component muteert state direct én roept de server aan.
|
||||
|
||||
```tsx
|
||||
function handleDragEnd(event) {
|
||||
const store = useStore.getState()
|
||||
const prevOrder = [...store.relations.pbiIds]
|
||||
const newOrder = arrayMove(prevOrder, oldIndex, newIndex)
|
||||
|
||||
// 1. Snapshot voor rollback
|
||||
const mutationId = store.applyOptimisticMutation({
|
||||
kind: 'pbi-order',
|
||||
prevPbiIds: prevOrder,
|
||||
})
|
||||
|
||||
// 2. Optimistisch toepassen
|
||||
useStore.setState((s) => { s.relations.pbiIds = newOrder })
|
||||
|
||||
// 3. Server bevestigt (of niet)
|
||||
startTransition(async () => {
|
||||
const result = await reorderPbisAction(productId, newOrder)
|
||||
const st = useStore.getState()
|
||||
if (result.success) {
|
||||
st.settleMutation(mutationId)
|
||||
} else {
|
||||
st.rollbackMutation(mutationId)
|
||||
toast.error('Volgorde opslaan mislukt')
|
||||
}
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
**Cross-priority drag** vereist twee mutaties: een `pbi-order` voor de lijst
|
||||
plus een `entity-patch` voor de priority op de PBI zelf. Beide settle/rollback
|
||||
samen.
|
||||
|
||||
**SSE-echo van een net optimistisch toegepaste wijziging** moet idempotent
|
||||
zijn — INSERT → bestaat al → return; UPDATE → merge into existing.
|
||||
|
||||
---
|
||||
|
||||
## API endpoints
|
||||
|
||||
Voor elke `ensure*Loaded` een GET-route met:
|
||||
|
||||
- Auth via `authenticateApiRequest` (Bearer-token of iron-session cookie).
|
||||
- Access-control via `productAccessFilter(userId)` voor product-context;
|
||||
`getAccessibleProduct` voor explicit guards.
|
||||
- `export const dynamic = 'force-dynamic'`.
|
||||
- Status-vertaling via `taskStatusToApi` / `storyStatusToApi` /
|
||||
`pbiStatusToApi` (DB UPPER_SNAKE → API lowercase).
|
||||
|
||||
Referentie:
|
||||
[GET /api/products/:id/backlog](../../app/api/products/[id]/backlog/route.ts),
|
||||
[GET /api/pbis/:id/stories](../../app/api/pbis/[id]/stories/route.ts),
|
||||
[GET /api/stories/:id/tasks](../../app/api/stories/[id]/tasks/route.ts),
|
||||
[GET /api/tasks/:id](../../app/api/tasks/[id]/route.ts).
|
||||
|
||||
`TaskDetail` shape extends `BacklogTask` met `_detail: true` plus extra
|
||||
velden (`implementation_plan`, `acceptance_criteria`, `requires_opus`,
|
||||
`verify_only`, `verify_required`). Gebruik de `isDetail()` typeguard om de
|
||||
extra velden te tonen.
|
||||
|
||||
---
|
||||
|
||||
## Tests
|
||||
|
||||
Vitest + jsdom; setup in [`tests/setup.ts`](../../tests/setup.ts):
|
||||
|
||||
- `MemoryStorage` shim voor localStorage (G6 — vitest 4 + jsdom 29 mist 'm
|
||||
als configurable global).
|
||||
- `globalThis.fetch` herconfigureerbaar gemaakt zodat `vi.spyOn` werkt
|
||||
(anders krijg je `Cannot redefine property: fetch`).
|
||||
- Default fetch-stub die `null` JSON returnt — voorkomt unhandled rejections
|
||||
uit fire-and-forget `ensure*Loaded` calls die in tests niet expliciet
|
||||
gemockt zijn. Tests overrulen met `vi.spyOn(globalThis, 'fetch')` per case.
|
||||
- `mockImplementation` (G8) — niet `mockResolvedValue` — anders is de
|
||||
Response-body na de eerste `.json()` weg.
|
||||
|
||||
```ts
|
||||
// G5: snapshot original actions module-level, restore in beforeEach
|
||||
const originalActions = (() => {
|
||||
const s = useStore.getState()
|
||||
return { /* alle action-refs */ }
|
||||
})()
|
||||
|
||||
function resetStore() {
|
||||
useStore.setState((s) => {
|
||||
Object.assign(s, initialDataSlices)
|
||||
Object.assign(s, originalActions)
|
||||
})
|
||||
}
|
||||
|
||||
beforeEach(resetStore)
|
||||
```
|
||||
|
||||
**Acties mocken:** gebruik `setState((s) => { s.method = vi.fn() })`. Niet
|
||||
`vi.spyOn(state, 'method')` — de immer-frozen state is niet redefinable.
|
||||
|
||||
**Verplichte test-cases per workspace-store:**
|
||||
|
||||
- `hydrateSnapshot` vult entities + relations met sortering.
|
||||
- Selection cascade: `setActivePbi` reset story+task; `setActiveStory` reset
|
||||
task.
|
||||
- `setActiveProduct(null)` ruimt entities en relations op.
|
||||
- `applyRealtimeEvent` pbi/story/task `I|U|D` met sortering en parent-move.
|
||||
- Event voor ander `product_id` wordt genegeerd.
|
||||
- Unknown entity met matching product → `resyncActiveScopes('unknown-event')`
|
||||
trigger.
|
||||
- Job/worker/heartbeat/question events met `type`-veld → geen resync.
|
||||
- Delete-cleanup van actieve selectie.
|
||||
- Race-safe `ensure*Loaded` met requestId-guard (oude in-flight mag niet
|
||||
nieuwere selectie overschrijven).
|
||||
- `ensureTaskLoaded` zet `_detail: true`.
|
||||
- `resyncActiveScopes` triggert ensure-keten met juiste URLs en zet
|
||||
`lastResyncAt` + `resyncReason`.
|
||||
- localStorage restore-hints per setter.
|
||||
- Hint die niet (meer) in entities zit wordt genegeerd.
|
||||
- Optimistic mutation rollback/settle/SSE-echo idempotent.
|
||||
|
||||
---
|
||||
|
||||
## Gotchas — comment-template voor in code
|
||||
|
||||
Documenteer deze in code via comments boven de fix.
|
||||
|
||||
| # | Symptoom | Fix |
|
||||
|---|---|---|
|
||||
| **G1** | "Maximum update depth exceeded" — `s.byId[x] ?? []` levert nieuwe array per render | Module-level `EMPTY` const als fallback |
|
||||
| **G2** | Component re-rendert op iedere store-mutatie ondanks dat z'n data niet wijzigt | `useShallow(selectXxx)` voor lijsten |
|
||||
| **G3** | Hele state lijkt gewist na een `setState((s) => ({ context: ... }))` | Gebruik mutation-style: `setState((s) => { s.context.x = y })` (immer recipe muteert draft) |
|
||||
| **G4** | "method is not a function" in async context, of inconsistente state-mutaties | `get().method()` per call; nooit `const m = state.method` cachen |
|
||||
| **G5** | Tests beïnvloeden elkaar via `setState({ resyncActiveScopes: vi.fn() })` | `originalActions` snapshot op module-load + restore in `beforeEach` |
|
||||
| **G6** | `localStorage.clear is not a function` in vitest | `MemoryStorage` shim in `tests/setup.ts` |
|
||||
| **G7** | "Failed to parse URL from /api/..." in test-fetch | Mock fetch via `vi.spyOn(globalThis, 'fetch')` of stub in setup |
|
||||
| **G8** | "Body is unusable: Body has already been read" | `vi.fn().mockImplementation(() => Promise.resolve(new Response(...)))` — niet `mockResolvedValue` met een vooraf-gemaakte Response |
|
||||
|
||||
---
|
||||
|
||||
## Migratiepad voor een nieuwe workspace-store
|
||||
|
||||
Volg dezelfde 8 stappen als PBI-74 (zie
|
||||
[zustand-workspace-store-implementation.md](../plans/zustand-workspace-store-implementation.md)):
|
||||
|
||||
1. Skelet — types, store, selectors, restore + tests; geen UI-impact.
|
||||
2. Hydratie overstappen (parallel naast bestaande store).
|
||||
3. Componenten omzetten — `useShallow` voor lijsten, `setActiveX` setters.
|
||||
4. Race-safe loaders + restore-hints + URL-prioriteit.
|
||||
5. Hidden-tab + reconnect-resync (één PR — anders verlies je vangnet).
|
||||
6. Unknown-event filter (`isUnknownEntityEvent`).
|
||||
7. Cache-headers + LIST-endpoints (`force-dynamic`, `cache: 'no-store'`).
|
||||
8. Oude store opruimen.
|
||||
|
||||
Stap 9 ("sprint-workspace-store") is de toepassing van dit patroon op de
|
||||
sprint-flow — kan starten zodra `product-workspace-store` enkele weken
|
||||
stabiel in productie staat.
|
||||
|
|
@ -3,34 +3,99 @@ title: "Zustand optimistische update + rollback"
|
|||
status: active
|
||||
audience: [ai-agent, contributor]
|
||||
language: nl
|
||||
last_updated: 2026-05-03
|
||||
when_to_read: "When adding client-side state mutations that need optimistic UI and rollback."
|
||||
last_updated: 2026-05-10
|
||||
when_to_read: "When adding client-side state mutations that need optimistic UI and rollback (DnD, status toggles)."
|
||||
---
|
||||
|
||||
# Patroon: Zustand optimistische update + rollback
|
||||
|
||||
Gebruik dit patroon bij elke dnd-kit `onDragEnd` handler.
|
||||
Sinds PBI-74 lopen optimistic mutations via `applyOptimisticMutation`/
|
||||
`rollbackMutation`/`settleMutation` op de **workspace-store**. Het bredere
|
||||
patroon (store-design, SSE-integratie, restore-hints, tests) staat in
|
||||
[workspace-store.md](./workspace-store.md). Dit document beschrijft het
|
||||
DnD/status-mutation flow specifiek.
|
||||
|
||||
```ts
|
||||
const { pbiOrder, reorderPbis, rollbackPbis } = usePlannerStore()
|
||||
## Patroon
|
||||
|
||||
async function handleDragEnd(event: DragEndEvent) {
|
||||
1. Snapshot rollback-info via `applyOptimisticMutation` — krijgt `mutationId`.
|
||||
2. Pas state direct aan via `setState`.
|
||||
3. Server-actie aanroepen.
|
||||
4. Op success: `settleMutation(mutationId)` (ruimt pending-record op).
|
||||
5. Op error: `rollbackMutation(mutationId)` (herstelt vorige state + toast).
|
||||
|
||||
Cross-priority drag vereist twee mutaties (order + entity-patch) die samen
|
||||
settlen of rollbacken.
|
||||
|
||||
## Voorbeeld — PBI reorder
|
||||
|
||||
```tsx
|
||||
import { useProductWorkspaceStore } from '@/stores/product-workspace/store'
|
||||
|
||||
function handleDragEnd(event: DragEndEvent) {
|
||||
const { active, over } = event
|
||||
if (!over || active.id === over.id) return
|
||||
|
||||
const prevOrder = [...pbiOrder[productId]]
|
||||
const newOrder = arrayMove(prevOrder, oldIndex, newIndex)
|
||||
const store = useProductWorkspaceStore.getState()
|
||||
const prevOrder = [...store.relations.pbiIds]
|
||||
const oldIndex = prevOrder.indexOf(active.id as string)
|
||||
const newIndex = prevOrder.indexOf(over.id as string)
|
||||
if (oldIndex === -1 || newIndex === -1) return
|
||||
const newOrder = arrayMove([...prevOrder], oldIndex, newIndex)
|
||||
|
||||
// 1. Optimistisch updaten (direct zichtbaar voor gebruiker)
|
||||
reorderPbis(productId, newOrder)
|
||||
// 1. Snapshot rollback-info
|
||||
const mutationId = store.applyOptimisticMutation({
|
||||
kind: 'pbi-order',
|
||||
prevPbiIds: prevOrder,
|
||||
})
|
||||
|
||||
// 2. Persisteren via Server Action
|
||||
const result = await reorderPbisAction(productId, newOrder)
|
||||
// 2. Optimistisch toepassen
|
||||
useProductWorkspaceStore.setState((s) => {
|
||||
s.relations.pbiIds = newOrder
|
||||
})
|
||||
|
||||
// 3. Rollback bij fout
|
||||
if (!result.success) {
|
||||
rollbackPbis(productId, prevOrder)
|
||||
toast.error('Volgorde opslaan mislukt')
|
||||
}
|
||||
// 3-5. Server bevestigt of niet
|
||||
startTransition(async () => {
|
||||
const result = await reorderPbisAction(productId, newOrder)
|
||||
const st = useProductWorkspaceStore.getState()
|
||||
if (result.success) {
|
||||
st.settleMutation(mutationId)
|
||||
} else {
|
||||
st.rollbackMutation(mutationId)
|
||||
toast.error('Volgorde opslaan mislukt')
|
||||
}
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
## Voorbeeld — entity-patch (priority-wijziging)
|
||||
|
||||
```tsx
|
||||
const prevPbi = store.entities.pbisById[id]
|
||||
const patchMutationId = store.applyOptimisticMutation({
|
||||
kind: 'entity-patch',
|
||||
entity: 'pbi',
|
||||
id,
|
||||
prev: prevPbi,
|
||||
})
|
||||
useProductWorkspaceStore.setState((s) => {
|
||||
const pbi = s.entities.pbisById[id]
|
||||
if (pbi) pbi.priority = newPriority
|
||||
})
|
||||
// settle/rollback identiek aan order-flow
|
||||
```
|
||||
|
||||
## Mutation-soorten
|
||||
|
||||
| `kind` | Rollback-data | Use-case |
|
||||
|---|---|---|
|
||||
| `pbi-order` | `prevPbiIds` | DnD reorder van PBI's |
|
||||
| `story-order` | `pbiId` + `prevStoryIds` | DnD reorder van stories binnen een PBI |
|
||||
| `task-order` | `storyId` + `prevTaskIds` | DnD reorder van tasks binnen een story |
|
||||
| `entity-patch` | `entity` + `id` + `prev` (volledig vorig record of `undefined` voor delete-rollback) | Property-wijzigingen (priority, status), of optimistic delete/undelete |
|
||||
|
||||
## SSE-echo idempotent verwerken
|
||||
|
||||
Wanneer de server bevestigt en de NOTIFY-trigger het bijbehorende event
|
||||
emitteert, mag `applyRealtimeEvent` **geen dubbele insert** veroorzaken en
|
||||
**geen rollback triggeren**. INSERTs checken bestaan; UPDATEs mergen
|
||||
into-existing. Zie `applyRealtimeEvent` in [`stores/product-workspace/store.ts`](../../stores/product-workspace/store.ts).
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue