From ae0bd3f8d84bf9c40c9d9f0879022eeac5b977cc Mon Sep 17 00:00:00 2001 From: bchanot Date: Mon, 26 Oct 2026 02:01:55 +0100 Subject: [PATCH] docs(docs): V1-1.5 clients screens as built, owner choices, tests MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- CLAUDE.md | 15 ++++++-- docs/design/README.md | 2 +- docs/development/FRONTEND_ARCHITECTURE.md | 6 +++ docs/development/SUPABASE.md | 5 +++ docs/development/TEST_STRATEGY.md | 5 +++ docs/development/V1-1_OWNERS_ANIMALS.md | 45 +++++++++++++++++++++-- 6 files changed, 70 insertions(+), 8 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 622743f8..b5dfef52 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 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/ diff --git a/docs/design/README.md b/docs/design/README.md index 1cce98d6..ffdaa84a 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -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 | diff --git a/docs/development/FRONTEND_ARCHITECTURE.md b/docs/development/FRONTEND_ARCHITECTURE.md index 904a78cc..bd7a7631 100644 --- a/docs/development/FRONTEND_ARCHITECTURE.md +++ b/docs/development/FRONTEND_ARCHITECTURE.md @@ -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 `` 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 diff --git a/docs/development/SUPABASE.md b/docs/development/SUPABASE.md index a0f8dc9f..6ccc5ff9 100644 --- a/docs/development/SUPABASE.md +++ b/docs/development/SUPABASE.md @@ -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 ` creates `supabase/migrations/_.sql`. diff --git a/docs/development/TEST_STRATEGY.md b/docs/development/TEST_STRATEGY.md index 6c939362..d3d6bcef 100644 --- a/docs/development/TEST_STRATEGY.md +++ b/docs/development/TEST_STRATEGY.md @@ -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 diff --git a/docs/development/V1-1_OWNERS_ANIMALS.md b/docs/development/V1-1_OWNERS_ANIMALS.md index 3624e908..e8c4001d 100644 --- a/docs/development/V1-1_OWNERS_ANIMALS.md +++ b/docs/development/V1-1_OWNERS_ANIMALS.md @@ -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