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
(`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
`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
`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/auth/{Login,Signup,ForgotPassword,ResetPassword,AuthCallback}Route.tsx
│ │ ├─ 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
│ ├─ 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
@@ -239,10 +242,12 @@ faunosteo/
│ │ ├─ index.ts ← getDict(locale)
│ │ └─ useT.ts ← useT() hook (reads localeStore)
│ ├─ 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)
│ │ ├─ localeStore.ts ← locale Zustand store (persisted to localStorage)
│ │ └─ 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)
│ ├─ 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
@@ -254,6 +259,7 @@ faunosteo/
│ │ │ ConclusionPanel,NextAppointmentPicker,CoreUnavailable,HeldSessionPanel,ReplaceSessionDialog}.tsx
│ │ ├─ brand/{Brand,AppHeader,Footer,LanguageSwitcher,HomeSpaceLink}.tsx
│ │ ├─ auth/{AuthLayout,OAuthButtons,PasswordField,UnavailableNotice,AuthLink}.tsx
│ │ ├─ clients/{ClientForm,ClientAnimals,ArchiveClientDialog,ClientNotFound}.tsx
│ │ ├─ shell/{AppLayout,SidebarNav,MobileDrawer,UserBadge,SignOutButton}.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
@@ -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/supabase/ ← @faunosteo/supabase
│ ├─ 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/{client,anatomical-sheets}.test.ts, tests/db/ ← PGlite harness, shim, pgTAP runner, schema↔types test
├─ supabase/
+1 -1
View File
@@ -30,7 +30,7 @@ step has built yet, with the step that owns them:
| 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) |
| Bilans entry and screens | roadmap V1-3 (plan Step 14) |
| 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
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