From 12f0b21fdff354e8f85ed8a4967291986ec53b21 Mon Sep 17 00:00:00 2001 From: bchanot Date: Fri, 9 Oct 2026 00:24:22 +0200 Subject: [PATCH] =?UTF-8?q?feat(domain):=20finding=20kind=20observation=20?= =?UTF-8?q?=E2=86=92=20consultation=5Freason;=20Step=204=20business=20deci?= =?UTF-8?q?sions=20in=20spec=20+=20memory=20(BDR-033)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude/memory/decisions.md | 9 ++++ .claude/tasks/TODO.md | 10 ++++- docs/development/ANATOMICAL_SHEET_MODEL.md | 43 ++++++++----------- .../domain/src/anatomical-sheet/schema.ts | 2 +- packages/domain/tests/fixtures/horse-slice.ts | 10 ++--- 5 files changed, 41 insertions(+), 33 deletions(-) diff --git a/.claude/memory/decisions.md b/.claude/memory/decisions.md index 58a0cc70..3ddf93e4 100644 --- a/.claude/memory/decisions.md +++ b/.claude/memory/decisions.md @@ -279,3 +279,12 @@ Status: closed; category kind `observation` vs report Observation collision (C7) Tables species / anatomical_sheets / _versions / _assets. Published immutable via BEFORE UPDATE trigger (every role incl. owner; only published→deprecated with stamps); deprecated frozen; BEFORE DELETE trigger = preconditions (never published, never current, never base of active fork; reports join later) → no session flags, RPC just deletes. One draft per sheet (partial unique index, C8). Document↔row: CHECK `content->'schema_version' = to_jsonb(document_schema_version)`, trigger species match. `private.sheet_document_issues(jsonb)` re-checks the non-recursive error rules at publish + unknown asset ids → defense in depth, same codes as TS (BACKEND_ARCH "SQL doesn't re-implement Zod" kept for shape). Assets content-addressed (sha256, unique per sheet), Storage path `.svg` by convention, fork = metadata copy + `remap_document_assets`. Draft autosave = column-level UPDATE (content, change_note) policy on own draft (unaudited by design); identity (name/slug/description) column policy; visibility via audited `set_sheet_visibility` RPC and draft deletion via `delete_sheet_version` after gate review (sharing + deletion = sensitive state); `last_version_number` counter (no number reuse); content ≤ 2 MiB, byte_size ≤ 20 MiB, reason ≤ 500; `require_actor` refuses deactivated profiles; authz before lookup (unknown id = same 42501); fork copies only referenced assets. can_use_sheet = active ∧ (public ∨ editor) until grants/follows. Official sheet = creator null + is_official, platform admins edit. Alt rejected: session-flag delete bypass (hacky); Zod-equivalent validation only in TS (browser not a boundary); per-sheet asset storage copy on fork (needs worker job). Status: closed; names (`anatomical_sheet_assets`, storage layout, official ownership) listed for user confirmation. + +--- + +## BDR-033 | 2026-10-09 | User decisions on the Step 4 open points (sheets: follow, verification, versions, official, naming, server validation, erasure) + +User validated Step 4 and ruled: (1) public read by visibility, USE of a community sheet requires following its author, official sheets exempt → `can_use_sheet` + follow at community step; (2) private drafts for anyone, community publication only for authorised + verified accounts, student/professor keep own rules → gate in publish/set_visibility at verification step; (3) new publication = current, no auto-deprecation (current behaviour); (4) official sheets platform-owned, admin-run (current model); (5) finding kind `observation` → `consultation_reason` (done, packages/domain); (6) server-side validation mandatory for publication, frontend never a boundary → Zod shape check server-side before community step; (7) account deletion handles dependencies/transfer explicitly, nothing may block erasure forever → retention step anonymises authorship via a system path. +Scope guard from user: implement along the planned steps, keep 4b (equine import) free of community/account features. +Status: closed (recorded in ANATOMICAL_SHEET_MODEL.md §5). + diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index 24a2d08f..8828bc4a 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -61,7 +61,7 @@ feat/findings-tree-v2 merged (FindingsTreePicker tracked in HEAD); all work belo - [x] 3.8 CI: supabase job (start, db reset, test db, gen types diff); check job runs PGlite suite via pnpm -r - [x] 3.9 docs: docs/development/SUPABASE.md (start/reset/test/types/bootstrap owner), CLAUDE.md folder map + scopes, README pointer - [x] 3.10 verify: typecheck, test:run 278 app + 13 supabase (81 pgTAP), lint 0, build OK; BDR-026..029, LRN-035/036, BLK-006, EVAL-006 -- [ ] Step 4 — canonical anatomical sheet model (2026-10-08, branch feature/step-04-anatomical-sheet-model). Scope re-split: model + validation + persistence + tests here; legacy importer → official equine DRAFT + import report = next step (user: no full import yet, draft verified before publication). Spec: docs/development/ANATOMICAL_SHEET_MODEL.md +- [x] Step 4 — canonical anatomical sheet model (2026-10-08, feature/step-04-anatomical-sheet-model merged into develop, USER VALIDATED 2026-10-09; 7 business decisions → BDR-033, spec §5). Scope re-split: model + validation + persistence + tests here; legacy importer → official equine DRAFT + import report = next step (user: no full import yet, draft verified before publication). Spec: docs/development/ANATOMICAL_SHEET_MODEL.md - [x] 4.0 context + spec: business §2.6–2.9/§7/§16/§17.3/§23, OPEN_QUESTIONS C1/C2/C8/C9/Q3/Q5/Q9, audit 07; ANATOMICAL_SHEET_MODEL.md written - [x] 4.1 packages/domain: AnatomicalSheetDocumentSchema (strict, localized {fr,en}, views tree, annotations union, finding tree with category kind), validateSheetDocument (integrity issues), assertPublishable, createEmptySheetDocument; fixture horse-slice; tests per rule + id-stability - [x] 4.2 migration 20261008110000_anatomical_sheets: species (seed equine), enums, sheets/versions/assets, triggers (one draft, published immutable, delete preconditions, species match), helpers can_edit/can_use_sheet, sheet_document_issues, lifecycle RPCs (create/draft/publish/deprecate/delete/fork/archive/restore/delete sheet/register asset), privileges + RLS @@ -69,7 +69,13 @@ feat/findings-tree-v2 merged (FindingsTreePicker tracked in HEAD); all work belo - [x] 4.4 packages/supabase: database.types.ts regenerated (real stack), schema-types test extended (tables, enums list, functions); index.ts row aliases; publishSheetVersion service (domain validation before RPC) + test - [x] 4.5 docs: SUPABASE.md layout/tests, CLAUDE.md folder map + conventions + scopes, packages/README, IMPLEMENTATION_PLAN Step 4 adjustment note, CHANGELOG - [x] 4.6 verify: pnpm check green (61+17+278), db:reset + db:test 210/210 real stack, types in sync; verifier ECARTS(5) + security BLOCK(1) → all fixed (BLK-007 hardening migration, visibility RPC, +32 pgTAP, doc sync); BDR-030..032, LRN-038..040, EVAL-008 -- [ ] Step 4b — legacy importer → official equine sheet as DRAFT (document.json + legacy-id-map + IMPORT-REPORT.md for business verification), publication after user validation +- [ ] Step 4b — equine import (2026-10-09, branch feature/step-04b-equine-import): legacy SVGs + catalog → official equine sheet as DRAFT, import report for business review, no publication + - [ ] 4b.0 kind rename observation→consultation_reason (BDR-033 #5); decisions in spec §5 + memory + - [ ] 4b.1 packages/anatomy: legacy importer (SVG walker via @xmldom/xmldom, catalog mapper, deterministic ids, legacy-id-map, import report with anomalies incl. ssb-dysfunctions), CLI `pnpm import:equine` writing supabase/seed/anatomical-sheets/equine/v1/{document.json,legacy-id-map.json,IMPORT-REPORT.md,assets/,equine_v1.sql}; tests: counts preserved (27 ann / 26 mapped / 792 nodes / 612 leaves / 41 vet), determinism, Zod + 0 integrity errors, golden artifacts + - [ ] 4b.2 migration 20261009100000 sheet asset storage: bucket anatomical-sheet-assets (private), object read policy through the sheet (published refs or editor), no API writes; shim storage tables; pgTAP + - [ ] 4b.3 seed: equine_v1.sql idempotent (platform-owned official sheet, private, draft v1, 2 asset rows, fixed ids) in config sql_paths + PGlite harness applies supabase/seed/**; pgTAP 006: draft present, not publishable by non-admin, sheet_document_issues empty, assets match; upload script for the SVG bytes (service key from env, user/operator runs) + - [ ] 4b.4 real stack: db reset + db test + types check + assets upload + REST read check; docs (SUPABASE.md, ANATOMICAL_SHEET_MODEL.md §6 import, CLAUDE.md, plan note, CHANGELOG) + - [ ] 4b.5 verify: pnpm check, verifier + security gates, capitalize --- diff --git a/docs/development/ANATOMICAL_SHEET_MODEL.md b/docs/development/ANATOMICAL_SHEET_MODEL.md index 35a8bd4a..79ba11f9 100644 --- a/docs/development/ANATOMICAL_SHEET_MODEL.md +++ b/docs/development/ANATOMICAL_SHEET_MODEL.md @@ -57,7 +57,7 @@ AnatomicalSheetDocument │ Geometry = circle { cx, cy, r } | polygon { points: [x, y][] ≥ 3 } | path { d } └─ finding_zones: FindingZone[] FindingZone = { id, name: LocalizedText, categories: FindingCategory[] } - FindingCategory = { id, kind: dysfunction | observation | anamnesis | custom, name, description?, children: FindingNode[] } + FindingCategory = { id, kind: dysfunction | consultation_reason | anamnesis | custom, name, description?, children: FindingNode[] } FindingNode = { id, name, description?, requires_vet_referral?, sources?, children? } (recursive) SourceRef = { type: manual | journal | database | web, citation, url? } ``` @@ -269,28 +269,21 @@ with the community step (§17.4). | Migrations reproducible | PGlite replays from zero in `pnpm test:run`; `pnpm db:reset` on the real stack | | Previous tests pass | root `pnpm check` | -## 5. Decisions left to the user +## 5. Business decisions (user, 2026-10-09) -1. **Follow = permission to use a public sheet** (§2.9) is not yet modelled: - today every authenticated user can use any public active sheet. Grants - and follows will narrow `can_use_sheet` at the community step. -2. **Who may create sheets**: any active account for now. Should creation - wait for professional verification (Step 7)? -3. **Deprecation policy**: publishing v2 does not deprecate v1. Should it, - automatically, or stay a manual act? -4. **Table name `anatomical_sheet_assets` and the content-addressed Storage - layout** (`.svg`): confirm before the importer writes files. -5. **Official equine sheet owner**: platform-owned (`creator_user_id = null`, - `is_official = true`, edited by platform admins) or owned by the client's - account? -6. **Finding category kind naming**: `observation` collides with the report - "Observation" (OPEN_QUESTIONS C7). Alternative: `consultation_reason`. -7. **Server-side shape validation**: SQL re-checks references, sizes and the - species, not the full Zod shape (ids pattern, enums, unknown keys). A - client calling the RPC directly can publish a shape-invalid document to - its own sheet. Options: a plpgsql shape check, or publication through an - Edge Function running the Zod schema (community step at the latest). -8. **Account erasure**: `creator_user_id` is `on delete restrict` and the - immutability guard blocks `set null` on `published_by` of published rows, - so deleting an `auth.users` row that owns sheets fails by design until the - retention step (§16) defines reassignment or anonymisation. +The open points of Step 4 were decided as follows. Each line names where +the decision lands; only the naming one is implemented in this document. + +| # | Decision | Where it lands | +| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | Public sheets are readable according to their visibility, but **using** a community sheet for a report requires following its author. Official Faunosteo sheets need no follow. | `can_use_sheet` gains the follow predicate at the community step; official sheets (`is_official`) bypass it. Until then every active account may use any public sheet. | +| 2 | Any account may prepare private drafts; **community publication** is reserved to authorised, verified accounts. Student and professor roles keep their own rules. | `publish_sheet_version` + `set_sheet_visibility('public')` gain a verification check at the identity / verification step. | +| 3 | A new publication becomes the current version; older versions are **not deprecated automatically** and stay readable under the access rules. | Already the behaviour of `publish_sheet_version`; deprecation stays a manual act. | +| 4 | Official sheets are **platform-owned**, administered by authorised accounts. | Already the model: `creator_user_id = null`, `is_official = true`, platform admins edit. | +| 5 | Name anatomical findings apart from the observations typed during a report. | Finding category kind `observation` renamed **`consultation_reason`** (`dysfunction` / `consultation_reason` / `anamnesis` / `custom`). The report-side object keeps the name Observation. | +| 6 | Server-side validation and integrity for every publication; the frontend is never a security boundary. | SQL already re-checks references, sizes and species. The full shape check (Zod) moves server-side before community publication: plpgsql shape rules or an Edge Function gate, decided at the community step. | +| 7 | Account deletion handles dependencies and transfers explicitly (RGPD); no dependency may block the erasure of personal data forever. | Retention step (§16): published versions get their `created_by` / `published_by` anonymised through a dedicated system path (the immutability guard will allow that single transition), personal sheets are transferred or archived, `creator_user_id` keeps `on delete restrict` only as the backstop that forces the explicit path. | + +Still open, technical only: the Storage layout `.svg` is applied by +the importer step (4b) with a bucket policy that authorises through the +sheet, never through a hash alone. diff --git a/packages/domain/src/anatomical-sheet/schema.ts b/packages/domain/src/anatomical-sheet/schema.ts index 19c304ad..9879c556 100644 --- a/packages/domain/src/anatomical-sheet/schema.ts +++ b/packages/domain/src/anatomical-sheet/schema.ts @@ -217,7 +217,7 @@ export const FindingNodeSchema: z.ZodType< /** Typed business buckets; creators may add their own as 'custom'. */ export const FindingCategoryKindSchema = z.enum([ 'dysfunction', - 'observation', + 'consultation_reason', 'anamnesis', 'custom', ]) diff --git a/packages/domain/tests/fixtures/horse-slice.ts b/packages/domain/tests/fixtures/horse-slice.ts index 4f05c2f1..a1fecf92 100644 --- a/packages/domain/tests/fixtures/horse-slice.ts +++ b/packages/domain/tests/fixtures/horse-slice.ts @@ -86,7 +86,7 @@ const HIP_ZONE = { }, { id: 'hip-observations', - kind: 'observation', + kind: 'consultation_reason', name: OBSERVATIONS_NAME, children: [ { @@ -139,7 +139,7 @@ const CERVICAL_ZONE = { }, { id: 'cervical-observations', - kind: 'observation', + kind: 'consultation_reason', name: OBSERVATIONS_NAME, children: [ { @@ -177,7 +177,7 @@ const C7_T1_ZONE = { }, { id: 'c7-t1-observations', - kind: 'observation', + kind: 'consultation_reason', name: OBSERVATIONS_NAME, children: [ leaf( @@ -211,7 +211,7 @@ const ATM_ZONE = { }, { id: 'atm-observations', - kind: 'observation', + kind: 'consultation_reason', name: OBSERVATIONS_NAME, children: [ leaf( @@ -258,7 +258,7 @@ const SPHENOID_ZONE = { }, { id: 'sphenoid-observations', - kind: 'observation', + kind: 'consultation_reason', name: OBSERVATIONS_NAME, children: [ leaf(