feat(domain): finding kind observation → consultation_reason; Step 4 business decisions in spec + memory (BDR-033)

This commit is contained in:
bchanot committed 2026-10-09 00:24:22 +02:00
1 parent 1cc70c3589
commit 12f0b21fdf
5 files changed
+41 -33

No files matched your search

+9
View File
@@ -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 `<sha256>.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).
+8 -2
View File
@@ -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
---
+18 -25
View File
@@ -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** (`<sha256>.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 `<sha256>.svg` is applied by
the importer step (4b) with a bucket policy that authorises through the
sheet, never through a hash alone.
@@ -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',
])
+5 -5
View File
@@ -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(