Files
faunosteo/docs/development/V1-1_OWNERS_ANIMALS.md
T
bchanot c71fafa3c5 docs(docs): add V1-1 clients and animals contract
Functional contract for roadmap item V1-1 with the owner's orientations
of 2026-10-25 recorded as proposals awaiting ratification (D1-D9, D16,
C4-C6), their SQL and permission impact, the sub-choices they leave and
the decisions still open. No migration, table, RPC or component.
2026-10-25 17:12:30 +01:00

30 KiB
Raw Blame History

V1-1 Clients and animals: functional contract

Status: proposal, 2026-10-25, revised the same day with the owner's orientations (brief « P0 : arbitrages documentaires et finalisation du contrat V1-1 »). Nothing is implemented and nothing is authorised: no migration, table, RPC, RLS policy, component or route exists or may be created for this step until the owner ratifies the orientations of §9.1 and answers §9.2. The orientations are recorded as proposed, not ratified. 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 that cite it keep working.

Part 1 states the facts. Parts 2 to 7 are the proposed contract. Part 8 lists the tests and the Definition of Done. Part 9 lists the orientations, the sub-choices they leave, and the decisions still open.


1. Facts the contract rests on

Area State on develop (0c54e4b)
Client and animal data Text inside a bilan only: report v3 owner = { name }, animal = { speciesId, name, breed?, age? } (crates/core/src/domain/report/identity.rs). No table.
Species public.species (id slug, name_fr, name_en, sort_order, active), one row equine / Cheval / Horse; SELECT for authenticated on active rows; no API write path.
Anatomical sheets Only the equine DRAFT exists, unpublished until business review (BDR-034, BDR-037). Its content changes only through curation/changes.json and the Rust pipeline until plan Step 17 (owner, 2026-10-25).
Accounts Email/password sign-up, enable_confirmations = true (no session before the email is confirmed), profiles.active switched by staff only, private.require_actor() refuses a missing or deactivated actor.
Roles platform_role = owner, admin, moderator, support (BDR-026). No professional status and no cabinet table exist.
Audit audit.audit_logs append-only, written by private.log_event(), action format domain.verb.
Files client-files and animal-files buckets exist, closed (row only, no policy).
UI /app shell (sidebar, drawer, top bar), Dashboard, Account. The validated mockup (docs/design/) shows Clients and Animaux sidebar entries and a mobile tab bar Accueil / Bilans / Agenda / Profil. The shared Dialog has no focus trap or focus restore (RR-7).
Form validation D-R7: form constraints stay TypeScript (Zod schemas returning i18n keys); a constants module is checked against pg_constraint by a PGlite test. The SQL CHECK is the server boundary. The 2026-10-25 inventory put V1-1 validation in crates/core: that contradicted D-R7 and is withdrawn here (EVAL-034).
Tests pgTAP on PGlite and on the real stack; real-stack e2e pattern in packages/supabase/tests/e2e; no real-browser test runner in the repository (RR-8).

2. Scope

In V1-1, a signed-in practitioner with a confirmed email:

  1. creates, edits, lists, searches, archives and restores clients, persons and organisations;
  2. creates, edits, lists, searches, archives and restores animals, each linked to zero, one or several clients with a role per link;
  3. sees a client's animals and an animal's clients, current and former;
  4. does all of it on a phone (375 px wide) and on a computer, in French and English, with the keyboard alone and with a screen reader.

Out of scope, each named so nobody builds it early: cabinet creation and membership management, sharing between practitioners, client portal and client accounts, any directory or matching across practitioners, consent records, photos, weight and files, imports (CSV, PDF), notifications, any link with bilans (V1-3), account closure, deletion, anonymisation and export (D9), quotas and billing, the professional verification process (plan Step 9), any staff access to the records (D16), any editing of the anatomical reference. The local tool and the bilan format do not change; annotating a bilan never changes curation/changes.json.


3. Workspaces and the future cabinets (D2, C4)

Orientation D2 / C4: records belong to a workspace. In V1-1 each practitioner has one personal workspace. There is no global directory of clients shared between practitioners. Multi-practitioner cabinets come later and are not built in V1-1.

Table V1-1 content Later
workspaces id, kind (personal only), created_at; one personal workspace per profile, created with the profile (trigger + backfill of existing profiles) kind = cabinet, name, logo: the plan's Step 10 builds cabinets as workspaces instead of a separate organizations table
workspace_members workspace_id, user_id, role (owner only) roles manager, practitioner, secretary added with the cabinet step

One helper answers every access question: the caller's role in a workspace, null when the caller is not a member or the profile is inactive. Policies and RPCs never test user_id = auth.uid() on the record itself, so the cabinet step adds members, not new policies on every table.

Why not a plain owner_user_id column: it is simpler today, but every policy and helper of clients, animals and later bilans would need a second branch for cabinets, and moving a practitioner's records into a cabinet would rewrite ownership columns. The workspace costs two small tables now.

Record placement is explicit: the browser sends the target workspace on create and the server checks the caller's role in it. In V1-1 the app always sends the personal workspace.


4. Entities and fields

Vocabulary (orientation D1): the interface says « Clients » (English "Clients") and the code entity is clients. A client is the person or the structure the practitioner deals with. Its relation to an animal carries a role: owner (Propriétaire), keeper (Détenteur, for example the stable that boards the horse) or contact (Contact). The entity and the role are never merged: the same client can own one horse and keep another.

4.1 Client

Field Rule Required
kind person (personne physique) or organisation (structure: écurie, haras, association, entreprise or another legal entity); defaults to person column always set, nothing to type (D3)
display_name person: the name as the practitioner writes it (« Marie Dupont »); organisation: its name (« Écurie du Lac »); 1 to 120 characters yes, the only required input (D4)
email practical address format, at most 254 characters, stored lower-case no
phone E.164 like profiles.phone; French national input (06 12 34 56 78) normalised to +33… on submit no
address_line1, address_line2, postal_code, city at most 120 / 120 / 16 / 80 characters, no postal format check (Belgium, Switzerland) no
country ISO 3166-1 alpha-2; no SQL default, the form proposes France no
notes private to the workspace, at most 4 000 characters no
archived_at, archived_by set by the archive RPC only n/a

Every text field is trimmed, refuses control characters and is never empty when present. No uniqueness on email or phone: two clients may share a household address or phone. Contact details are optional at creation (D4): what a booking, an invoice or a regulated document requires is set by the step that introduces it, never by a NOT NULL here.

4.2 Animal

Field Rule Required
species_id an active row of species (§4.4) yes (D5)
species_detail free text, 1 to 80 characters, required with other and refused with any other species if other (D5)
name 1 to 80 characters yes (D6)
sex male, female, unknown; defaults to unknown column always set, nothing to type (D6)
breed free text, at most 80 characters (no breed list in V1-1) no
birth_year four-digit year, not in the future no
birth_date the full date, only when it is known; not in the future; when present, birth_year equals its year (CHECK) no
neutered yes, no, unknown; together with sex it gives stallion, gelding, mare in the equine UI no, proposal (D6a)
identification microchip, UELN, tattoo: at most 64 characters, letters, digits, spaces and hyphens, stored upper-case; no per-species format check no, proposal (D6a)
colour at most 80 characters no, proposal (D6a)
notes private to the workspace, at most 4 000 characters no, proposal (D6a)
deceased_on date not in the future; a deceased animal stays readable and is never archived implicitly no, proposal (D6a)
archived_at, archived_by archive RPC only n/a

A year alone never becomes a date: an animal born « in 2015 » has birth_year = 2015 and no birth_date, never a stored 1 January (D6, D6b). Deferred to a later step (D6): weight (it belongs to a visit, not to the animal) and photo (it needs the animal-files rules and a worker job). The fields marked « proposal » go beyond the owner's list of 2026-10-25; the owner keeps or drops each before the migration (D6a).

4.3 Client and animal relation

Table animal_clients (orientation D7): animal_id, client_id, role (owner, keeper, contact), created_at, ended_at. Rules:

  • many-to-many: an animal links to several clients and a client to several animals, each link with its role; co-ownership is several owner links, and owner and keeper are distinct links;
  • client and animal belong to the same workspace (composite foreign keys on (workspace_id, id));
  • one current row per (animal, client, role) (partial unique index on rows with no ended_at);
  • no owner is required: an animal may have no current owner link, because the owner is unknown or not entered yet. No SQL constraint and no RPC refuses it, and the app never creates a placeholder client; it shows « Propriétaire non renseigné ». Whether a business operation (bilan, invoice, sharing) later requires an owner is decided by the step that introduces the operation;
  • ending a relation (horse sold, keeper changed) sets ended_at; the row stays as history and the former owner or keeper is shown as such (D7a, historical relations kept under D8).

4.4 Species

The species list is reference data written by migration (orientation D5): the nine species of this contract's first version, horse (the existing row equine), donkey, dog, cat, cattle, goat, sheep, pig and rabbit, plus « Autre » (other) with its required species_detail. No other species is added. The slugs of the new rows follow the format of the equine row and are fixed with the migration.

A species carries no anatomical sheet by itself: an animal of any listed species can be recorded while no usable sheet exists for it (today only the equine draft exists), and nothing links a species to a sheet automatically. V1-1 shows no sheet information; V1-3 decides what a bilan does for an animal whose species has no sheet.


5. Permissions

5.1 Matrix

Actor Read Create Edit Archive / restore Delete
Workspace member with role owner (V1-1: the practitioner in their personal workspace) yes yes yes, active records only yes no (§6)
Future cabinet roles manager, practitioner, secretary per the cabinet step per the cabinet step per the cabinet step per the cabinet step no
Another signed-in account no no no no no
Platform owner, admin, moderator, support no no no no no
Deactivated profile no no no no no
Anonymous no no no no no

Orientation C5: writes belong to the members who hold a write right in the workspace concerned. In V1-1 that is only the practitioner who owns the personal workspace. Future cabinets may add permissions (business architecture §2.2: a secretary manages customers and animals); the helper's shape allows them, and they are built with the cabinet step.

Orientation D16: Faunosteo staff have no ordinary business access to private records. No platform role (owner, admin, moderator, support) reads or writes clients, animals or bilans through a policy or an RPC, and no admin screen lists or opens them. That rule is distinct from exceptional privileged technical operations (database maintenance, backup restore, incident response through the service key or a database superuser): those exist by construction of the hosting, and before any publication a separate contract frames, justifies and audits them. V1-1 creates no exceptional access mechanism (no impersonation, no break-glass RPC), and no worker job reads these tables.

5.2 Verification (C6)

Orientation C6: email confirmation and professional verification are two distinct things. An account with a confirmed email has private use of the application, within the permissions and features available: V1-1 is open to any active account with a session (GoTrue gives no session before confirmation). Professional verification (plan Step 9; BDR-041 said Step 11, corrected by BDR-072) is required for the public features that present a practitioner as a verified professional (public profile, community publication, booking); it is not built in V1-1 and does not gate it. Professional statuses (practitioner, student, professor) come from verification and are never platform roles (BDR-026).

5.3 Edits and finished bilans (C5)

V1-1 holds no bilan. The rule binds V1-3: a bilan keeps its own identity snapshot (already true of the report v3 format); editing an animal or a client never rewrites a finished bilan, retroactively or silently. Any refresh of a draft bilan from the animal record is an explicit user action.

5.4 Server rules

  • Reads: SELECT policies on clients, animals, animal_clients, workspaces, workspace_members through the workspace helper, explicit column lists in the app (no select=*).
  • Writes: security-definer RPCs only (create, update, archive, restore, link, end a link). No INSERT, UPDATE or DELETE grant on these tables for API roles. Each RPC calls private.require_actor(), checks the role in the target workspace, answers the same 42501 for an unknown id and a forbidden id, and writes one log_event row with ids and changed field names, never names, contacts or notes.
  • Concurrency: update RPCs take the updated_at the form loaded and refuse a stale write with a closed conflict kind, so two tabs never overwrite each other silently.
  • Archived records are read-only until restored.
  • Helpers in private follow the project rule: security definer, set search_path = '', EXECUTE revoked from public, granted only where evaluated; census tests updated.

6. Archive, deletion and privacy

6.1 Archive (D8)

Archiving is a functional state, read-only and reversible. It hides a record from default lists and search, keeps it readable from its page and from the « archived » filter, and refuses edits until the record is restored. Restore is always possible. Relations are kept: an archived client stays on its animals' pages, marked archived. Archiving a client never archives its animals; the confirmation lists the active animals for which it is the only current owner.

Archiving erases nothing. It is not the deletion or anonymisation of personal data (§6.2), and no retention duration is attached to it.

6.2 Account deletion and the data lifecycle (D9)

V1-1 implements no account closure, deletion, anonymisation or export, and sets no retention duration. Orientation D9: no rule may block the deletion of an account for good because it holds data. A later lifecycle contract (plan Step 26, BDR-033 point 7) will distinguish closing the account, deleting or anonymising personal data, keeping some data where a justification exists, the records of a workspace shared by a cabinet, and the legal obligations that apply. The owner sets the retention durations and the erasure policy; nothing here presumes them.

What V1-1 does so that contract stays possible:

  • records belong to a workspace, never to a user column, so a cabinet's records survive a member leaving, and a personal workspace can be exported, anonymised or erased as one unit;
  • authorship columns (archived_by, audit rows) hold ids only, never names, so anonymising a profile rewrites no record;
  • a client's personal data sits in the identified columns of one table, with no copy in audit rows, logs or URLs, so erasure or anonymisation is a bounded update.

The one technical choice before the migration is how the database behaves when an auth user whose personal workspace holds records is deleted in DEV (D9a, §9.2).

To frame with legal counsel before any public exposure (business architecture §28); nothing here decides it:

  • likely roles: the practitioner or cabinet is the controller of client and animal records, Faunosteo its processor, which needs processor terms in the conditions of use;
  • the legal basis is not presumed to be consent. The likely basis for client identity and contact data is the care contract between practitioner and client and the practitioner's legal obligations (invoicing). Consent would apply to optional purposes only (marketing, sharing with another practitioner), none of which V1-1 implements;
  • clients must be informed (GDPR articles 13 and 14): the information text, and whether the app records that it was given, is decision D10. V1-1 shows nothing to clients;
  • retention durations belong to the lifecycle contract (§6.2);
  • minimisation: the field list of §4 is closed; the notes fields carry a hint to record only what the care needs;
  • no personal data in URLs (ids are uuids; the search term is never put in the query string), in audit rows or in application logs; search goes through a POST RPC so the term stays out of access logs.

7. Screens and journeys

Routes (English, like the existing /app/dashboard and /app/account):

Route Content
/app/clients list (name, kind, city, phone, animal count), search, archived filter, « new client »
/app/clients/new form; optional « add a first animal » section in the same flow
/app/clients/:clientId identity and contact, animals with their role (current and former), edit, archive or restore, add an animal
/app/animals list (name, species, breed, sex, owners or « Propriétaire non renseigné »), search, species and archived filters, « new animal »
/app/animals/new form with optional client selection or inline client creation; prefilled when opened from a client
/app/animals/:animalId identity, owners, keepers and contacts (current and former), edit, archive or restore

An unknown id and a forbidden id show the same « not found » screen.

Journeys:

  1. New client calling about a horse: Clients → new client → type the name, add the first animal in the same form → save → client page with the animal.
  2. Find an animal from a phone in a stable: Animaux → type part of the name or the identification → open the animal → see owners and keeper with the phone as a tel: link.
  3. Horse sold: animal page → add the new owner → end the old owner's relation → the old client stays, with its other animals, and appears as former owner on the horse's page.
  4. Owner unknown: a rider brings a horse without its owner's details → the animal is created with no client → its page and the list show « Propriétaire non renseigné », no placeholder client exists → the owner is added later.
  5. Client archived: the confirmation lists the animals for which it is the only current owner → archived → hidden from lists, visible under the archived filter, still shown on its animals' pages, restorable.
  6. Animal deceased, if deceased_on is kept (D6a): mark deceased with a date → the animal stays in lists with a « deceased » badge.

Desktop: the sidebar entries Clients and Animaux of the validated mockup become active; list and detail use the existing Card, FormField and Button components; no new visual direction. Mobile: single column, rows as cards with 44 px targets, forms as full pages (no modal form), save bar reachable with the keyboard open. The tab bar question is decision D11; dashboard tiles are decision D12.

Accessibility applied in V1-1, not deferred to V1-5: every field labelled, errors linked with aria-describedby and announced, focus moved to the first error on submit and to the page heading on navigation, visible focus, no action reachable only by pointer, confirmation dialogs with focus trap and focus restore (decision D13), an axe check per screen in the browser tests. Unsaved form changes ask before leaving. Failure kinds are closed and phrased by i18n (FR and EN), like the auth and asset failures.


8. Tests and Definition of Done

8.1 SQL (pgTAP, PGlite and real stack)

  • RLS enabled, no API write grant, explicit column grants; census tests (001, schema↔types) updated.
  • Allowed and denied per actor of §5.1: member reads and writes; second account, anonymous, deactivated account and each platform role read nothing and every RPC refuses with 42501; unknown id and forbidden id give the same error.
  • Every CHECK of §4 accepted at its bound and refused one step past it; a client with only a display name accepted; species_detail required with other and refused otherwise; a birth_date whose year differs from birth_year refused, a birth_year alone accepted.
  • Same-workspace link rule; an animal with no owner link accepted; a second current (animal, client, role) row refused; an ended relation kept and readable; archived records refuse edits; archiving a client leaves its animals and links unchanged; stale updated_at refused.
  • Audit rows written for each RPC, with no name, contact or note in them.
  • Personal workspace created for a new profile and backfilled for existing ones; the D9a behaviour as decided.

8.2 Cross-account on the real stack

An e2e file beside avatar-flow.e2e.ts: two users created through the admin API on the local stack; A creates a client and an animal; B lists (empty), reads by id (nothing), updates, archives, links (42501); the anon key reads nothing; A deactivated by SQL loses access. Run by pnpm script on the DEV origin.

8.3 Application

  • Unit and component tests: form schemas (each rule, i18n keys), list and search states (empty, results, error), archive and restore flow, conflict message, « Propriétaire non renseigné » state, route guard, i18n key parity.
  • Constraint parity test (D-R7): the TypeScript constants equal the SQL CHECK bounds read from pg_constraint on PGlite.

8.4 Real browsers

A Playwright suite under apps/app/e2e (decision D14: @playwright/test and @axe-core/playwright as dev dependencies), run against pnpm dev and the local stack on the DEV origin:

  • desktop Chromium, Firefox and WebKit; phone viewports 375 × 667 and 412 × 915;
  • journeys 1 to 6 of §7;
  • the creation journey with the keyboard only;
  • two browser contexts: B opens A's client URL and gets « not found »;
  • no client or animal name in any URL;
  • an axe scan on each screen, zero serious or critical violation.

Then the owner's manual check on a real phone and a computer over the LAN.

8.5 Definition of Done

All tests above green; pnpm check:all; pnpm db:reset && pnpm db:test; regenerated database.types.ts; fresh verifier and security gates; docs (a domain document for clients and animals, CLAUDE.md folder map and architecture, docs/design/README.md owners table); report format, PDF, sheets and local tool unchanged; nothing deployed, Supabase DEV untouched outside db:reset of the local stack.


9. Orientations and decisions

9.1 Owner orientations of 2026-10-25 (proposed, awaiting ratification)

All are needed before the first migration. « SQL » marks an orientation that fixes a table shape or a constraint, « permissions » one that fixes a policy or an RPC check.

Id Orientation Impact
D1 Interface term « Clients »; Propriétaire, Détenteur and Contact are roles of the relation to an animal; the client entity is never confused with its role SQL: table clients, link roles owner / keeper / contact
D2 / C4 workspaces and workspace_members; one personal workspace per practitioner in V1-1; records attached to a workspace; no global client directory; cabinets later, not built in V1-1 SQL and permissions: every policy and RPC goes through the workspace helper
D3 Persons and structures (écuries, haras, associations, entreprises, other legal entities), with an explicit distinction in the model SQL: kind column and CHECK
D4 The display name or company name is the only required field; contact details optional at creation; later steps set their own requirements SQL: one required column; no NOT NULL on contact columns
D5 The nine species of this contract plus « Autre » with a detail; no new species; no automatic sheet per species; a species may exist with no usable sheet SQL: reference rows by migration; species_detail CHECK
D6 Name and species required; sex with unknown; breed optional; birth year optional; a full date when known, never invented from a year; weight and photo deferred SQL: sex CHECK and default; birth_year / birth_date coherence CHECK
D7 Many-to-many relation with an explicit role per link; co-ownership; owner unknown or not entered allowed with no fake client; no SQL rule forcing an owner while that is undecided SQL: link table with no minimum-owner constraint
D8 Archive read-only and reversible; historical relations kept; no cascade from a client to its animals; no retention duration; archive is not erasure SQL and permissions: archived_at columns, RPCs refuse edits on archived rows
D9 No rule blocking an account's deletion for good; a later lifecycle contract (closure, deletion or anonymisation, justified retention, cabinet records, legal obligations); nothing implemented in V1-1, nothing in the model preventing it SQL: delete behaviour of the keys to the profile (D9a)
D16 No ordinary staff access to private records; no admin screen on clients, animals or bilans; exceptional technical operations framed, justified and audited before publication; no exceptional access mechanism in V1-1 permissions: no platform-role branch in any policy or RPC
C5 Writes reserved to workspace members with a write right; in V1-1 only the practitioner in their personal workspace; finished bilans never changed retroactively or silently permissions
C6 Email confirmation distinct from professional verification; a confirmed email gives private use; verification required for public professional features; statuses are not platform roles; verification process not built now permissions: the V1-1 gate is an active session

9.2 Sub-choices the orientations leave open (SQL, before the migration)

Id Question Recommendation Alternative
D4a Structured first and last name for persons not in V1-1: one display_name; nullable columns can be added later without touching existing rows a required last_name for persons (a second required field, against D4)
D6a Fields beyond the owner's list: neutered, identification, colour, notes, deceased_on keep all five, optional drop any of them; adding one later is an additive column
D6b Birth date model birth_year plus an optional birth_date, with the coherence CHECK one date with a precision flag: stores an invented day for a year-only birth, which D6 refuses
D7a Ending a relation ended_at on the link, the row kept as history delete the row; the history then survives only as ids in the audit log
D9a Deleting, in DEV, an auth user whose personal workspace holds records a temporary guard refuses it, replaced by the lifecycle contract; an account with no record is deleted as today cascade (erases the records with the account, deciding the policy early) or keep an orphaned workspace (records nobody can read)

9.3 Decisions still open

Not arbitrated by the owner; status open, recommendation and impact given.

Before the RPCs are written (they change server behaviour):

Id Decision Recommendation Impact
D15 Abuse guard per-workspace caps (20 000 clients, 50 000 animals) refused by the create RPCs RPC behaviour, no table change

Before or during the interface work (no table impact):

Id Decision Recommendation Impact
D10 Client information notice: text, and whether the app records that it was given decide with the legal texts; nothing recorded in V1-1 none in V1-1; recording it later adds a column; required before public exposure
D11 Mobile navigation drawer only in V1-1; the tab bar of the mockup arrives with Bilans (V1-3), since two of its four entries would lead nowhere today UI
D12 Dashboard tiles show the two real tiles (clients, animals) now; bilans and appointments when their tables exist UI
D13 Shared Dialog focus trap and restore fix it in V1-1 (it also improves the editor dialogs; partial RR-7) UI, shared component
D14 Real-browser test tooling add @playwright/test and @axe-core/playwright as dev dependencies manifest and lockfile change at implementation
D17 Bridge to the local tool (« start a bilan for this animal », prefill only) no: V1-3 links bilans to animals properly; a prefill now would be a second path to delete later none

9.4 Never assumed, framed before any public exposure

The legal basis of the processing (consent is not presumed to be required), the information given to clients, the retention durations, the deletion and anonymisation rules, the legal qualification of each party. None of them blocks a DEV implementation once §9.1 is ratified; each blocks any public exposure.

Ratifying §9.1, answering §9.2 and settling D15 unlock the first migration, on a feature/ branch off develop.