docs(backlog): add TECH-TYPED-ROUTER-DRIFT

Triggered by the typed-router.d.ts regeneration in 3198698. Documents
three approaches (lefthook pre-commit, gitignore+postinstall, CI-check)
with their trade-offs. Defers selection to implementation time;
recommends bundling with the next pages-tree refactor (likely WS-3 PR-B).

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
2026-05-04 21:53:38 +02:00
parent 31986989cd
commit 831f36e618

View File

@@ -642,6 +642,67 @@ of `plugins/` raakt, of een dedicated 2-3 uur sessie na WS-6 sluiting.
---
### TECH-TYPED-ROUTER-DRIFT — apps/app/typed-router.d.ts drifts when pages/ changes are merged without rebuild
**Aanleiding:** Op 2026-05-04 bleek `apps/app/typed-router.d.ts`
achter te lopen op de pages-tree: vier `form-failures` routes
(organisation + platform, list + detail) waren al maanden geleden
gelandt in main, maar de gegenereerde route-types waren nooit
mee-gecommit. Pas een lokale `pnpm build` triggerde
`unplugin-vue-router` om het bestand te regenereren, waarna een
losse commit (`3198698`) de drift dichtmaakte. Zonder die toevallige
build-run had de drift onbeperkt door kunnen lopen — TypeScript
flagde de stale routes niet, en niemand routeert via de typed names
hard genoeg dat het brak.
Het bestand is tracked, niet gitignored. Dat betekent: elke PR die
een file in `apps/app/src/pages/` toevoegt of hernoemt, moet
óók de regeneratie van `typed-router.d.ts` meecommitten. In de
praktijk gebeurt dat nu inconsistent.
**Wat:** Drie reële paden, kies bij implementatie:
- **Approach 1 (preferred): pre-commit hook in lefthook.**
Voeg een lefthook pre-commit hook toe die — wanneer een
`apps/app/src/pages/**` file in de staging-set zit —
`unplugin-vue-router` triggert en `apps/app/typed-router.d.ts`
re-stage't als hij is veranderd. Hook is silent op de happy
path; faalt loud bij regeneratie-error. Voordeel: types altijd
in sync in git, fresh clones werken zonder eerst te builden.
Nadeel: extra commit-tijd voor pages-changes (~2-5s per commit
in de plugin), en `unplugin-vue-router` heeft geen standalone
CLI-mode dus de hook wordt een Node-script dat de plugin laadt
en handmatig aanstuurt — fragiel bij plugin-versie-upgrades.
- **Approach 2 (alternative): gitignore + regenereer in postinstall.**
Voeg `apps/app/typed-router.d.ts` toe aan `.gitignore`. Voeg een
`postinstall` script in `apps/app/package.json` dat `vue-tsc` of
een vergelijkbare prebuild-stap triggert die `unplugin-vue-router`
zijn type-emit laat doen. Voordeel: drift is structureel
onmogelijk — er is niets meer in git om uit sync te raken. Nadeel:
fresh clones zijn een paar seconden trager (`pnpm install` doet
meer werk), en als `postinstall` faalt heb je IDE-rode-squiggles
totdat je het oplost.
- **Approach 3 (status quo + alarm): CI-check.**
Houd het bestand tracked, maar voeg een CI-stap toe die
`unplugin-vue-router` regenereert en faalt als de output
verschilt van wat in git staat. Voordeel: minimale lokale
workflow-impact. Nadeel: CI-only — drift wordt pas gevonden
bij PR-build. Werkt alleen als er CI is (op het moment van
schrijven: er is nog geen GitHub-Actions / Drone / Gitea-Actions
pipeline geconfigureerd in deze repo).
**Prioriteit:** Laag — geen functionele impact, alleen DX en
type-safety-betrouwbaarheid. Geen blocker voor andere
workstreams. Aanbevolen moment: meelift met de eerste
substantiële pages-tree refactor (bijvoorbeeld WS-3 PR-B die
de portal pages naar `apps/app/src/pages/portal/` verhuist —
dán is de drift-kans het grootst en de pijn van onbeschermd
laten ook).
---
### TECH-WS3-BOUNDARIES-SUBZONES — Sub-zone import-boundaries inside components/ and pages/
**Aanleiding:** WS-3 sessie 1c heeft top-level zone-boundaries in