feat(domain): sheet document schema v2 — references registry, review_status, vertebral count_range; SQL gate + pgTAP 008

This commit is contained in:
bchanot committed 2026-10-09 16:30:58 +02:00
1 parent 6c5b2b7754
commit 3dbbfdf1df
19 files changed
+474 -71

No files matched your search

+27 -12
View File
@@ -25,7 +25,7 @@ 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.
## 2. Canonical document (schema_version 1)
## 2. Canonical document (schema_version 2)
Every id is a **stable id**: `^[a-z0-9][a-z0-9_-]{0,63}$`, never derived
from a label, never changed by a translation. Vertebral region codes are
@@ -36,32 +36,43 @@ Adding a locale later means adding an optional key, not a new field family.
```text
AnatomicalSheetDocument
├─ schema_version: 1
├─ schema_version: 2
├─ species_id: stable id (row of public.species)
├─ name: LocalizedText display name of the sheet
├─ description: LocalizedOptionalText
├─ scope_disclaimer: LocalizedOptionalText legal scope text shown once per session and in the PDF
├─ attribution: { authors: string[], license: string | null, notes: string | null }
├─ vertebral_config: { regions: VertebralRegion[] } ORDERED; codes free (C/T/L/S/Cd for the horse)
│ VertebralRegion = { code, name: LocalizedText, count ≥ 1 }
│ VertebralRegion = { code, name: LocalizedText, count ≥ 1, count_range: { min, max } | null }
│ count = usual number (picker default); count_range = documented individual variation (Cd 15–21)
├─ references: Reference[] shared bibliography, cited by id from the finding tree
│ Reference = { id, type: book | journal | standard | legal | web | manual, citation, url | null, doi | null }
├─ categories: AnnotationCategory[] { id, name: LocalizedText, color: '#rrggbb' | null }
├─ views: SheetView[]
│ main: { id, kind: 'main', name, svg_asset_id: uuid | null, view_box: ViewBox | null }
│ detail: { id, kind: 'detail', name, parent_view_id, svg_asset_id: uuid | null, view_box: ViewBox | null }
│ ViewBox = { min_x, min_y, width > 0, height > 0 }
├─ annotations: Annotation[]
│ common: { id, view_id, category_id, laterality, geometry: Geometry | null }
│ common: { id, view_id, category_id, laterality, geometry: Geometry | null, review_status }
│ review_status ∈ inherited | reviewed | to_confirm (default inherited)
│ point | zone: + { name: LocalizedText, finding_zone_id: id | null, vertebral_region_code: code | null }
│ detail_trigger: + { name: LocalizedText | null, opens_view_id }
│ laterality ∈ unpaired | bilateral | left | right
│ 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 | 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? }
FindingCategory = { id, kind: dysfunction | consultation_reason | anamnesis | custom, name, description?, reference_ids?, review_status?, children: FindingNode[] }
FindingNode = { id, name, description?, requires_vet_referral?, reference_ids?, review_status?, children? } (recursive)
```
Version 2 (Step 4c) replaced the inline `sources` of version 1 by the
`references` registry + `reference_ids` (one atlas backs hundreds of
entries, declared once), added `review_status` (what was checked against
references versus inherited from the legacy catalog) and `count_range`
(individual variation of a vertebral region). No version 1 document was
ever published: the SQL CHECK accepts version 2 only and the one draft is
regenerated by its seed.
Why these shapes:
- **Views are a tree**, not a `details.head` field. A detail view names its
@@ -87,9 +98,9 @@ Why these shapes:
by `(finding_zone_id, path[])` exactly as `Finding.path` does today, so
the Step 5 report adapter is a rename, not a re-keying.
- **Tree nodes are lean on input, total on output**: `description`,
`requires_vet_referral`, `sources`, `children` are optional in the JSON
and defaulted by the parser (612 leaves would otherwise carry four empty
keys each). Structural records (views, annotations) use explicit `null`.
`requires_vet_referral`, `reference_ids`, `review_status`, `children` are
optional in the JSON and defaulted by the parser (612 leaves would
otherwise carry five empty keys each). Structural records (views, annotations) use explicit `null`.
- The parser is **strict**: unknown keys are rejected. A canonical document
must not silently carry fields no version of the schema defines.
@@ -125,11 +136,15 @@ Integrity rules (error unless stated):
| `region.code.duplicate`, `category.id.duplicate`, `finding_zone.id.duplicate` | uniqueness |
| `finding.id.duplicate` | node ids unique among siblings (per zone, per children array) |
| `finding_zone.unreferenced` (warning) | zone no annotation points to |
| `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 |
A draft may be saved with errors. Publishing a document with errors is
refused in TypeScript (`assertPublishable`) and in SQL:
`private.sheet_document_issues` re-checks every error-level rule except the
two recursive ones (parent cycle, sibling uniqueness) and reports
`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