docs(docs): V1-1.5 clients screens as built, owner choices, tests

Contract §11.7 (U1, U2, animals read-only, first-animal section deferred;
access layer, workspace state, routes, form, page, leave guard, focus,
deviations, counts), FRONTEND_ARCHITECTURE note, design README owners row,
TEST_STRATEGY, SUPABASE.md access layer and DEV note, CLAUDE.md map.
This commit is contained in:
bchanot committed 2026-10-26 02:01:55 +01:00
1 parent db81928dfa
commit ae0bd3f8d8
6 files changed
+70 -8

No files matched your search

@@ -13,6 +13,12 @@ architecture) is the current description. V1-1.3 (2026-10-25): every modal
(`Dialog`, the mobile drawer) is built on `components/ui/ModalDialog.tsx`, the
native `<dialog>` in modal mode (behaviour in `V1-1_OWNERS_ANIMALS.md` §11.6),
and the real-browser suites live in `apps/app/e2e` (`BROWSER_TESTS.md`).
V1-1.5 (2026-10-26): the first record screens, the clients
(`V1-1_OWNERS_ANIMALS.md` §11.7): data access only through
`packages/supabase` (closed `RecordFailure` kinds), page-local state in hooks
under `apps/app/src/clients/`, the personal workspace in `authStore`, the
routes behind `RequireWorkspace`, unsaved changes guarded by `useLeaveGuard`
and `AppLayout`. No data cache library: each page reads what it shows.
## 1. Starting point
+5
View File
@@ -315,6 +315,11 @@ M2. An account whose workspace holds an animal can no longer be deleted
either (D9a): in DEV, delete its relations, animals and clients first from a
privileged SQL session, in that order.
The browser reaches these tables through `packages/supabase/src/{workspaces,clients,species,records}.ts`
since V1-1.5 (contract §11.7). The client screens run against DEV only once
the owner has applied M1 to M3 with §3.3; until then they are developed and
tested on the isolated stack, and no DEV acceptance is recorded.
## 4. Writing a migration
1. `pnpm supabase migration new <name>` creates `supabase/migrations/<timestamp>_<name>.sql`.
+5
View File
@@ -34,6 +34,11 @@ shared budget under concurrency, D9a through GoTrue admin, read timings on
20 000 animals), run in four migration states; 14 deliberate faults of M3
caught (`V1-1_OWNERS_ANIMALS.md` §8.3). The axe exceptions match rule,
selector, markup and route.
V1-1.5 (2026-10-26): supabase vitest 92 (access layer 33); sandbox suites 54
(`clients-access.sandbox.ts` 8: the access layer through supabase-js against
real GoTrue and PostgREST); app vitest 508 (client screens 22, form schema 20,
workspace and account change 6); `e2e:shell` 42 (client journeys 36, FR/EN,
desktop and 375 px, axe). The shell suite keeps no HTML report.
## 1. Layers
+42 -3
View File
@@ -13,7 +13,10 @@ authorised V1-1.2. V1-1.2 and V1-1.3 were validated on 2026-10-25 and
Animaux et relations », BDR-077), which authorised V1-1.4. Migrations M1
(§8.1), M2 (§8.2) and M3 (§8.3) are written and tested on the isolated stack
(`pnpm db:sandbox`, SUPABASE.md §5.1); none is applied to Supabase DEV (owner
procedure: SUPABASE.md §3.3). Nothing of V1-1.5 and V1-1.6 exists.
procedure: SUPABASE.md §3.3). V1-1.4 was validated on 2026-10-26 (brief
« Validation V1-1.4 et autorisation V1-1.5 Interface Clients »), which
authorised the client screens of V1-1.5 (§11.7), built and tested on the
isolated stack. Nothing of V1-1.6 exists.
Branch: `feature/v1-1-clients-animals`. Roadmap position:
`IMPLEMENTATION_PLAN.md` §0; this step is a reduced plan Step 12 that also lays
the permission frame of Step 10. The file name keeps "OWNERS" so the documents
@@ -1261,6 +1264,42 @@ validated mockups unchanged).
| The mockup's bar now | Bilans and Agenda lead nowhere until V1-3 and later (hidden or disabled tabs); Clients and Animaux stay in the drawer anyway; a fixed bottom bar competes with the save action that §11.4 keeps reachable with the keyboard open |
| A bar adapted to V1-1 (Accueil, Clients, Animaux, Profil) | one tap to the V1-1 screens; departs from the validated mockup, so it needs a new validated design file first; the bar changes again when Bilans and Agenda arrive |
### 11.7 V1-1.5 as built (2026-10-26)
Owner choices of 2026-10-26, asked before the screens: U1 « Afficher plus »
(keyset pages of 25, no numbered page), U2 one « Afficher les archivés »
toggle, the client page shows its animals read-only (no link, no « ajouter »
until the animal screens), the « Ajouter un premier animal » section of
`/app/clients/new` moves to V1-1.6 with the animal screens.
| Part | As built |
|---|---|
| Access layer | `packages/supabase/src/workspaces.ts` (`fetchPersonalWorkspaceId`), `clients.ts` (search with one probe row for « Afficher plus », read by id with an explicit column list and no request for an id that is not a uuid, create with a request id, update sending every field, archive, client animals, archive preview), `species.ts` (labels), `records.ts`: the closed kinds of §9.4 plus `session_expired` (HTTP 401, PGRST30x) and `network` (no answer); every RPC answer checked by Zod. Proven by unit tests and by `tests/sandbox/clients-access.sandbox.ts`, the same functions through supabase-js against the sandbox's real GoTrue and PostgREST |
| Personal workspace | read by `state/authStore.ts` with the account: `loading`, `ready`, `inactive` (profile deactivated), `unconfirmed` (no confirmed email), `missing`, `error`; never created in the browser. A change of account drops profile, roles, avatar and workspace in the same update, and an answer that arrives for the previous account is ignored. `app/guards/RequireWorkspace.tsx` renders the client routes only when ready and remounts them per workspace |
| Routes | `/app/clients`, `/app/clients/new`, `/app/clients/:clientId`, `/app/clients/:clientId/edit` (`app/routes/app/clients/`); an unknown, foreign or malformed id shows the same « Client introuvable » inside the shell |
| List | search sent after 300 ms without typing (POST, the term never in a URL), the archived toggle, rows with kind, city, phone and `current_animal_count`, « Afficher plus », loading, empty, no-result, error and retry states, the row count announced |
| Form | `clients/validation.ts` on `field-limits.ts` (D-R7: code points, control ranges, email pattern, ISO country list); the phone entry rule of §11.3, shown converted when the field is left; « Personne » checked, the name label follows the kind, required and optional marked in the labels, the first error focused; one request id per creation intent, sent again on a retry; on `conflict` the stored values appear under the fields that differ, the typed ones stay, the next save applies them knowingly; submit guarded against double clicks; the save bar stays reachable at the bottom on a phone |
| Page | identity, kind and archived badges, phone as `tel:`, email as `mailto:`, address and country name, the animals read-only (current then former, role, dates when known, species name); archive through a confirmation listing the active animals for which the client is the only current owner (it refuses to close while the request runs), restore by one button, outcomes announced |
| Leave guard | `useLeaveGuard`: `beforeunload` while the form holds changes, and `AppLayout` asks before following any in-app link (sidebar, drawer, top bar, the form's own « Annuler »); the browser's back and forward buttons are not intercepted (declarative router, §11.3) |
| Navigation | « Clients » in the sidebar and the drawer after « Tableau de bord » (the validated mockup's order); no tab bar (D11 unchanged) |
| Focus | each client page focuses its heading when it opens, also when opened from the drawer (after the drawer closed and returned focus) |
Deviations and limits: the contract's `beforeunload` plus Cancel guard is
extended to every in-app link; the search term and the archived toggle are not
kept when returning from a client page (no storage of terms); phones show in
E.164 as stored; the dashboard tiles (D12) are not built. The shell's top bar
already carried an `h1` with the page title on large screens before V1-1.5;
the client pages add their own `h1` in `main`, as the existing pages do.
Tests: supabase vitest 92 (access layer 33), sandbox suites 54 (access layer
8); app vitest 508 (client screens 22, form schema 20, store 15); Chromium
`e2e:shell` 42 (client journeys 36: create, search, edit, archive, archived
filter, restore, pages, keyboard only, two accounts, concurrent edit, retry
after a lost answer, network failures, leave guard, change of language; FR
and EN, desktop and 375 px, axe on every state with no exception of RR-7
inherited). Report check: the shell suite's HTML report kept the typed
passwords of its throwaway accounts; it was removed (`BROWSER_TESTS.md` §3).
---
## 12. Tests and Definition of Done
@@ -1446,8 +1485,8 @@ validates after V1-1.1 and after the first UI step; nothing merges into
| V1-1.1 | Workspaces: M1 (with the correlation header cap), helpers, trigger, backfill, RLS, pgTAP `012`. Written and tested on an isolated stack (§8.1), validated 2026-10-25; not applied to DEV |
| V1-1.2 | Clients data: M2, RPCs, searches, D15 guards (budget per workspace, its lock), N9 audit policy, field limits and parity test, sandbox suite. Written and tested on the isolated stack (§8.2), validated 2026-10-25; not applied to DEV |
| V1-1.3 | UI foundations: Playwright Chromium and axe (D14), `Dialog` containment and restore (D13). Built (§11.6), validated 2026-10-26 |
| V1-1.4 | Animals and relations data: M3 with the species rows, RPCs, history rules, D9a proof. Written and tested on the isolated stack (§8.3), awaiting the owner's checkpoint; not applied to DEV |
| V1-1.5 | Clients UI: routes, forms, list and search, archive, navigation entry |
| V1-1.4 | Animals and relations data: M3 with the species rows, RPCs, history rules, D9a proof. Written and tested on the isolated stack (§8.3), validated 2026-10-26; not applied to DEV |
| V1-1.5 | Clients UI: routes, forms, list and search, archive, navigation entry. Built and tested on the isolated stack (§11.7), awaiting the owner's checkpoint; the owner's check over the LAN needs M1 to M3 on DEV |
| V1-1.6 | Animals and relations UI, navigation (D11), dashboard tiles (D12), documents, Definition of Done |
Recommended first step: V1-1.1. It is SQL only, has no visible choice, and