janpeter/Scrum4Me
0
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Scrum4Me/docs/plans/zustand-workspace-store-implementation.md
Janpeter Visser 98ee05d458
feat(PBI-74): sprint-workspace-store (Story 9) (#181) 
* feat(PBI-74): sprint-workspace-store skelet (Story 9 / T-879)

- stores/sprint-workspace/{types,store,selectors,restore}.ts conform
  product-workspace blueprint
- ContextSlice: activeProduct, activeSprintId, activeStoryId, activeTaskId
- EntitiesSlice: sprintsById, storiesById, tasksById
- RelationsSlice: sprintIdsByProduct, storyIdsBySprint, taskIdsByStory
- LoadingSlice met activeRequestId voor race-safe ensure*Loaded
- SyncSlice: realtimeStatus, lastResyncAt, resyncReason
- Realtime applyRealtimeEvent voor sprint/story/task entities + unknown-event
  fallback, parent-move handling, child-cleanup bij D op sprint/story
- Optimistic mutations: sprint-story-order, sprint-task-order, entity-patch
- LocalStorage hints (storage key sprint-workspace-hints) per product/sprint
- 45 unit-tests groen — verplicht 13 cases uit workspace-store.md §Tests

* feat(PBI-74): sprint hydratie + realtime SSE (Story 9 / T-880)

- app/api/realtime/sprint/route.ts: SSE-stream LISTEN/NOTIFY op
  scrum4me_changes, filter entity ∈ {sprint, story, task} per product_id;
  ready-event, heartbeat 25s, hard-close 240s
- lib/realtime/use-sprint-realtime.ts: client-hook met backoff-reconnect;
  ready-cycle telt; geen close op hidden; setRealtimeStatus
- lib/realtime/use-sprint-workspace-resync.ts: visibility + online triggers
  resyncActiveScopes('visible' | 'reconnect')
- components/sprint/sprint-hydration-wrapper.tsx: hydrateSnapshot via
  useEffect met fingerprint-check; mount realtime + resync
- app/(app)/products/[id]/sprint/[sprintId]/page.tsx: wrap SprintBoardClient
  in SprintHydrationWrapper; bouw SprintWorkspaceTask-shape voor
  tasksByStoryWorkspace en SprintHydrationData voor de wrapper

Schaduw-fase: useSprintStore blijft parallel werken in board components
totdat T-881 die migreert en T-883 de oude store opruimt.

* feat(PBI-74): migreer sprint-board componenten naar workspace-store (Story 9 / T-881)

- TaskList: leest tasks via selectTasksForStory met useShallow; DnD via
  applyOptimisticMutation('sprint-task-order') + settle/rollback
- SprintBacklogLeft: leest stories via selectStoriesForActiveSprint met
  useShallow; props 'stories' verwijderd
- SprintBoardClient: leest sprintStories uit selector i.p.v. lokale state;
  add/remove via direct setState met manuele snapshot-rollback;
  reorder via applyOptimisticMutation('sprint-story-order'); assignee-
  change via store entity-mutation; tasksByStory en sprintStoryIdList
  props weg
- app/(app)/.../sprint/[sprintId]/page.tsx: bouwt SprintHydrationData voor
  wrapper; geeft alleen non-store props door aan SprintBoardClient

useSprintStore wordt nergens meer geïmporteerd — alleen comment-referentie
in SprintHydrationWrapper. Cleanup van het bestand zelf in T-883.

Verify groen (671 tests, typecheck, lint clean).

* feat(PBI-74): read-routes voor sprint-workspace + cache-headers (Story 9 / T-882)

- GET /api/products/[id]/sprints — lijst sprints per product
  (ensureProductSprintsLoaded). force-dynamic, productAccessFilter,
  start_date/end_date naar ISO-date string.
- GET /api/sprints/[id]/workspace — sprint snapshot met sprint-meta,
  stories (incl. taskCount/doneCount/assignee), tasks gegroepeerd per
  story (ensureSprintLoaded). force-dynamic, productAccessFilter via
  product, status-vertaling via taskStatusToApi/storyStatusToApi.

Race-safe loaders (activeRequestId-guard), restore-flow (cascade-restore
via writeProductHint/writeSprintHint/writeStoryHint/writeTaskHint),
resync-laag (useSprintWorkspaceResync visibility + online), unknown-event
filter (isUnknownEntityEvent → resyncActiveScopes('unknown-event')) zijn
allemaal in T-879/T-880 al ingebouwd; T-882 sluit het loop met de
ontbrekende API-endpoints + cache-headers (cache: 'no-store' op fetches,
force-dynamic op routes).

* feat(PBI-74): cleanup oude sprint-store (Story 9 / T-883)

- rm stores/sprint-store.ts — alle componenten lezen nu via
  useSprintWorkspaceStore (T-881 voltooide imports-migratie)
- update SprintHydrationWrapper-comment: schaduw-fase referenties
  verwijderd

Verify: 671 tests groen, typecheck clean, build groen.
Grep useSprintStore = 0.

* docs(PBI-74): update Story 9 status in implementatieplan (T-884)

- Frontmatter: ready-to-execute → in-progress; revision 1 → 2;
  last_updated 2026-05-09 → 2026-05-10
- Stories-tabel: kolom Status toegevoegd (Stories 1-8 DONE via PR #180,
  Story 9 met T-884 op review)
- §Story 9: per-taak status + acceptatie-checklist voor T-884 manuele
  staging-checks
- Aanbeveling-blokje: noteert dat Story 9 vroeger gestart is dan het
  ontwerpdoc adviseerde
2026-05-10 06:53:04 +02:00

11 KiB
Raw Blame History

title status audience language last_updated revision
Zustand workspace-store implementatieplan (PBI-74) in-progress
maintainer
contributor
ai-agent
nl 2026-05-10 2

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.

Status (2026-05-10): Stories 1-8 merged via PR #180 (product-workspace-store productie). Story 9 (sprint-workspace-store) uitgevoerd op feat/sprint-workspace-store — automatische verify+build groen, manuele E2E-staging-checks van T-884 nog te doen voor merge.

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

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 (DONE): stores/sprint-workspace/{types,store,selectors,restore}.ts + 45 unit-tests groen. Mirrort product-workspace blueprint met sprint-specifieke aanpassingen (sprintIdsByProduct, storyIdsBySprint, sprint-story-membership semantiek).
  • T-880 — Hydratie + realtime (DONE): app/api/realtime/sprint/route.ts SSE-endpoint, lib/realtime/use-sprint-realtime.ts, lib/realtime/use-sprint-workspace-resync.ts, components/sprint/sprint-hydration-wrapper.tsx. Wrapper hydreert via fingerprint-check; SSE blijft open op hidden, ready-cycle triggert reconnect-resync.
  • T-881 — Componenten (DONE): TaskList, SprintBacklogLeft, SprintBoardClient lezen via selectors uit useSprintWorkspaceStore met useShallow. DnD via applyOptimisticMutation('sprint-story-order' | 'sprint-task-order') met settle/rollback; add/remove via direct setState met manuele snapshot-rollback.
  • T-882 — Race-safe + restore + resync + unknown-event + read-routes (DONE): GET /api/products/[id]/sprints en GET /api/sprints/[id]/workspace toegevoegd; activeRequestId-guard + restore-flow + useSprintWorkspaceResync + isUnknownEntityEvent waren al geïmplementeerd in T-879/T-880.
  • T-883 — Cleanup (DONE): stores/sprint-store.ts verwijderd. Grep useSprintStore = 0. Verify (671 tests) + build groen.
  • T-884 — E2E sprint-board verificatie (REVIEW — manuele staging-checks):
    • Cold reload → laatste sprint hersteld
    • Tab hidden > 30s + terug → resync
    • Netwerk uit/aan → reconnect + resync
    • DnD reorder → optimistic UI; SSE-echo idempotent
    • DB UPDATE story zonder delta → unknown-event resync binnen 1 cycle
    • Twee tabs open → mutatie zichtbaar in beide binnen ~2s

Aanbeveling per ontwerpdoc: Story 9 was bedoeld om pas te starten nadat product-workspace enkele weken stabiel in productie staat. PR #180 merged 2026-05-10; Story 9 vervolgens diezelfde dag uitgevoerd op gebruikersverzoek. Stabiliteit van product-workspace + impact van Story 9 op sprint-workflow nog te observeren in staging/productie.

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.