docs(docs): consolidate V1-2 contract with ratified O1-O23, open AR-1
This commit is contained in:
1 parent
397d6007b4
commit
7fec2ce86f
7 files changed
+1621
-646
No files matched your search
@@ -1,17 +1,28 @@
|
||||
---
|
||||
paths: ["crates/core/src/domain/sheet/**", "docs/development/ANATOMICAL_SHEET_MODEL.md", "supabase/seed/anatomical-sheets/**", "crates/core/src/bin/upload_sheet_assets/**"]
|
||||
paths: ["crates/core/src/domain/sheet/**", "docs/development/ANATOMICAL_SHEET_MODEL.md", "docs/development/V1-2_ANATOMICAL_SHEETS.md", "supabase/seed/anatomical-sheets/**", "crates/core/src/bin/upload_sheet_assets/**"]
|
||||
---
|
||||
|
||||
# Anatomical sheet model (crates/core/src/domain/sheet + migration 20261008110000)
|
||||
- `docs/development/ANATOMICAL_SHEET_MODEL.md` is the source of truth: document shape, issue codes, tables, RPCs.
|
||||
- `docs/development/ANATOMICAL_SHEET_MODEL.md` is the source of truth for the model as built: document shape, issue
|
||||
codes, tables, RPCs. `docs/development/V1-2_ANATOMICAL_SHEETS.md` holds the ratified V1-2 rules (O1-O23, BDR-082):
|
||||
every V1-2 change follows it, and V1-2.9 folds it back into the model file.
|
||||
- Ids are stable slugs never derived from labels; labels are `{ fr, en }` objects. Annotation → findings is the
|
||||
explicit `finding_zone_id`; vertebral regions are ordered data with free codes. No label matching at runtime.
|
||||
- A published version is immutable (trigger, every role). Change = new draft (`create_sheet_draft`) then
|
||||
`publish_sheet_version`. Integrity rule codes are shared by `validate_sheet_document` (Rust core) and
|
||||
`private.sheet_document_issues` (SQL); add a rule on both sides and in the spec table.
|
||||
- A published version is immutable (trigger, every role) and, from V1-2, never deleted, even deprecated. Change = new
|
||||
draft (`create_sheet_draft`) then publication; from V1-2, publication only from an approved round on a server
|
||||
verdict of the core.
|
||||
- The Rust core is the only authority on document rules (O22): add a rule to `validate_sheet_document` and to the spec
|
||||
table only. Never extend `private.sheet_document_issues`: V1-2 (M5) removes its business rules and keeps the
|
||||
structural and relational guards.
|
||||
- Document schema change → bump `SHEET_DOCUMENT_SCHEMA_VERSION`, extend the SQL CHECK on `document_schema_version`.
|
||||
- Official equine sheet = generated seed `draft/` (`pnpm import:equine --out` into an empty folder, then reviewed and copied; never edit `legacy-import/` or `draft/` by hand;
|
||||
`curation_draft` / `curation_review` fail on drift, `pnpm import:equine --check` lists it). Every content change goes through `curation/changes.json` (traced in CHANGELOG.md).
|
||||
It is a DRAFT until a platform admin publishes it after business review of `REVIEW-REPORT.md`.
|
||||
- Sheet SVG bytes live in Storage bucket `anatomical-sheet-assets` as `<sha256>.svg`; uploads are an operator task
|
||||
(`pnpm assets:upload <seed dir>` with the service key in env), never from the browser.
|
||||
No bump during V1-2 (BLK-008).
|
||||
- Historical equine sheet `503dc301…` = generated seed `draft/` (`pnpm import:equine --out` into an empty folder, then
|
||||
reviewed and copied; never edit `legacy-import/` or `draft/` by hand; `curation_draft` / `curation_review` fail on
|
||||
drift, `pnpm import:equine --check` lists it). Its content changes only through `curation/changes.json` (traced in
|
||||
CHANGELOG.md), and the pipeline stays unchanged during V1-2. It is never published; equine work moves to an
|
||||
application working copy (O17), whose publication is an owner act after the business review.
|
||||
- Sheet SVG bytes live in Storage bucket `anatomical-sheet-assets` as `<sha256>.svg`, never overwritten. Until M5
|
||||
(V1-2.1) uploads are an operator task (`pnpm assets:upload <seed dir>`, local stacks, service key in env); from M5,
|
||||
editors upload from the application after the core's cleaning, and the worker verifies every submitted revision (M6).
|
||||
- Omitted `review_status` means `inherited` (`#[serde(default)]`): any check on statuses treats an absent value as
|
||||
`inherited`.
|
||||
@@ -55,7 +55,8 @@ business decisions ratified 2026-10-25, BDR-073; architecture and N1-N9 validate
|
||||
`pnpm db:sandbox`, applied to Supabase DEV 2026-10-27 by the owner procedure (SUPABASE.md §3.3); V1-1.3 the native modal dialog (D13) and the Playwright + axe suites
|
||||
(D14, `docs/development/BROWSER_TESTS.md`); V1-1.5 the client screens (`/app/clients`, contract §11.7) and V1-1.6
|
||||
the animal screens and the relations (`/app/animals`, contract §11.8; D11: drawer only, no tab bar)).
|
||||
V1-2 contract (draft, owner review pending): `docs/development/V1-2_ANATOMICAL_SHEETS.md`, branch `feature/v1-2-anatomical-sheets`.
|
||||
V1-2 contract (decisions O1-O23 ratified 2026-10-28, BDR-082; contract under the owner's final review, no implementation before
|
||||
the owner's go): `docs/development/V1-2_ANATOMICAL_SHEETS.md`, branch `feature/v1-2-anatomical-sheets`.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -11,6 +11,15 @@ manual report points confirmed).
|
||||
Out of scope here: the legacy importer and the official equine draft
|
||||
(next step), the visual editor, cloud reports, community, booking.
|
||||
|
||||
V1-2 (decisions ratified 2026-10-28, `V1-2_ANATOMICAL_SHEETS.md`, BDR-082)
|
||||
replaces the validation tiers of §2.1, the lifecycle of §3.1 and the access
|
||||
helpers of §3.2: explicit rights with MFA, drafts saved through an RPC with
|
||||
revisions, review rounds verified by the Rust worker, the SQL mirror of the
|
||||
integrity rules removed (the core is the only authority), species created
|
||||
inactive, the historical equine sheet kept read-only beside an application
|
||||
working copy. Until V1-2.9 rewrites those parts, this file describes the
|
||||
model as built.
|
||||
|
||||
## 1. Two layers
|
||||
|
||||
| Layer | Where | Role |
|
||||
@@ -19,8 +28,9 @@ Out of scope here: the legacy importer and the official equine draft
|
||||
| Relational identity | `supabase/migrations/20261008110000_anatomical_sheets.sql` | Who owns the sheet, visibility, versions and their status, provenance of copies, assets, audit. |
|
||||
|
||||
The database stores the document as JSONB in
|
||||
`anatomical_sheet_versions.content`. Zod is the shape contract at the
|
||||
application boundary; SQL checks what only SQL can know (species of the
|
||||
`anatomical_sheet_versions.content`. The Rust core's strict parser is the
|
||||
shape contract (`crates/core/src/domain/sheet/schema.rs`, through wasm in the
|
||||
browser); SQL checks what only SQL can know (species of the
|
||||
parent sheet, assets registered for the sheet, immutability, numbering) plus
|
||||
the referential rules of §3 at publication time, so a browser cannot publish
|
||||
a dangling document.
|
||||
@@ -109,8 +119,8 @@ Why these shapes:
|
||||
|
||||
| Tier | Function | When |
|
||||
| ---------- | ------------------------------------------ | ----------------------------------------------------------------------------- |
|
||||
| Shape | `AnatomicalSheetDocumentSchema.parse()` | every save (draft included) |
|
||||
| Integrity | `validateSheetDocument(doc): SheetIssue[]` | editor feedback; `publishable` = no issue with `severity: 'error'` |
|
||||
| Shape | strict parse of the Rust core (`schema.rs`) | every load and every check |
|
||||
| Integrity | `validate_sheet_document(doc)` (core; `sheet.check` through wasm) | editor feedback; `publishable` = no issue with `severity: 'error'` |
|
||||
| Relational | `publish_sheet_version()` in SQL | publication: species matches the sheet, assets exist, referential rules below |
|
||||
|
||||
`SheetIssue = { code, severity: 'error' | 'warning', path, message }`; the
|
||||
@@ -140,17 +150,20 @@ Integrity rules (error unless stated):
|
||||
| `reference.id.duplicate` | reference ids unique |
|
||||
| `finding.reference.missing` | every `reference_ids` entry (categories and nodes, any depth) is declared |
|
||||
| `region.count_range.invalid` | `count_range.min ≤ count ≤ count_range.max` when a range is given |
|
||||
| `reference.url.scheme` (SQL only; Zod refuses it at parse) | every `references[].url` is null or starts with `http://` / `https://` |
|
||||
| `reference.url.scheme` (SQL only; the core's strict parse refuses it) | every `references[].url` is null or starts with `http://` / `https://` |
|
||||
|
||||
A draft may be saved with errors. Publishing a document with errors is
|
||||
refused in TypeScript (`assertPublishable`) and in SQL:
|
||||
refused on the client (`publishSheetVersion` in `packages/supabase` runs the
|
||||
core's `sheet.check`) and in SQL:
|
||||
`private.sheet_document_issues` re-checks every error-level rule except
|
||||
parent cycles and sibling uniqueness (citations are walked recursively with
|
||||
a `jsonpath` `**` descent) and reports
|
||||
`document.shape` when an id-bearing collection is not an array;
|
||||
`private.sheet_document_unknown_assets` adds `view.asset.unknown` when a
|
||||
view points at an asset not registered for the sheet. Both run inside
|
||||
`publish_sheet_version`.
|
||||
`publish_sheet_version`. V1-2 removes the business part of this mirror and the
|
||||
client gate, keeps the structural and relational guards, and publishes only on
|
||||
a server verdict of the core (contract §12.2, O22).
|
||||
|
||||
## 3. Relational model
|
||||
|
||||
@@ -277,7 +290,7 @@ with the community step (§17.4).
|
||||
| Criterion | Where it is proven |
|
||||
| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| A sheet with several views and annotations explicitly linked to findings | `crates/core/tests/fixtures/horse-slice.json` (from `horse-slice.ts`, deleted at R5.7; 2 views, trigger, spine region, bilateral joint, 3 finding kinds); schema + integrity tests |
|
||||
| Ids stable under translation | test: renaming every label leaves ids, references and `validateSheetDocument` output unchanged |
|
||||
| Ids stable under translation | test: renaming every label leaves ids, references and `validate_sheet_document` output unchanged |
|
||||
| Published versions immutable | pgTAP: UPDATE of content / status / number on a published row → `42501` for the table owner; zero rows touched through the API role |
|
||||
| New version leaves old ones intact | pgTAP: v2 draft then publish; v1 row byte-identical, `current_version_id` moves |
|
||||
| Copies keep provenance, source untouched | pgTAP: fork → `based_on_*` set, source rows and assets unchanged; editing the copy leaves the source unchanged |
|
||||
|
||||
@@ -29,7 +29,7 @@ computer. Inventory: `.claude/audits/2026-10-25-functional-inventory.md`.
|
||||
|---|---|---|
|
||||
| P0 | Documents realigned on the code, decisions recorded (`OPEN_QUESTIONS.md` statuses) | none |
|
||||
| V1-1 | Clients and animals of a practitioner's workspace, with the permission frame of future cabinets (`V1-1_OWNERS_ANIMALS.md`) | 12 reduced, frame of 10 |
|
||||
| V1-2 | Anatomical sheets loaded from Supabase under control (no publication of the equine draft without the owner) | 13 reduced |
|
||||
| V1-2 | Official anatomical sheets administered from the application: rights, structured editor, server-verified review and publication, catalogue; the equine sheet prepared, never published inside V1-2 (`V1-2_ANATOMICAL_SHEETS.md`, decisions ratified 2026-10-28, BDR-082) | 13, and 17 reduced to official sheets |
|
||||
| V1-3 | Bilans persisted, linked to an animal, history | 14 (+ 11 skeleton if a quota applies) |
|
||||
| V1-4 | Stored PDF artifacts and authorised sharing | 15 reduced, sharing part of 12 |
|
||||
| V1-5 | Cross-cutting mobile and accessibility validation | design README, `TEST_STRATEGY.md` |
|
||||
@@ -367,7 +367,7 @@ Name: Anatomical sheets in the database and official equine seed
|
||||
Objective: Sheet and version tables with immutability, SVG assets in Storage, seed of the official equine sheet as a draft, SheetProvider over Supabase, read-only sheet library in the app.
|
||||
Dependencies: Step 3, Step 4, Step 8
|
||||
Changes expected:
|
||||
- supabase: anatomical_sheets, anatomical_sheet_versions (content_jsonb + schema CHECK), immutability trigger on published rows, version numbering RPC, deprecate RPC, GC function with the four preconditions (no report, no fork, no grant, no pending process) returning candidates only (deletion job at Step 18), helpers can_use_sheet/can_fork_sheet (creator-only for now), operator upload of the drawings (`pnpm assets:upload`) and the generated draft seed. Publication of the official equine sheet is an explicit act of a platform admin after the business review of REVIEW-REPORT.md (BDR-034, BDR-037); no step publishes it automatically.
|
||||
- supabase: anatomical_sheets, anatomical_sheet_versions (content + schema CHECK), immutability trigger on published rows, version numbering RPC, deprecate RPC, GC function with the four preconditions (no report, no fork, no grant, no pending process) returning candidates only (deletion job at Step 18), helpers can_use_sheet/can_fork_sheet (creator-only for now), operator upload of the drawings (`pnpm assets:upload`) and the generated draft seed. Publication of the official equine sheet is an explicit act of a platform admin after the business review of REVIEW-REPORT.md (BDR-034, BDR-037); no step publishes it automatically.
|
||||
- packages/supabase: typed accessors; apps/app: SheetProvider.supabase replaces the bundled seed in production builds (bundled kept for tests), /app/anatomy read-only list and preview.
|
||||
Tests: pgTAP: UPDATE on published content raises; v2 numbering; GC preconditions each individually; non-creator cannot read a private sheet; integration: seed is idempotent and byte-faithful (checksums).
|
||||
Manual validation: open /app/anatomy, see "Faunosteo / Cheval / officielle" with its draft or published status, preview both views, click zones (no report yet).
|
||||
@@ -384,6 +384,11 @@ candidates. Roadmap item V1-2 reduces the step to a controlled loading of the
|
||||
sheets; whether a signed-in practitioner may load the unpublished draft is an
|
||||
owner decision taken at V1-2.
|
||||
|
||||
Step 13 note (2026-10-28): V1-2 absorbs the provider and the library
|
||||
(`V1-2_ANATOMICAL_SHEETS.md` §10, §11). Drafts are never served to readers
|
||||
(D3); the catalogue is read under an explicit, provisional catalogue access
|
||||
until the entitlements of Step 11 (O21). The GC candidates stay with Step 18.
|
||||
|
||||
```text
|
||||
Step 14
|
||||
Name: Cloud reports
|
||||
@@ -444,6 +449,14 @@ Definition of Done: architecture Sprint 6 (except "promote manual point", added
|
||||
Risks: largest UI step; split into sub-branches (canvas tools / panels / publish) each merged green behind a "beta" flag; feature parity gaps with the vanilla tool found late (mitigate with the reference tests first).
|
||||
```
|
||||
|
||||
Step 17 note (2026-10-28): requirement D9 (BDR-081) moves the editor of
|
||||
official sheets into V1-2, at the level 1 of `V1-2_ANATOMICAL_SHEETS.md` §8.2,
|
||||
with server-verified review and publication. It supersedes, for official
|
||||
sheets, the 2026-10-25 rule « no graphic editor until Step 17 »: the curation
|
||||
pipeline stays the authority of the historical equine sheet only, whose work
|
||||
moves to an application working copy (O17). Step 17 keeps personal sheets, the
|
||||
level 2 editor (§8.3) and the community parts.
|
||||
|
||||
```text
|
||||
Step 18
|
||||
Name: Community
|
||||
|
||||
@@ -49,12 +49,23 @@ Step 5).
|
||||
sources and the Rust pipeline, reviewed, tested and versioned. Annotating a
|
||||
bilan is distinct from changing the anatomical reference and never touches
|
||||
`curation/changes.json`.
|
||||
Superseded for official sheets (owner, 2026-10-27, D9, BDR-081; decisions
|
||||
ratified 2026-10-28, BDR-082): V1-2 brings the editor of official sheets,
|
||||
with server-verified review and publication (`V1-2_ANATOMICAL_SHEETS.md`).
|
||||
The curation pipeline stays the authority of the historical equine sheet
|
||||
only; equine work moves to an application working copy (O17).
|
||||
2. Publication of the official equine sheet: the plan's Step 13 used to expect
|
||||
"v1 published"; BDR-034 and BDR-037 keep it a draft until a platform admin
|
||||
publishes after business review. Confirmed (owner, 2026-10-25): the equine
|
||||
sheet stays a draft until business validation, and nothing publishes it
|
||||
automatically. Still open for V1-2: who triggers the review, and whether
|
||||
V1-2 may serve the unpublished draft to signed-in practitioners.
|
||||
Resolved (owner, 2026-10-27 and 2026-10-28; BDR-081, BDR-082): drafts are
|
||||
never served to readers (D3); an editor submits, a reviewer outside the
|
||||
author set approves, a publisher publishes (O1, O2); the historical equine
|
||||
sheet is never published and its review is prepared on a working copy,
|
||||
whose publication stays an owner act after the business review, outside
|
||||
V1-2 (O17, O18).
|
||||
3. Recorded decision BDR-041 calls professional verification "Step 11"; the
|
||||
plan numbers it Step 9. Resolved: the plan's numbering is kept and the
|
||||
correction is the new entry BDR-072 (the registry is append-only, BDR-041
|
||||
|
||||
@@ -320,6 +320,9 @@ which needs the clock and is checked by the RPCs (tomorrow's UTC date, §9.3):
|
||||
|
||||
Reference data written by migration: the nine species of the contract (the
|
||||
existing `equine` row plus eight) and « Autre ». No other species is added.
|
||||
(Amended by V1-2 O9, ratified 2026-10-28: a habilitated sheet editor creates a
|
||||
species inactive, invisible in the animal forms, and the platform owner
|
||||
activates it; `V1-2_ANATOMICAL_SHEETS.md` §7.2.)
|
||||
Slugs, names and order approved by the owner (§13.2 N1). Compatibility,
|
||||
checked on 2026-10-25: species are rows of `public.species` (text `id`,
|
||||
CHECK `^[a-z0-9][a-z0-9_-]{0,63}$`, which every slug below satisfies), never a
|
||||
|
||||
File diff suppressed because it is too large.
Load diff
Reference in new issue
Block a user