diff --git a/dev-docs/BACKLOG.md b/dev-docs/BACKLOG.md index 5a47d8da..c4d56070 100644 --- a/dev-docs/BACKLOG.md +++ b/dev-docs/BACKLOG.md @@ -1450,6 +1450,62 @@ other `custom_fields` properties) as a form binding target. May coincide with Crewli's v2 dietary management feature work. **Refs:** RFC-WS-6.md §3 Q9 v1.2 addendum, ARCH-BINDINGS.md appendix. +## API response validation + +### ARCH-API-RESPONSE-VALIDATION — Uniforme typed + runtime-validated contracts op de API-grens + +**Aanleiding:** PR-B2a's `contexts.{available, default}` block op `/auth/me` exposeert de bredere +architecturale gap: backend-resources emiteren JSON shapes die frontend-composables consumeren via +hand-geschreven TypeScript interfaces met `as ResponseType` casts. Er is geen runtime-check die +backend ↔ frontend drift vangt. String-literal velden zoals `'portal' | 'organizer'` of +`'ok' | 'failed'` bestaan zonder canonieke enumeratie aan beide kanten van de boundary. Deze +gap is structureel, niet beperkt tot één endpoint; een halve oplossing (alleen frontend Enum, +of alleen één endpoint met Zod) zou een gemixt patroon vastleggen. + +**Wat:** Eigen workstream met eigen ARCH-document (`dev-docs/ARCH-API-VALIDATION.md` skeleton +geland). Scope: + +- **Backend:** Audit van `App\Http\Resources\**` op enumerated values. PHP Enums onder + `App\Enums\**` voor alle geënumereerde domeinwaarden (auth contexts, statussen, role + categories, purpose names). Resources emiteren `->value` (geen wire-format-breaking change). +- **Frontend:** Adoptie van Zod als runtime-validator op API-response-ingress. Conventie: + elke composable onder `apps/app/src/composables/api/**` parsest zijn response door een + Zod-schema. TypeScript types worden afgeleid via `z.infer` — geen + hand-geschreven response-interfaces. +- **Codegen:** Pipeline die backend-resources → Zod-schemas + TS-types genereert. Kandidaten: + Scramble OpenAPI output (per DOC-01) naar `openapi-zod-client` / `orval`, of een + hand-rolled generator op PHP Resource introspectie. +- **Tooling:** Reference-implementatie met round-trip backend Enum → resource → codegen → + Zod-schema → composable → typed return. CI-gate die unvalidated composables flagt. + +**Sequentie:** Ingepland **na** WS-3 PR-C (cleanup) en **na** WS-7 (GlitchTip), **vóór** +RFC-FORM-BUILDER-UI implementatie begint. Argumenten: + +- PR-C maakt frontend-laag stabiel; geen overlap met layout-refactor +- WS-7 levert de Sentry-compatible exception-capture die Zod parse-failures schoon vangt + voor monitoring na rollout +- RFC-FORM-BUILDER-UI introduceert een grote nieuwe set composables; die landen op het + gevalideerde patroon vanaf de eerste commit i.p.v. retrofit later + +**Geschatte inspanning:** 2–3 dagen voor conventie + reference-implementatie + ~5 +hoge-prioriteit endpoints (`/auth/me`, form-builder list-endpoints, identity-match endpoints). +Verdere composable-uitrol gebeurt organisch als features worden geraakt of toegevoegd. + +**Out of scope:** form-input validatie (al via VeeValidate + Zod), WebSocket-validatie +(separaat, COMM-01), publieke API-contracten voor third parties (separaat, DIFF-03). + +**Open beslissingen:** codegen toolchain (Scramble-pipeline vs hand-rolled), validation +failure-mode (hard fail vs soft fail per env), per-route opt-out, boundary placement +(composable-laag vs axios-interceptor vs dedicated middleware). + +**Prioriteit:** Hoog — foundation-investering die voorkomt dat S3b technische schuld stapelt. +Niet blokkerend voor lopend werk. + +**Refs:** `dev-docs/ARCH-API-VALIDATION.md` (skeleton), AUTH_ARCHITECTURE.md (eerste +consumer), ARCH-FORM-BUILDER.md (high-priority migratie target), ARCH-BINDINGS.md +(status-fields zijn early-validation kandidaten), DOC-01 (Scramble pipeline kan codegen +voeden). + --- _Laatste update: April 2026_