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 66c30fc49c 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:50:11 +02:00

191 lines
11 KiB
Markdown
Raw Blame History

---
title: "Zustand workspace-store implementatieplan (PBI-74)"
status: in-progress
audience: [maintainer, contributor, ai-agent]
language: nl
last_updated: 2026-05-10
revision: 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](./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](./zustand-store-rearchitecture.md)).
- 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](./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.
Reference in a new issue View git blame Copy permalink