janpeter/Scrum4Me
0
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2
Scrum4Me/docs/plans/zustand-workspace-store-implementation.md
Madhura68 48d1e11a2a 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>
2026-05-10 00:55:22 +02:00

9.2 KiB
Raw Blame History

title status audience language last_updated revision
Zustand workspace-store implementatieplan (PBI-74) ready-to-execute
maintainer
contributor
ai-agent
nl 2026-05-09 1

Zustand workspace-store implementatieplan

PBI in Scrum4Me-MCP: PBI-74 — Zustand store rearchitecture — product- en sprint-workspace.

Bron-ontwerp (architectuur en gotchas): zustand-store-rearchitecture.md revisie 3.

Dit document koppelt de stories en taken in MCP aan de implementatie. Per story acceptatiecriteria; per taak een concrete deliverable. Alle items staan in MCP op OPEN/TO_DO. Geen executie tot expliciete trigger ("voer Story 1 uit").

Context

De client-state ligt over vier los gegroeide stores: backlog-store, planner-store, selection-store, product-store. Vier zwakheden:

  • SSE sluit op tab hidden zonder resync bij visible — gemiste events blijven gemist.
  • Geen reconcile bij reconnect (Postgres NOTIFY heeft geen replay).
  • Onbekende entity-events worden stil genegeerd.
  • LocalStorage soms behandeld als waarheid i.p.v. restore-hint.
  • Geen race-safe loaders — trage fetch van oude selectie kan nieuwste overschrijven.

De rearchitecture lost dit op via één product-workspace-store (en analoog sprint-workspace-store) met genormaliseerde entity-maps, race-safe ensure*Loaded met activeRequestId-guard, expliciete resync-laag (visible/reconnect/unknown-event), idempotente SSE-application en localStorage als pure restore-hint.

Aanpak

  • Eén PBI (PBI-74).
  • Negen stories die mappen op de stappen 1-9 in het bron-ontwerp.
  • Granulariteit Story 3 = één story met taken per component.
  • Story 5 in één PR (visibility-handling + resync horen samen).
  • Per story: PR, npm run verify && npm run build groen, status DONE pas na merge.
  • Branch: feat/zustand-workspace-store (één branch voor alle stories).

Stories en taken

# Story MCP Taken
1 Skelet + test-infrastructuur ST-1318 T-837 … T-843 (7)
2 Hydratie overstappen (parallel-running) ST-1319 T-844 … T-847 (4)
3 Componenten omzetten naar workspace-store ST-1320 T-848 … T-855 (8)
4 Race-safe loaders en restore-hints ST-1321 T-856 … T-860 (5)
5 Hidden-tab + reconnect resync (één PR) ST-1322 T-861 … T-864 (4)
6 Unknown-event fallback ST-1323 T-865 … T-867 (3)
7 Cache-headers en read-routes ST-1324 T-868 … T-871 (4)
8 Oude stores opruimen ST-1325 T-872 … T-878 (7)
9 Sprint-workspace-store ST-1326 T-879 … T-884 (6)

Totaal: 48 taken.

Story 1 — Skelet + test-infrastructuur

Doel: nieuwe store + selectors + restore-utils met volledige unit-test-suite, nog zonder UI-consumenten.

Belangrijkste taken:

  • T-837 — Vitest naar jsdom + tests/setup.ts met MemoryStorage (G6).
  • T-838/839/840/841 — stores/product-workspace/{types,store,selectors,restore}.ts.
  • T-842 — Volledige test-suite per §Testing setup-checklist (G5/G7/G8).
  • T-843 — API endpoint-audit voor ensure*Loaded URLs.

Acceptatie: alle test-cases groen, geen UI-impact.

Story 2 — Hydratie overstappen

Doel: BacklogHydrationWrapper en useBacklogRealtime voeden zowel oude store als nieuwe store. Componenten lezen nog uit oude.

Taken: T-844 (wrapper dual-dispatch), T-845 (realtime dual-dispatch), T-846 (dev-only fingerprint verifyer), T-847 (productpicker → setActiveProduct).

Acceptatie: schaduw-store inhoud matcht oude store na elk SSE-event.

Story 3 — Componenten omzetten

Doel: componenten lezen uit nieuwe workspace-store; oude stores hebben geen UI-consumenten meer.

Taken per component: T-848 (split-pane), T-849 (pbi-list), T-850 (story-panel), T-851 (task-panel), T-852 (start-sprint-button), T-853 (set-current-product). Plus T-854 (G1/G2-audit) en T-855 (integration-tests bijwerken).

Acceptatie: geen "Maximum update depth" warnings; oude store-imports alleen nog in tests die in Story 8 verdwijnen.

Story 4 — Race-safe loaders en restore-hints

Doel: ensure*Loaded met activeRequestId-guard; localStorage hints met validatie.

Taken: T-856 (guard), T-857 (restore-flow met await ensure-chain), T-858 (hint-persistentie), T-859 (URL-prioriteit), T-860 (race-safety tests).

Acceptatie: trage fetch + her-selectie corrumpeert nooit; cold reload restoret zonder fout.

Story 5 — Hidden-tab + reconnect resync (één PR)

Doel: SSE blijft open op hidden; resync via expliciete laag.

Taken: T-861 (geen close op hidden), T-862 (ready-event triggert resync na reconnect), T-863 (useWorkspaceResync hook), T-864 (tests).

Acceptatie: hidden→visible en reconnect herstellen gemiste wijzigingen in één cyclus.

Story 6 — Unknown-event fallback

Doel: onbekende entity-events triggeren resync; job/worker noise wordt genegeerd.

Taken: T-865 (isUnknownEntityEvent filter), T-866 (resync-trigger), T-867 (negatieve filter-tests).

Acceptatie: directe DB UPDATE zonder herkenbare delta-event wordt zichtbaar binnen één resync; job-events triggeren geen resync.

Story 7 — Cache-headers en read-routes

Doel: geen stale data uit Next/browser cache.

Taken: T-868 (cache: 'no-store'), T-869 (force-dynamic audit), T-870 (LIST-endpoints toevoegen waar nodig), T-871 (SSE-route ready-event coverage).

Acceptatie: response headers in productie tonen cache-control: no-store; LIST-endpoints bestaan voor alle ensure*Loaded.

Story 8 — Oude stores opruimen

Doel: vier oude stores verwijderd.

Taken: T-872 (grep), T-873/874/875/876 (delete vier files), T-877 (oude tests migreren), T-878 (stores/products-store.ts blijft + dev-fingerprint cleanup).

Acceptatie: grep useBacklogStore|usePlannerStore|useSelectionStore|useProductStore = 0; npm run verify && npm run build groen.

Story 9 — Sprint-workspace-store

Doel: zelfde patroon op sprint-workflow toegepast.

Taken: T-879 (skelet), T-880 (hydratie+realtime), T-881 (componenten), T-882 (race-safe + restore + resync + unknown-event in één keer), T-883 (cleanup oude sprint-state), T-884 (E2E sprint-board verificatie).

Aanbeveling per ontwerpdoc: start Story 9 pas nadat product-workspace enkele weken stabiel in productie staat. PBI-74 sluit pas wanneer Story 9 ook merged is.

Critical files

Te wijzigen:

  • vitest.config.ts — env naar jsdom, setupFiles
  • nieuw: tests/setup.ts — MemoryStorage, restoreAllMocks
  • nieuw: stores/product-workspace/{types,store,selectors,restore}.ts
  • nieuw: stores/sprint-workspace/{types,store,selectors,restore}.ts
  • nieuw: lib/realtime/use-workspace-resync.ts
  • components/backlog/backlog-hydration-wrapper.tsx
  • lib/realtime/use-backlog-realtime.ts
  • components/backlog/backlog-split-pane.tsx, pbi-list.tsx, story-panel.tsx, task-panel.tsx
  • components/.../start-sprint-button.tsx, set-current-product.tsx
  • read-routes onder app/api/... voor PBI/story/task LIST + detail
  • te verwijderen in Story 8: stores/{backlog,planner,selection,product}-store.ts

Te hergebruiken (geen wijziging):

  • lib/product-access.ts — getAccessibleProduct, blijft auth/access-bron
  • app/api/realtime/backlog/route.ts — ready-event al aanwezig
  • docs/patterns/realtime-notify-payload.md — payload-contract
  • docs/patterns/route-handler.md — REST patroon
  • stores/products-store.ts, stores/solo-store.ts, stores/notifications-store.ts, stores/idea-store.ts, stores/jobs-store.ts — blijven ongewijzigd

Verificatie per story

  • Story 1: Vitest groen voor alle test-cases (hydrate, cascade, realtime, ensureLoaded race, resync, restore-hints, optimistic mutation).
  • Story 2: dev-server, productpagina, fingerprint match in console.
  • Story 3: klik door 3 panels, DnD test, geen "Maximum update depth"-warnings.
  • Story 4: staging — cold reload, throttle fetch + her-selecteer.
  • Story 5: tab hidden > 30s + terug → resync zichtbaar; netwerk uit/aan → reconnect+resync.
  • Story 6: DB UPDATE op story zonder delta-event → zichtbaar binnen 1 resync; job-events negeren resync.
  • Story 7: response headers cache-control: no-store; tweede pageload toont verse data.
  • Story 8: grep oude store-imports = 0; npm run verify && npm run build groen.
  • Story 9: sprint-board flow analoog Story 1-8 verifications.

Eind-acceptatie PBI-74: alle items uit §Acceptatiecriteria van zustand-store-rearchitecture.md (regels 727-746) behaald.

Workflow per story

  1. git checkout -b feat/zustand-workspace-store (eerste story); blijf op deze branch tot expliciete cut.
  2. mcp__scrum4me__get_claude_context → pak next story uit PBI-74.
  3. Voer taken uit in sort_order; update status per taak via mcp__scrum4me__update_task_status.
  4. Lees relevante bestanden + patronen vóór begin (zie §Critical files).
  5. npm run verify && npm run build per laag.
  6. Commit per laag (git add -A && git commit); geen push tussendoor.
  7. Story-status sluit zodra alle taken DONE.
  8. Lege story-queue → git push -u origin feat/zustand-workspace-store + gh pr create.
  9. Per story een eigen PR; merge één voor één.