From 70f21ccf373f89e02805fd2e4b77c52687a63571 Mon Sep 17 00:00:00 2001 From: Bastien Chanot Date: Wed, 20 May 2026 06:15:26 +0200 Subject: [PATCH] docs: add PATHOLOGIES-FORMAT spec for the findings JSON catalog Documents the canonical pathologies.json shape next to the existing ANATOMY-SVG-CONVENTION and PDF-FORMAT guides. Mirrors the Zod contract in src/domain/schema/findings.ts: - Top-level frame (schema_version, scope_disclaimer, species, zones). - ZoneFindings shape and how name_fr/name_en bridge to SVG labels. - Recursive FindingNode (leaf vs intermediate, optional description, vet-referral flag, sources). - SourceRef enum + URL validation. - A minimal worked example. - How leaf selections become persisted Findings, with the labelFr/En snapshot contract that protects already-exported reports from retroactive catalog edits. - Authoring workflow that defers to `pnpm scaffold:species` and Vite HMR-driven validation. Co-Authored-By: Claude --- docs/PATHOLOGIES-FORMAT.md | 235 +++++++++++++++++++++++++++++++++++++ 1 file changed, 235 insertions(+) create mode 100644 docs/PATHOLOGIES-FORMAT.md diff --git a/docs/PATHOLOGIES-FORMAT.md b/docs/PATHOLOGIES-FORMAT.md new file mode 100644 index 00000000..4874589a --- /dev/null +++ b/docs/PATHOLOGIES-FORMAT.md @@ -0,0 +1,235 @@ +# Pathologies / Findings JSON Format + +Each species ships a `pathologies.json` next to its `index.ts` manifest. +The JSON encodes the **hierarchical findings catalog** the practitioner +sees in the editor's per-zone picker and in the exported PDF. + +The single source of truth is the Zod schema at +[`src/domain/schema/findings.ts`](../src/domain/schema/findings.ts) — +this document mirrors it. + +The catalog is loaded once at module import via +`SpeciesFindingsSchema.parse(data)`. A malformed JSON crashes loudly at +boot (Zod stack trace pointing at the offending node) — there is no +silent fallback. + +--- + +## Top-level shape + +```json +{ + "schema_version": "1.1", + "scope_disclaimer": "string non vide — affiché 1× par session dans l'éditeur", + "species": { + "id": "equine", + "name_fr": "Cheval", + "name_en": "Horse" + }, + "zones": { + "": { ... ZoneFindings ... } + } +} +``` + +| Field | Type | Required | Notes | +| ------------------ | ------ | -------- | ----------------------------------------------------------- | +| `schema_version` | string | yes | non-empty, bump on breaking changes | +| `scope_disclaimer` | string | yes | non-empty, shown once per session | +| `species.id` | string | yes | should match the `SpeciesManifest.id` in the manifest | +| `species.name_fr` | string | yes | | +| `species.name_en` | string | yes | | +| `zones` | object | yes | dictionary keyed by free-form `zoneKey` → `ZoneFindings` | + +`zoneKey` is opaque — kebab-case is the convention. It does NOT have +to match SVG `data-anno-id` values (those are usually generator +strings). The runtime matches SVG zones to JSON zones via +`bone.fr` / `bone.en` ⇄ `zone.name_fr` / `zone.name_en` using the +fuzzy matcher in `src/lib/zoneMatch.ts`. + +--- + +## ZoneFindings + +```json +{ + "id": "sphenoid", + "name_fr": "Sphénoïde", + "name_en": "Sphenoid", + "categories": [ { ... FindingNode ... } ] +} +``` + +| Field | Type | Required | Notes | +| ------------ | --------------- | -------- | --------------------------------------------------------- | +| `id` | string | yes | by convention the same string as the parent `zoneKey` | +| `name_fr` | string | yes | matched against SVG `data-anno-name-fr` | +| `name_en` | string | yes | matched against SVG `data-anno-name-en` | +| `categories` | `FindingNode[]` | yes | may be empty | + +--- + +## FindingNode (recursive) + +```json +{ + "id": "tensions", + "name_fr": "Tensions des muscles masticateurs", + "name_en": "Masticatory muscle tensions", + "description_fr": "optionnel", + "description_en": "optionnel", + "requires_vet_referral": false, + "sources": [ { ... SourceRef ... } ], + "children": [ { ... FindingNode ... } ] +} +``` + +| Field | Type | Required | Notes | +| ----------------------- | --------------- | -------- | -------------------------------------------------- | +| `id` | string | yes | unique within its parent's `children` / `categories` | +| `name_fr` | string | yes | | +| `name_en` | string | yes | | +| `description_fr` | string | no | surfaced above the children list in the picker | +| `description_en` | string | no | reserved for future locale switch | +| `requires_vet_referral` | boolean | no | adds a ⚠ badge in picker and a ⚠ prefix in PDF | +| `sources` | `SourceRef[]` | no | citations, see below | +| `children` | `FindingNode[]` | no | absent or `[]` → leaf (selectable checkbox) | + +**Leaf vs intermediate:** + +- `children` missing or empty → **leaf**. Rendered as a checkbox. + Selecting it emits a `Finding` with the full path snapshot. +- `children` non-empty → **intermediate**. Rendered as a drill-down + button. The badge next to it counts selected descendants. + +--- + +## SourceRef (optional citation) + +```json +{ + "type": "journal", + "citation": "Auteur, 'Titre', Journal, 2024", + "url": "https://example.com/paper" +} +``` + +| Field | Type | Required | Notes | +| ---------- | --------------------------------------------- | -------- | -------------------------------------- | +| `type` | `"manual" \| "journal" \| "database" \| "web"` | yes | enum, validated by Zod | +| `citation` | string | yes | non-empty, human-readable | +| `url` | string | no | must pass `z.string().url()` if present | + +--- + +## Minimal complete example + +```json +{ + "schema_version": "1.1", + "scope_disclaimer": "Les éléments listés correspondent au périmètre légal de l'ostéopathie animale : dysfonctions ostéopathiques palpées, observations cliniques et motifs de consultation. Aucun diagnostic médical n'est posé. Toute pathologie organique relève du vétérinaire.", + "species": { + "id": "canine", + "name_fr": "Chien", + "name_en": "Dog" + }, + "zones": { + "hanche": { + "id": "hanche", + "name_fr": "Hanche (coxo-fémorale)", + "name_en": "Hip joint", + "categories": [ + { + "id": "dysf", + "name_fr": "Dysfonctions ostéopathiques", + "name_en": "Osteopathic dysfunctions", + "children": [ + { + "id": "compression", + "name_fr": "Compression articulaire", + "name_en": "Joint compression", + "description_fr": "Restriction de mobilité dans plusieurs plans" + }, + { + "id": "instabilite", + "name_fr": "Instabilité", + "name_en": "Instability", + "requires_vet_referral": true, + "sources": [ + { + "type": "journal", + "citation": "Smith et al., 2024", + "url": "https://example.com/paper" + } + ] + } + ] + } + ] + } + } +} +``` + +--- + +## Validation rules + +- Every required `string` field must be non-empty (`z.string().min(1)`). +- `url` fields must parse via `z.string().url()`. +- Recursion through `children` is `z.lazy` — depth is unbounded. +- A bad JSON throws a Zod error at `pathologies.ts` import time, with a + path pointing at the offending node — the editor never starts with a + half-valid catalog. + +--- + +## How selections become reports + +When the practitioner toggles a leaf checkbox, the picker emits a +`Finding`: + +```ts +{ + zoneId: "", + path: ["", "", ..., ""], + labelFrSnapshot: "", + labelEnSnapshot: "", + requiresVetReferral?: true +} +``` + +The snapshot fields freeze the label so already-exported reports stay +legible even if the catalog is later edited or renamed. The `path` is +kept for future re-link / migration tooling but is never required to +re-render an existing report. + +In the PDF, findings are grouped by `zoneId` (one +`CONSTATS — ` section per zone) followed by a single +`CONSTATS LIBRES` section listing the free-text additions. + +--- + +## Authoring workflow + +1. Copy `src/domain/species/equine/pathologies.json` as a reference, + or scaffold a new species via `pnpm scaffold:species` (writes a + minimal valid skeleton). +2. Edit the JSON, respecting the schema above. +3. Run `pnpm dev` — Vite HMR reloads the module, Zod parses the new + tree, errors surface immediately on save. +4. The picker and PDF pick up changes without any code edit. + +For production deploys, ship the new JSON via the normal build pipeline +(`pnpm build`) — there is no runtime hot-reload outside the dev server. + +--- + +## Related schemas + +| File | Purpose | +| ------------------------------------------ | -------------------------------------------------------------------------- | +| `src/domain/schema/findings.ts` | Zod definitions: `FindingNode`, `ZoneFindings`, `SpeciesFindings`, `SourceRef` | +| `src/domain/schema/observation.ts` | `Finding` snapshot stored on an observation | +| `src/domain/species/equine/pathologies.json` | Authoritative reference catalog | +| `src/lib/zoneMatch.ts` | SVG zone label ↔ JSON zone name matcher |