feat(domain): sheet document schema v2 — references registry, review_status, vertebral count_range; SQL gate + pgTAP 008
This commit is contained in:
1 parent
6c5b2b7754
commit
3dbbfdf1df
19 files changed
+474
-71
No files matched your search
@@ -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
|
||||
|
||||
Reference in new issue
Block a user