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

+11 -4
View File
@@ -50,10 +50,11 @@ Product roadmap (owner, 2026-10-25): P0 docs, then V1-1 clients and animals, V1-
V1-3 cloud bilans, V1-4 stored PDF and sharing, V1-5 mobile and accessibility pass V1-3 cloud bilans, V1-4 stored PDF and sharing, V1-5 mobile and accessibility pass
(`docs/development/IMPLEMENTATION_PLAN.md` §0; V1-1 contract `docs/development/V1-1_OWNERS_ANIMALS.md`: (`docs/development/IMPLEMENTATION_PLAN.md` §0; V1-1 contract `docs/development/V1-1_OWNERS_ANIMALS.md`:
business decisions ratified 2026-10-25, BDR-073; architecture and N1-N9 validated, BDR-074; on business decisions ratified 2026-10-25, BDR-073; architecture and N1-N9 validated, BDR-074; on
`feature/v1-1-clients-animals` V1-1.1 to V1-1.3 (validated) and V1-1.4 are built: migrations `20261025100000_workspaces.sql`, `feature/v1-1-clients-animals` V1-1.1 to V1-1.4 (validated) and V1-1.5 are built: migrations `20261025100000_workspaces.sql`,
`20261025110000_clients.sql` and `20261026100000_animals_relations.sql` (contract §8.3), tested on PGlite and the isolated stack `20261025110000_clients.sql` and `20261026100000_animals_relations.sql` (contract §8.3), tested on PGlite and the isolated stack
`pnpm db:sandbox`, not applied to Supabase DEV; V1-1.3 the native modal dialog (D13) and the Playwright + axe suites `pnpm db:sandbox`, not applied to Supabase DEV; V1-1.3 the native modal dialog (D13) and the Playwright + axe suites
(D14, `docs/development/BROWSER_TESTS.md`); no client or animal screen yet). (D14, `docs/development/BROWSER_TESTS.md`); V1-1.5 the client screens (`/app/clients`, contract §11.7) on the
isolated stack; no animal screen yet).
--- ---
@@ -223,7 +224,9 @@ faunosteo/
│ │ ├─ routes/{Home,NewReport,Editor,NotFound}Route.tsx │ │ ├─ routes/{Home,NewReport,Editor,NotFound}Route.tsx
│ │ ├─ routes/auth/{Login,Signup,ForgotPassword,ResetPassword,AuthCallback}Route.tsx │ │ ├─ routes/auth/{Login,Signup,ForgotPassword,ResetPassword,AuthCallback}Route.tsx
│ │ ├─ routes/app/{Dashboard,Account}Route.tsx ← behind RequireAuth, inside AppLayout │ │ ├─ routes/app/{Dashboard,Account}Route.tsx ← behind RequireAuth, inside AppLayout
│ │ ├─ guards/{RequireAuth,RedirectIfSignedIn,SessionLoading}.tsx │ │ ├─ routes/app/clients/{ClientsList,ClientCreate,ClientDetail,ClientEdit}Route.tsx ← V1-1.5, behind RequireWorkspace
│ │ ├─ guards/{RequireAuth,RedirectIfSignedIn,SessionLoading,RequireWorkspace}.tsx ← RequireWorkspace: personal workspace ready, remount per workspace
│ │ ├─ useLeaveGuard.ts + usePageHeading.ts ← unsaved changes (beforeunload + in-app links via AppLayout); heading focus on page open
│ │ └─ providers/{ConfigProvider,AuthProvider}.tsx ← AppConfig context; session + locale sync start │ │ └─ providers/{ConfigProvider,AuthProvider}.tsx ← AppConfig context; session + locale sync start
│ ├─ auth/{validation,redirects,useAuthFailureMessage}.ts ← Zod schemas (i18n keys), safe next path, failure phrasing │ ├─ auth/{validation,redirects,useAuthFailureMessage}.ts ← Zod schemas (i18n keys), safe next path, failure phrasing
│ ├─ account/{validation,useProfileForm}.ts ← account section schemas + one-save form hook │ ├─ account/{validation,useProfileForm}.ts ← account section schemas + one-save form hook
@@ -239,10 +242,12 @@ faunosteo/
│ │ ├─ index.ts ← getDict(locale) │ │ ├─ index.ts ← getDict(locale)
│ │ └─ useT.ts ← useT() hook (reads localeStore) │ │ └─ useT.ts ← useT() hook (reads localeStore)
│ ├─ state/ │ ├─ state/
│ │ ├─ authStore.ts ← session, user, profile, roles, recovery flag (onAuthStateChange) │ │ ├─ authStore.ts ← session, user, profile, roles, recovery flag, personal workspace state (onAuthStateChange; reset on account change)
│ │ ├─ leaveGuardStore.ts ← armed while a page holds unsaved changes
│ │ ├─ reportStore.ts ← Zustand store (Report v3, core-built reports, actions answer { ok }) + persistence.ts (raw texts, quarantine keys) │ │ ├─ reportStore.ts ← Zustand store (Report v3, core-built reports, actions answer { ok }) + persistence.ts (raw texts, quarantine keys)
│ │ ├─ localeStore.ts ← locale Zustand store (persisted to localStorage) │ │ ├─ localeStore.ts ← locale Zustand store (persisted to localStorage)
│ │ └─ practitionerCache.ts ← localStorage prefill │ │ └─ practitionerCache.ts ← localStorage prefill
│ ├─ clients/{validation,countries,useClientForm,useClientList,useClientRecord}.ts ← client form schema on field-limits (D-R7), ISO list, page-local hooks
│ ├─ anatomy/drawing.ts ← the core's composed view (`view.canvas`) → DOMParser → importNode (R3; no sanitiser here) │ ├─ anatomy/drawing.ts ← the core's composed view (`view.canvas`) → DOMParser → importNode (R3; no sanitiser here)
│ ├─ components/ │ ├─ components/
│ │ ├─ ui/{Button,ButtonLink,Card,Dialog,ModalDialog,Input,Label,Select,Textarea,Badge,Chip,Icon,FormField,Notice}.tsx ← ModalDialog: native <dialog> showModal (D13), Dialog and MobileDrawer on it │ │ ├─ ui/{Button,ButtonLink,Card,Dialog,ModalDialog,Input,Label,Select,Textarea,Badge,Chip,Icon,FormField,Notice}.tsx ← ModalDialog: native <dialog> showModal (D13), Dialog and MobileDrawer on it
@@ -254,6 +259,7 @@ faunosteo/
│ │ │ ConclusionPanel,NextAppointmentPicker,CoreUnavailable,HeldSessionPanel,ReplaceSessionDialog}.tsx │ │ │ ConclusionPanel,NextAppointmentPicker,CoreUnavailable,HeldSessionPanel,ReplaceSessionDialog}.tsx
│ │ ├─ brand/{Brand,AppHeader,Footer,LanguageSwitcher,HomeSpaceLink}.tsx │ │ ├─ brand/{Brand,AppHeader,Footer,LanguageSwitcher,HomeSpaceLink}.tsx
│ │ ├─ auth/{AuthLayout,OAuthButtons,PasswordField,UnavailableNotice,AuthLink}.tsx │ │ ├─ auth/{AuthLayout,OAuthButtons,PasswordField,UnavailableNotice,AuthLink}.tsx
│ │ ├─ clients/{ClientForm,ClientAnimals,ArchiveClientDialog,ClientNotFound}.tsx
│ │ ├─ shell/{AppLayout,SidebarNav,MobileDrawer,UserBadge,SignOutButton}.tsx │ │ ├─ shell/{AppLayout,SidebarNav,MobileDrawer,UserBadge,SignOutButton}.tsx
│ │ └─ account/{SectionCard,SaveRow,AvatarSection,PersonalInfoForm,ProfessionalInfoForm,PreferencesForm,SecurityPanel,RoleBadges}.tsx │ │ └─ account/{SectionCard,SaveRow,AvatarSection,PersonalInfoForm,ProfessionalInfoForm,PreferencesForm,SecurityPanel,RoleBadges}.tsx
│ ├─ account/avatarTransport.ts ← magic-byte sniff (never SVG), createImageBitmap → canvas ≤ 1024 px → JPEG transport blob │ ├─ account/avatarTransport.ts ← magic-byte sniff (never SVG), createImageBitmap → canvas ≤ 1024 px → JPEG transport blob
@@ -283,6 +289,7 @@ faunosteo/
│ (packages/domain and packages/anatomy deleted at R5.7: their sources resolve at 756b7ef, crates/core/tests/curation/{FILES,LEDGER}.tsv) │ (packages/domain and packages/anatomy deleted at R5.7: their sources resolve at 756b7ef, crates/core/tests/curation/{FILES,LEDGER}.tsv)
├─ packages/supabase/ ← @faunosteo/supabase ├─ packages/supabase/ ← @faunosteo/supabase
│ ├─ src/{index,client,database.types,anatomical-sheets,assets}.ts ← typed client, generated types, publish gate, avatar flow (closed AssetFailure kinds) │ ├─ src/{index,client,database.types,anatomical-sheets,assets}.ts ← typed client, generated types, publish gate, avatar flow (closed AssetFailure kinds)
│ ├─ src/{records,workspaces,clients,species,field-limits}.ts ← V1-1 record access (closed RecordFailure kinds, keyset pages), D-R7 bounds
│ ├─ tests/e2e/avatar-flow.e2e.ts + vitest.e2e.config.ts ← real-stack end-to-end (`pnpm e2e:avatar`), skipped without the stack env │ ├─ tests/e2e/avatar-flow.e2e.ts + vitest.e2e.config.ts ← real-stack end-to-end (`pnpm e2e:avatar`), skipped without the stack env
│ └─ tests/{client,anatomical-sheets}.test.ts, tests/db/ ← PGlite harness, shim, pgTAP runner, schema↔types test │ └─ tests/{client,anatomical-sheets}.test.ts, tests/db/ ← PGlite harness, shim, pgTAP runner, schema↔types test
├─ supabase/ ├─ supabase/
+1 -1
View File
@@ -30,7 +30,7 @@ step has built yet, with the step that owns them:
| Element | Owner | | Element | Owner |
|---|---| |---|---|
| Clients and Animaux entries and screens | roadmap V1-1 (plan Step 12 reduced, `docs/development/V1-1_OWNERS_ANIMALS.md`) | | Clients and Animaux entries and screens | roadmap V1-1 (plan Step 12 reduced, `docs/development/V1-1_OWNERS_ANIMALS.md`). Clients built in V1-1.5 (2026-10-26): the entry in the sidebar and the drawer after Tableau de bord, the screens on the existing cards, fields, badges and buttons (the mockup draws no client screen); Animaux with V1-1.6 |
| Fiches anatomiques entry and screen | roadmap V1-2 (plan Step 13 reduced) | | Fiches anatomiques entry and screen | roadmap V1-2 (plan Step 13 reduced) |
| Bilans entry and screens | roadmap V1-3 (plan Step 14) | | Bilans entry and screens | roadmap V1-3 (plan Step 14) |
| Agenda entry and screens | plan Step 20 | | Agenda entry and screens | plan Step 20 |
@@ -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 (`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), 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`). 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 ## 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 either (D9a): in DEV, delete its relations, animals and clients first from a
privileged SQL session, in that order. 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 ## 4. Writing a migration
1. `pnpm supabase migration new <name>` creates `supabase/migrations/<timestamp>_<name>.sql`. 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 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, caught (`V1-1_OWNERS_ANIMALS.md` §8.3). The axe exceptions match rule,
selector, markup and route. 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 ## 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 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 (§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 (`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: Branch: `feature/v1-1-clients-animals`. Roadmap position:
`IMPLEMENTATION_PLAN.md` §0; this step is a reduced plan Step 12 that also lays `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 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 | | 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 | | 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 ## 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.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.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.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.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 | | 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 | | 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 Recommended first step: V1-1.1. It is SQL only, has no visible choice, and