diff --git a/docs/development/ANATOMICAL_SHEET_MODEL.md b/docs/development/ANATOMICAL_SHEET_MODEL.md index a81fd079..42ce4386 100644 --- a/docs/development/ANATOMICAL_SHEET_MODEL.md +++ b/docs/development/ANATOMICAL_SHEET_MODEL.md @@ -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 diff --git a/packages/anatomy/src/legacy/catalog.ts b/packages/anatomy/src/legacy/catalog.ts index da3362ff..188daa5a 100644 --- a/packages/anatomy/src/legacy/catalog.ts +++ b/packages/anatomy/src/legacy/catalog.ts @@ -2,7 +2,6 @@ import type { FindingCategoryKind, FindingNodeInput, LocalizedOptionalText, - SourceRef, } from '@faunosteo/domain' import { isStableId, slugify } from './ids' import type { Anomaly, ZoneStats } from './types' @@ -21,7 +20,8 @@ export interface LegacyNode { description_fr?: string description_en?: string requires_vet_referral?: boolean - sources?: SourceRef[] + /** Inline citations of the legacy format; none exist, see importer guard. */ + sources?: unknown[] children?: LegacyNode[] } @@ -130,7 +130,6 @@ function mapNode( const text = description(node) if (text) out.description = text if (node.requires_vet_referral === true) out.requires_vet_referral = true - if (node.sources) out.sources = node.sources.map((s) => ({ ...s })) if (node.children) { out.children = node.children.map((c) => mapNode(c, [...path, node.id], state), diff --git a/packages/anatomy/src/legacy/importer.ts b/packages/anatomy/src/legacy/importer.ts index 5c8f2d57..ac5baecf 100644 --- a/packages/anatomy/src/legacy/importer.ts +++ b/packages/anatomy/src/legacy/importer.ts @@ -153,6 +153,7 @@ function buildDocument( `pathologies.json (schema ${sources.catalog.schema_version})`, }, vertebral_config: { regions: vertebralRegions(sources.formula) }, + references: [], categories: mapped.categories.categories, views: buildViews(sources.assets), annotations: mapped.annotations.map((m) => m.annotation), @@ -226,6 +227,17 @@ function assertAnnotationsKept(stats: ImportStats): void { ) } +/** + * The canonical document cites a shared references registry; the legacy + * inline `sources` are not mapped. None exist today: refuse to drop any. + */ +function assertNoInlineSources(stats: ImportStats): void { + if (stats.sources === 0) return + throw new Error( + `${stats.sources} inline legacy sources found: map them to references`, + ) +} + function sourceAnomalies( sources: ParsedSources, stats: ImportStats, @@ -305,6 +317,7 @@ export function importEquineLegacy(input: EquineLegacyInput): ImportResult { const parsed = AnatomicalSheetDocumentSchema.parse(document) const stats = buildStats(sources, document, mapped) assertAnnotationsKept(stats) + assertNoInlineSources(stats) return { document, legacyIdMap: buildIdMap(sources, mapped), diff --git a/packages/anatomy/src/legacy/report.ts b/packages/anatomy/src/legacy/report.ts index f2c1bdb5..4e693215 100644 --- a/packages/anatomy/src/legacy/report.ts +++ b/packages/anatomy/src/legacy/report.ts @@ -1,3 +1,4 @@ +import { SHEET_DOCUMENT_SCHEMA_VERSION } from '@faunosteo/domain' import { AUTHORED_LABEL_CODE, regionLabelSubject } from './authored-labels' import { countTree } from './catalog' import type { Anomaly, ImportResult } from './types' @@ -269,7 +270,7 @@ function anomaliesSection(result: ImportResult): string { /** Source keys the document does not carry, and where they live now. */ const NOT_CARRIED_OVER = [ '`schema_version` du catalogue (`2.0`) : version du format historique, ' + - 'remplacée par `schema_version: 1` du document canonique ; la valeur ' + + `remplacée par \`schema_version: ${SHEET_DOCUMENT_SCHEMA_VERSION}\` du document canonique ; la valeur ` + "d'origine est citée dans `attribution.notes`.", 'bloc `species` du catalogue (`equine`, Cheval / Horse) : porté par ' + '`species_id` du document et par la table `public.species` ; le nom ' + diff --git a/packages/domain/src/anatomical-sheet/create.ts b/packages/domain/src/anatomical-sheet/create.ts index cc61873d..884f6524 100644 --- a/packages/domain/src/anatomical-sheet/create.ts +++ b/packages/domain/src/anatomical-sheet/create.ts @@ -27,6 +27,7 @@ export function createEmptySheetDocument( scope_disclaimer: {}, attribution: { authors: [], license: null, notes: null }, vertebral_config: { regions: [] }, + references: [], categories: [], views: [ { diff --git a/packages/domain/src/anatomical-sheet/schema.ts b/packages/domain/src/anatomical-sheet/schema.ts index 9879c556..25e354b6 100644 --- a/packages/domain/src/anatomical-sheet/schema.ts +++ b/packages/domain/src/anatomical-sheet/schema.ts @@ -1,16 +1,21 @@ import { z } from 'zod' /** - * Canonical anatomical sheet document, schema_version 1. + * Canonical anatomical sheet document, schema_version 2. * * Shape contract of docs/development/ANATOMICAL_SHEET_MODEL.md §2. Every * object is strict: a canonical document must not silently carry fields no - * version of the schema defines. Cross-references (view ids, zone ids…) are - * checked by validateSheetDocument, not here, so a draft with dangling - * references can still be saved. + * version of the schema defines. Cross-references (view ids, zone ids, + * reference ids…) are checked by validateSheetDocument, not here, so a + * draft with dangling references can still be saved. + * + * Version 2 (Step 4c): shared bibliographic `references` registry cited by + * `reference_ids`, `review_status` on findings and annotations, optional + * `count_range` on vertebral regions. No version 1 document was ever + * published, so version 1 is not read any more. */ -export const SHEET_DOCUMENT_SCHEMA_VERSION = 1 +export const SHEET_DOCUMENT_SCHEMA_VERSION = 2 /** Ids are never derived from labels, so translations never move them. */ export const STABLE_ID_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/ @@ -30,11 +35,29 @@ export const LocalizedOptionalTextSchema = z .object({ fr: z.string().optional(), en: z.string().optional() }) .strict() +/** + * How far the sheet content was checked against references. `inherited` = + * taken over from a previous source without review; `reviewed` = checked + * and cited; `to_confirm` = changed or added on documented grounds, still + * awaiting a professional's confirmation. + */ +export const ReviewStatusSchema = z.enum(['inherited', 'reviewed', 'to_confirm']) + +const CountRangeSchema = z + .object({ min: z.number().int().min(1), max: z.number().int().min(1) }) + .strict() + +/** + * `count` is the usual number of vertebrae (what the picker shows by + * default); `count_range` states the documented individual variation so a + * report may record a vertebra beyond the usual count. Null = no variation. + */ export const VertebralRegionSchema = z .object({ code: RegionCodeSchema, name: LocalizedTextSchema, count: z.number().int().min(1), + count_range: CountRangeSchema.nullable().default(null), }) .strict() @@ -125,6 +148,7 @@ const annotationCommon = { category_id: StableIdSchema, laterality: LateralitySchema, geometry: GeometrySchema.nullable(), + review_status: ReviewStatusSchema.default('inherited'), } /** Observable annotations link to findings through one explicit field. */ @@ -165,15 +189,24 @@ const HttpUrlSchema = z .url() .refine((url) => /^https?:\/\//i.test(url), 'http(s) URL expected') -export const SourceRefSchema = z +/** + * One bibliographic reference, declared once in the document and cited by + * id from any number of findings (an anatomy atlas backs hundreds of + * entries). `citation` is the human-readable form (author, title, edition, + * year, publisher or journal, location in the work when known). + */ +export const ReferenceSchema = z .object({ - type: z.enum(['manual', 'journal', 'database', 'web']), + id: StableIdSchema, + type: z.enum(['book', 'journal', 'standard', 'legal', 'web', 'manual']), citation: z.string().min(1), - url: HttpUrlSchema.optional(), + url: HttpUrlSchema.nullable().default(null), + doi: z.string().min(1).nullable().default(null), }) .strict() -export type SourceRef = z.infer +export type Reference = z.infer +export type ReviewStatus = z.infer export type LocalizedText = z.infer export type LocalizedOptionalText = z.infer @@ -183,7 +216,8 @@ export interface FindingNode { name: LocalizedText description: LocalizedOptionalText requires_vet_referral: boolean - sources: SourceRef[] + reference_ids: string[] + review_status: ReviewStatus children: FindingNode[] } @@ -193,7 +227,8 @@ export interface FindingNodeInput { name: LocalizedText description?: LocalizedOptionalText requires_vet_referral?: boolean - sources?: SourceRef[] + reference_ids?: string[] + review_status?: ReviewStatus children?: FindingNodeInput[] } @@ -208,7 +243,8 @@ export const FindingNodeSchema: z.ZodType< name: LocalizedTextSchema, description: LocalizedOptionalTextSchema.default({}), requires_vet_referral: z.boolean().default(false), - sources: z.array(SourceRefSchema).default([]), + reference_ids: z.array(StableIdSchema).default([]), + review_status: ReviewStatusSchema.default('inherited'), children: z.array(FindingNodeSchema).default([]), }) .strict(), @@ -228,6 +264,8 @@ export const FindingCategorySchema = z kind: FindingCategoryKindSchema, name: LocalizedTextSchema, description: LocalizedOptionalTextSchema.default({}), + reference_ids: z.array(StableIdSchema).default([]), + review_status: ReviewStatusSchema.default('inherited'), children: z.array(FindingNodeSchema), }) .strict() @@ -261,6 +299,7 @@ export const AnatomicalSheetDocumentSchema = z scope_disclaimer: LocalizedOptionalTextSchema, attribution: AttributionSchema, vertebral_config: VertebralConfigSchema, + references: z.array(ReferenceSchema), categories: z.array(AnnotationCategorySchema), views: z.array(SheetViewSchema), annotations: z.array(AnnotationSchema), diff --git a/packages/domain/src/anatomical-sheet/validate.ts b/packages/domain/src/anatomical-sheet/validate.ts index 473de443..97aa6ead 100644 --- a/packages/domain/src/anatomical-sheet/validate.ts +++ b/packages/domain/src/anatomical-sheet/validate.ts @@ -3,6 +3,7 @@ import type { Annotation, FindingNode, SheetView, + VertebralRegion, } from './schema' /** @@ -32,6 +33,7 @@ type DetailView = Extract /** A sibling level of the finding tree: categories or node children. */ interface FindingLevelItem { id: string + reference_ids: readonly string[] children: readonly FindingNode[] } @@ -372,6 +374,69 @@ const checkFindingZonesReferenced: Rule = (doc) => { ) } +const checkReferenceIdsUnique: Rule = (doc) => + duplicateIssues( + doc.references.map((reference) => reference.id), + 'reference.id.duplicate', + (index) => `references[${index}].id`, + ) + +/** A citation must point at a declared reference, at every depth. */ +function citationIssues( + nodes: readonly FindingLevelItem[], + path: string, + known: ReadonlySet, +): SheetIssue[] { + return nodes.flatMap((node, index) => { + const own = node.reference_ids.flatMap((id, refIndex) => + known.has(id) + ? [] + : [ + error( + 'finding.reference.missing', + `${path}[${index}].reference_ids[${refIndex}]`, + `Reference "${id}" is not declared in references`, + ), + ], + ) + const nested = citationIssues( + node.children, + `${path}[${index}].children`, + known, + ) + return [...own, ...nested] + }) +} + +const checkFindingReferences: Rule = (doc) => { + const known = new Set(doc.references.map((reference) => reference.id)) + return doc.finding_zones.flatMap((zone, index) => + citationIssues( + zone.categories, + `finding_zones[${index}].categories`, + known, + ), + ) +} + +/** The usual count must sit inside the documented variation. */ +function countRangeIssue(region: VertebralRegion, index: number): SheetIssue[] { + const range = region.count_range + if (range === null) return [] + if (range.min <= region.count && region.count <= range.max) return [] + return [ + error( + 'region.count_range.invalid', + `vertebral_config.regions[${index}].count_range`, + `Region "${region.code}": count ${region.count} outside ` + + `${range.min}–${range.max}`, + ), + ] +} + +const checkRegionCountRanges: Rule = (doc) => + doc.vertebral_config.regions.flatMap(countRangeIssue) + const RULES: readonly Rule[] = [ checkMainViewCount, checkViewIdsUnique, @@ -391,6 +456,9 @@ const RULES: readonly Rule[] = [ checkFindingZoneIdsUnique, checkFindingSiblings, checkFindingZonesReferenced, + checkReferenceIdsUnique, + checkFindingReferences, + checkRegionCountRanges, ] /** Lists every integrity issue of a shape-valid document. */ diff --git a/packages/domain/tests/anatomical-sheet.schema.test.ts b/packages/domain/tests/anatomical-sheet.schema.test.ts index 0e7cfd1a..ac881981 100644 --- a/packages/domain/tests/anatomical-sheet.schema.test.ts +++ b/packages/domain/tests/anatomical-sheet.schema.test.ts @@ -50,7 +50,7 @@ describe('AnatomicalSheetDocumentSchema', () => { ], ['a stable id with an accent', (d) => set(d, ['categories', 0, 'id'], 'É')], ['an empty stable id', (d) => set(d, ['finding_zones', 0, 'id'], '')], - ['schema_version 2', (d) => set(d, ['schema_version'], 2)], + ['schema_version 1', (d) => set(d, ['schema_version'], 1)], [ 'a non-uuid svg_asset_id', (d) => set(d, ['views', 0, 'svg_asset_id'], 'horse'), @@ -85,23 +85,21 @@ describe('AnatomicalSheetDocumentSchema', () => { (d) => set(d, ['annotations', 3, 'finding_zone_id'], 'hip'), ], [ - 'a javascript: source url', + 'a javascript: reference url', + (d) => set(d, ['references', 0, 'url'], 'javascript:alert(1)'), + ], + [ + 'a reference type foo', + (d) => set(d, ['references', 0, 'type'], 'foo'), + ], + [ + 'a review_status foo', + (d) => set(d, ['annotations', 0, 'review_status'], 'foo'), + ], + [ + 'a count_range with min 0', (d) => - set( - d, - [ - 'finding_zones', - 0, - 'categories', - 2, - 'children', - 0, - 'sources', - 0, - 'url', - ], - 'javascript:alert(1)', - ), + set(d, ['vertebral_config', 'regions', 4, 'count_range', 'min'], 0), ], [ 'a finding category kind foo', @@ -136,13 +134,15 @@ describe('FindingNodeSchema defaults', () => { }) expect(node.description).toEqual({}) expect(node.requires_vet_referral).toBe(false) - expect(node.sources).toEqual([]) + expect(node.reference_ids).toEqual([]) + expect(node.review_status).toBe('inherited') expect(node.children[0]).toEqual({ id: 'flexion', name: { fr: 'Flexion', en: 'Flexion' }, description: {}, requires_vet_referral: false, - sources: [], + reference_ids: [], + review_status: 'inherited', children: [], }) }) @@ -152,7 +152,13 @@ describe('FindingNodeSchema defaults', () => { const lameness = doc.finding_zones[0].categories[1].children[0] expect(lameness.requires_vet_referral).toBe(true) const trauma = doc.finding_zones[0].categories[2].children[0] - expect(trauma.sources).toHaveLength(1) + expect(trauma.reference_ids).toEqual(['legacy-catalog']) + expect(doc.vertebral_config.regions[4].count_range).toEqual({ + min: 15, + max: 21, + }) + expect(doc.vertebral_config.regions[0].count_range).toBeNull() + expect(doc.annotations[0].review_status).toBe('inherited') }) it('does not add default keys to the lean input', () => { diff --git a/packages/domain/tests/anatomical-sheet.validate.test.ts b/packages/domain/tests/anatomical-sheet.validate.test.ts index 70c25436..8856be86 100644 --- a/packages/domain/tests/anatomical-sheet.validate.test.ts +++ b/packages/domain/tests/anatomical-sheet.validate.test.ts @@ -32,6 +32,7 @@ function point(id: string, fields: Partial = {}): Annotation { category_id: 'articulations', laterality: 'bilateral', geometry: null, + review_status: 'inherited', name: { fr: id, en: id }, finding_zone_id: 'hip', vertebral_region_code: null, @@ -47,6 +48,7 @@ function trigger(id: string, viewId: string, opensViewId: string) { category_id: 'cadrans-du-crane', laterality: 'unpaired', geometry: null, + review_status: 'inherited', name: null, opens_view_id: opensViewId, } satisfies Annotation @@ -284,6 +286,49 @@ describe('integrity rules (one mutation per code)', () => { expect(issuesOf(doc)).toEqual([]) }) + it('reference.id.duplicate', () => { + const doc = mutated((d) => { + d.references.push(structuredClone(d.references[0])) + }) + expect(issuesOf(doc)).toEqual([ + ['reference.id.duplicate', 'references[1].id'], + ]) + }) + + it('finding.reference.missing on a category and on a nested node', () => { + const doc = mutated((d) => { + const hip = d.finding_zones[0].categories + hip[0].reference_ids = ['nav-2017'] + hip[0].children[0].children[0].reference_ids = ['legacy-catalog', 'x'] + }) + expect(issuesOf(doc)).toEqual([ + [ + 'finding.reference.missing', + 'finding_zones[0].categories[0].reference_ids[0]', + ], + [ + 'finding.reference.missing', + 'finding_zones[0].categories[0].children[0].children[0].reference_ids[1]', + ], + ]) + }) + + it('region.count_range.invalid when count sits outside the range', () => { + const doc = mutated((d) => { + d.vertebral_config.regions[4].count_range = { min: 19, max: 21 } + }) + expect(issuesOf(doc)).toEqual([ + ['region.count_range.invalid', 'vertebral_config.regions[4].count_range'], + ]) + }) + + it('region.count_range accepts count on the bounds', () => { + const doc = mutated((d) => { + d.vertebral_config.regions[4].count_range = { min: 18, max: 18 } + }) + expect(issuesOf(doc)).toEqual([]) + }) + it('finding_zone.unreferenced is a warning', () => { const doc = mutated((d) => { d.finding_zones.push({ diff --git a/packages/domain/tests/fixtures/horse-slice.ts b/packages/domain/tests/fixtures/horse-slice.ts index a1fecf92..cd0897e7 100644 --- a/packages/domain/tests/fixtures/horse-slice.ts +++ b/packages/domain/tests/fixtures/horse-slice.ts @@ -102,15 +102,7 @@ const HIP_ZONE = { { ...ANAMNESIS, children: [ - { - ...TRAUMA, - sources: [ - { - type: 'manual', - citation: 'Legacy equine catalog (pathologies.json)', - }, - ], - }, + { ...TRAUMA, reference_ids: ['legacy-catalog'] }, ], }, ], @@ -273,7 +265,7 @@ const SPHENOID_ZONE = { } satisfies AnatomicalSheetDocumentInput['finding_zones'][number] const HORSE_SLICE_INPUT: AnatomicalSheetDocumentInput = { - schema_version: 1, + schema_version: 2, species_id: 'equine', name: { fr: 'Cheval (extrait)', en: 'Horse (slice)' }, description: { @@ -294,9 +286,21 @@ const HORSE_SLICE_INPUT: AnatomicalSheetDocumentInput = { { code: 'T', name: { fr: 'Thoraciques', en: 'Thoracic' }, count: 18 }, { code: 'L', name: { fr: 'Lombaires', en: 'Lumbar' }, count: 6 }, { code: 'S', name: { fr: 'Sacrées', en: 'Sacral' }, count: 5 }, - { code: 'Cd', name: { fr: 'Caudales', en: 'Caudal' }, count: 18 }, + { + code: 'Cd', + name: { fr: 'Caudales', en: 'Caudal' }, + count: 18, + count_range: { min: 15, max: 21 }, + }, ], }, + references: [ + { + id: 'legacy-catalog', + type: 'manual', + citation: 'Legacy equine catalog (pathologies.json, schema 2.0)', + }, + ], categories: [ { id: 'articulations', diff --git a/packages/supabase/tests/anatomical-sheets.test.ts b/packages/supabase/tests/anatomical-sheets.test.ts index aec1e889..413f9abb 100644 --- a/packages/supabase/tests/anatomical-sheets.test.ts +++ b/packages/supabase/tests/anatomical-sheets.test.ts @@ -25,13 +25,14 @@ function stubClient(content: unknown) { } const publishable = { - schema_version: 1, + schema_version: 2, species_id: 'equine', name: { fr: 'Test', en: 'Test' }, description: {}, scope_disclaimer: {}, attribution: { authors: [], license: null, notes: null }, vertebral_config: { regions: [] }, + references: [], categories: [], views: [ { @@ -67,7 +68,7 @@ describe('publishSheetVersion', () => { }) it('refuses a document that does not match the schema', async () => { - const { client, rpcCalls } = stubClient({ schema_version: 2 }) + const { client, rpcCalls } = stubClient({ schema_version: 1 }) await expect(publishSheetVersion(client, 'v1')).rejects.toThrow() expect(rpcCalls).toEqual([]) }) diff --git a/supabase/migrations/20261010100000_sheet_document_schema_v2.sql b/supabase/migrations/20261010100000_sheet_document_schema_v2.sql new file mode 100644 index 00000000..8b990d12 --- /dev/null +++ b/supabase/migrations/20261010100000_sheet_document_schema_v2.sql @@ -0,0 +1,118 @@ +-- Canonical document schema_version 2 (ANATOMICAL_SHEET_MODEL.md §2, Step 4c): +-- shared `references` registry cited by `reference_ids`, `review_status` +-- on findings and annotations, optional `count_range` on vertebral regions. +-- No version 1 document was ever published (the only row is the official +-- equine draft, regenerated by its seed), so version 1 is no longer stored. + +alter table public.anatomical_sheet_versions + drop constraint anatomical_sheet_versions_schema_known; + +alter table public.anatomical_sheet_versions + add constraint anatomical_sheet_versions_schema_known + check (document_schema_version = 2); + +-- Shape: the references registry is one more id-bearing array. +create or replace function private.sheet_document_has_shape(p_doc jsonb) +returns boolean +language sql +immutable +set search_path = '' +as $$ + select jsonb_typeof(p_doc) = 'object' + and jsonb_typeof(coalesce(p_doc -> 'views', '[]'::jsonb)) = 'array' + and jsonb_typeof(coalesce(p_doc -> 'annotations', '[]'::jsonb)) = 'array' + and jsonb_typeof(coalesce(p_doc -> 'categories', '[]'::jsonb)) = 'array' + and jsonb_typeof(coalesce(p_doc -> 'finding_zones', '[]'::jsonb)) = 'array' + and jsonb_typeof(coalesce(p_doc -> 'references', '[]'::jsonb)) = 'array' + and jsonb_typeof(coalesce(p_doc -> 'vertebral_config' -> 'regions', '[]'::jsonb)) = 'array'; +$$; + +-- Uniqueness of the id-bearing collections, references included. +create or replace function private.sheet_document_duplicate_issues(p_doc jsonb) +returns text[] +language plpgsql +immutable +set search_path = '' +as $$ +declare + v_issues text[] := '{}'; + r record; +begin + for r in + select * from (values + ('views', 'id', 'view.id.duplicate'), + ('annotations', 'id', 'annotation.id.duplicate'), + ('categories', 'id', 'category.id.duplicate'), + ('finding_zones', 'id', 'finding_zone.id.duplicate'), + ('references', 'id', 'reference.id.duplicate') + ) as t(collection, key, code) + loop + if exists ( + select 1 from jsonb_array_elements(coalesce(p_doc -> r.collection, '[]'::jsonb)) e + group by e ->> r.key having count(*) > 1 + ) then + v_issues := private.append_issue(v_issues, r.code); + end if; + end loop; + if exists ( + select 1 from jsonb_array_elements(coalesce(p_doc -> 'vertebral_config' -> 'regions', '[]'::jsonb)) g + group by g ->> 'code' having count(*) > 1 + ) then + v_issues := private.append_issue(v_issues, 'region.code.duplicate'); + end if; + return v_issues; +end; +$$; + +-- Citations point at declared references (every depth of the finding tree, +-- categories included); the usual vertebra count sits inside its range. +create or replace function private.sheet_document_reference_issues(p_doc jsonb) +returns text[] +language plpgsql +immutable +set search_path = '' +as $$ +declare + v_issues text[] := '{}'; +begin + if exists ( + select 1 + from jsonb_path_query(coalesce(p_doc -> 'finding_zones', '[]'::jsonb), '$[*].categories[*].**.reference_ids[*]') cited + where not exists ( + select 1 from jsonb_array_elements(coalesce(p_doc -> 'references', '[]'::jsonb)) ref + where ref -> 'id' = cited + ) + ) then + v_issues := private.append_issue(v_issues, 'finding.reference.missing'); + end if; + if exists ( + select 1 + from jsonb_array_elements(coalesce(p_doc -> 'vertebral_config' -> 'regions', '[]'::jsonb)) g + where jsonb_typeof(g -> 'count_range') = 'object' + and not ( + (g -> 'count_range' ->> 'min')::numeric <= (g ->> 'count')::numeric + and (g ->> 'count')::numeric <= (g -> 'count_range' ->> 'max')::numeric + ) + ) then + v_issues := private.append_issue(v_issues, 'region.count_range.invalid'); + end if; + return v_issues; +end; +$$; + +revoke all on function private.sheet_document_reference_issues(jsonb) from public; + +create or replace function private.sheet_document_issues(p_doc jsonb) +returns text[] +language sql +immutable +set search_path = '' +as $$ + select case + when not private.sheet_document_has_shape(p_doc) then array['document.shape'] + else private.sheet_document_view_issues(p_doc) + || private.sheet_document_duplicate_issues(p_doc) + || private.sheet_document_annotation_issues(p_doc) + || private.sheet_document_reference_issues(p_doc) + end; +$$; diff --git a/supabase/seed/anatomical-sheets/equine/v1/IMPORT-REPORT.md b/supabase/seed/anatomical-sheets/equine/v1/IMPORT-REPORT.md index edce7970..baf750e1 100644 --- a/supabase/seed/anatomical-sheets/equine/v1/IMPORT-REPORT.md +++ b/supabase/seed/anatomical-sheets/equine/v1/IMPORT-REPORT.md @@ -193,7 +193,7 @@ Aucune donnée métier écartée. Non repris par construction : -- `schema_version` du catalogue (`2.0`) : version du format historique, remplacée par `schema_version: 1` du document canonique ; la valeur d'origine est citée dans `attribution.notes`. +- `schema_version` du catalogue (`2.0`) : version du format historique, remplacée par `schema_version: 2` du document canonique ; la valeur d'origine est citée dans `attribution.notes`. - bloc `species` du catalogue (`equine`, Cheval / Horse) : porté par `species_id` du document et par la table `public.species` ; le nom de la fiche est écrit séparément (voir anomalies `label.authored`). - second élément graphique de chaque annotation (marqueur visuel) : reste dans l'asset SVG copié à l'identique, le document ne garde que la zone de clic. - `data-anno-category-name` : répète le slug technique (`articulations`, `os`), ce n'est pas un libellé ; le libellé de catégorie vient de la table de l'importateur (section 4). diff --git a/supabase/seed/anatomical-sheets/equine/v1/document.json b/supabase/seed/anatomical-sheets/equine/v1/document.json index 8a55835b..829f483b 100644 --- a/supabase/seed/anatomical-sheets/equine/v1/document.json +++ b/supabase/seed/anatomical-sheets/equine/v1/document.json @@ -1,5 +1,5 @@ { - "schema_version": 1, + "schema_version": 2, "species_id": "equine", "name": { "fr": "Cheval", @@ -61,6 +61,7 @@ } ] }, + "references": [], "categories": [ { "id": "articulations", diff --git a/supabase/seed/anatomical-sheets/equine/v1/equine_v1.sql b/supabase/seed/anatomical-sheets/equine/v1/equine_v1.sql index c22c2301..73781018 100644 --- a/supabase/seed/anatomical-sheets/equine/v1/equine_v1.sql +++ b/supabase/seed/anatomical-sheets/equine/v1/equine_v1.sql @@ -23,7 +23,7 @@ select private.insert_sheet_draft( null, '503dc301-a8b1-50d4-9e44-0919b2fc2916', $equine_doc${ - "schema_version": 1, + "schema_version": 2, "species_id": "equine", "name": { "fr": "Cheval", @@ -85,6 +85,7 @@ select private.insert_sheet_draft( } ] }, + "references": [], "categories": [ { "id": "articulations", diff --git a/supabase/tests/005_anatomical_sheets.sql b/supabase/tests/005_anatomical_sheets.sql index 2434f7b2..3c53ca37 100644 --- a/supabase/tests/005_anatomical_sheets.sql +++ b/supabase/tests/005_anatomical_sheets.sql @@ -21,7 +21,7 @@ returns jsonb language sql as $$ select jsonb_build_object( - 'schema_version', 1, + 'schema_version', 2, 'species_id', 'equine', 'name', jsonb_build_object('fr', 'Cheval test', 'en', 'Test horse'), 'description', '{}'::jsonb, @@ -30,6 +30,7 @@ as $$ 'vertebral_config', jsonb_build_object('regions', jsonb_build_array( jsonb_build_object('code', 'C', 'name', jsonb_build_object('fr', 'Cervicales', 'en', 'Cervical'), 'count', 7) )), + 'references', '[]'::jsonb, 'categories', jsonb_build_array( jsonb_build_object('id', 'articulations', 'name', jsonb_build_object('fr', 'Articulations', 'en', 'Joints'), 'color', null) ), @@ -160,7 +161,7 @@ select throws_ok( ); select throws_ok( $$ update public.anatomical_sheet_versions - set content = jsonb_build_object('schema_version', 1, 'species_id', 'equine', 'pad', repeat('x', 2200000)) + set content = jsonb_build_object('schema_version', 2, 'species_id', 'equine', 'pad', repeat('x', 2200000)) where id = pg_temp.id('v1') $$, '23514', null, 'a document over 2 MiB is refused' ); @@ -405,7 +406,7 @@ select throws_ok( ); select throws_ok( $$ insert into public.anatomical_sheet_versions (sheet_id, version_number, document_schema_version, content) - values (pg_temp.id('sheet'), 9, 1, pg_temp.sheet_doc(null)) $$, + values (pg_temp.id('sheet'), 9, 2, pg_temp.sheet_doc(null)) $$, '42501', null, 'bob cannot insert a version row directly' ); @@ -429,7 +430,7 @@ select is( (select count(*) from public.anatomical_sheet_versions where id = pg_temp.id('v3') and content = '{}'::jsonb), 0::bigint, 'bob cannot read the draft' ); -update public.anatomical_sheet_versions set content = '{"schema_version":1}'::jsonb where id = pg_temp.id('v3'); +update public.anatomical_sheet_versions set content = '{"schema_version":2}'::jsonb where id = pg_temp.id('v3'); select throws_ok( $$ select public.fork_anatomical_sheet(pg_temp.id('v3'), 'Copie', 'copie-bob') $$, '42501', null, 'a draft cannot be copied (hidden from non-editors)' @@ -517,7 +518,7 @@ select is( update public.anatomical_sheet_versions set content = '{}'::jsonb where id = pg_temp.id('v2'); select is( (select content ->> 'schema_version' from public.anatomical_sheet_versions where id = pg_temp.id('v2')), - '1', 'a deprecated version is hidden from editor UPDATE' + '2', 'a deprecated version is hidden from editor UPDATE' ); reset role; select throws_ok( diff --git a/supabase/tests/006_sheet_asset_storage.sql b/supabase/tests/006_sheet_asset_storage.sql index 4aea4e98..e2510019 100644 --- a/supabase/tests/006_sheet_asset_storage.sql +++ b/supabase/tests/006_sheet_asset_storage.sql @@ -17,7 +17,7 @@ grant execute on function pg_temp.id(text) to anon, authenticated, service_role; -- Minimal publishable document with one main view on a given asset. create function pg_temp.doc(p_asset uuid) returns jsonb language sql as $$ select jsonb_build_object( - 'schema_version', 1, 'species_id', 'equine', + 'schema_version', 2, 'species_id', 'equine', 'name', jsonb_build_object('fr', 'A', 'en', 'A'), 'description', '{}'::jsonb, 'scope_disclaimer', '{}'::jsonb, 'attribution', jsonb_build_object('authors', '[]'::jsonb, 'license', null, 'notes', null), diff --git a/supabase/tests/007_equine_seed.sql b/supabase/tests/007_equine_seed.sql index 24d70229..6126793f 100644 --- a/supabase/tests/007_equine_seed.sql +++ b/supabase/tests/007_equine_seed.sql @@ -28,7 +28,7 @@ select results_eq( select results_eq( $$ select version_number, status::text, document_schema_version, published_at from public.anatomical_sheet_versions where sheet_id = pg_temp.id('sheet') $$, - $$ values (1, 'draft', 1, null::timestamptz) $$, + $$ values (1, 'draft', 2, null::timestamptz) $$, 'exactly one version, draft v1, never published' ); select is((select count(*) from public.anatomical_sheet_assets where sheet_id = pg_temp.id('sheet')), 2::bigint, 'two SVG assets registered'); diff --git a/supabase/tests/008_sheet_document_schema_v2.sql b/supabase/tests/008_sheet_document_schema_v2.sql new file mode 100644 index 00000000..8a4db50c --- /dev/null +++ b/supabase/tests/008_sheet_document_schema_v2.sql @@ -0,0 +1,90 @@ +-- Document schema_version 2: references registry, review status, count +-- ranges. Only version 2 is stored; the SQL gate re-checks the new rules. +begin; +select plan(8); + +insert into auth.users (id, email) values ('50000000-0000-0000-0000-00000000000a', 'alice-v2@test.local'); + +create function pg_temp.doc(p_refs jsonb, p_cited jsonb, p_range jsonb) +returns jsonb +language sql +as $$ + select jsonb_build_object( + 'schema_version', 2, + 'species_id', 'equine', + 'name', jsonb_build_object('fr', 'Cheval', 'en', 'Horse'), + 'description', '{}'::jsonb, + 'scope_disclaimer', '{}'::jsonb, + 'attribution', jsonb_build_object('authors', '[]'::jsonb, 'license', null, 'notes', null), + 'vertebral_config', jsonb_build_object('regions', jsonb_build_array( + jsonb_build_object('code', 'Cd', 'name', jsonb_build_object('fr', 'Caudales', 'en', 'Caudal'), 'count', 18, 'count_range', p_range) + )), + 'references', p_refs, + 'categories', jsonb_build_array( + jsonb_build_object('id', 'os', 'name', jsonb_build_object('fr', 'Os', 'en', 'Bones'), 'color', null) + ), + 'views', jsonb_build_array( + jsonb_build_object('id', 'main', 'kind', 'main', 'name', jsonb_build_object('fr', 'Vue', 'en', 'View'), + 'svg_asset_id', '00000000-0000-0000-0000-000000000001', 'view_box', null) + ), + 'annotations', jsonb_build_array( + jsonb_build_object('id', 'hip', 'kind', 'point', 'view_id', 'main', 'category_id', 'os', 'laterality', 'bilateral', + 'geometry', null, 'review_status', 'inherited', 'name', jsonb_build_object('fr', 'Hanche', 'en', 'Hip'), + 'finding_zone_id', 'hip', 'vertebral_region_code', null) + ), + 'finding_zones', jsonb_build_array( + jsonb_build_object('id', 'hip', 'name', jsonb_build_object('fr', 'Hanche', 'en', 'Hip'), 'categories', jsonb_build_array( + jsonb_build_object('id', 'hip-dysfunctions', 'kind', 'dysfunction', + 'name', jsonb_build_object('fr', 'Dysfonctions', 'en', 'Dysfunctions'), + 'reference_ids', '[]'::jsonb, + 'children', jsonb_build_array( + jsonb_build_object('id', 'articular', 'name', jsonb_build_object('fr', 'Articulaire', 'en', 'Articular'), + 'children', jsonb_build_array( + jsonb_build_object('id', 'flexion', 'name', jsonb_build_object('fr', 'Flexion', 'en', 'Flexion'), 'reference_ids', p_cited) + )) + )) + )) + ) + ); +$$; +grant execute on function pg_temp.doc(jsonb, jsonb, jsonb) to authenticated; + +select is( + private.sheet_document_issues(pg_temp.doc('[{"id":"nav","type":"standard","citation":"NAV 2017","url":null,"doi":null}]', '["nav"]', '{"min":15,"max":21}')), + '{}'::text[], 'a v2 document citing a declared reference inside its count range passes' +); +select is( + private.sheet_document_issues(pg_temp.doc('[]', '["nav"]', 'null')), + '{finding.reference.missing}'::text[], 'a citation of an undeclared reference is reported (nested node)' +); +select is( + private.sheet_document_issues(pg_temp.doc('[{"id":"nav","citation":"a"},{"id":"nav","citation":"b"}]', '[]', 'null')), + '{reference.id.duplicate}'::text[], 'duplicate reference ids are reported' +); +select is( + private.sheet_document_issues(pg_temp.doc('[]', '[]', '{"min":19,"max":21}')), + '{region.count_range.invalid}'::text[], 'a usual count outside its range is reported' +); +select is( + private.sheet_document_issues(pg_temp.doc('[]', '[]', '{"min":18,"max":18}')), + '{}'::text[], 'a count on the bounds of its range passes' +); +select is( + private.sheet_document_issues(jsonb_set(pg_temp.doc('[]', '[]', 'null'), '{references}', '"x"')), + '{document.shape}'::text[], 'a non-array references registry is a shape error' +); + +-- Only schema_version 2 rows are stored. +set local role authenticated; +select set_config('request.jwt.claims', '{"sub":"50000000-0000-0000-0000-00000000000a","role":"authenticated"}', true); +select throws_ok( + $$ select public.create_anatomical_sheet('equine', 'Old', 'old-v1', jsonb_set(pg_temp.doc('[]', '[]', 'null'), '{schema_version}', '1')) $$, + '23514', null, 'a schema_version 1 document is refused' +); +select lives_ok( + $$ select public.create_anatomical_sheet('equine', 'New', 'new-v2', pg_temp.doc('[]', '[]', 'null')) $$, + 'a schema_version 2 document is accepted as a draft' +); + +select * from finish(); +rollback;