docs(docs): add anatomical audit of existing SVG, catalog and report systems

Read-only technical audit before the SaaS redesign: 13 reports,
a logical anatomical-sheet JSON built from real horse data, verbatim
copies of the 52 relevant source files, and a self-contained ZIP.
This commit is contained in:
bastien committed 2026-10-06 23:51:35 +02:00
1 parent 83e40af99b
commit e471d41c6b
70 files changed
+22075

No files matched your search

@@ -0,0 +1,230 @@
# Adding a New Species
Faunosteo ships with one species (`equine`). Adding a new one is
mostly authoring work — anatomy SVGs and a findings JSON — backed by a
small amount of boilerplate that the project can scaffold for you.
> Throughout this document, replace `<id>` with the new species'
> kebab-case id (e.g. `canine`, `feline`, `bovine`).
---
## Quick start — `pnpm scaffold:species`
```bash
pnpm scaffold:species
```
The interactive prompt asks for:
- species id (kebab-case, e.g. `canine`),
- French and English display labels,
- the asset folder under `public/species/` (defaults to the id),
- the main SVG filename,
- zero or more detail-popup SVG paths (mapped by `data-anno-opens-detail` key),
- the vertebral formula (C / T / L / S / Cd).
It then writes:
```
src/domain/species/<id>/
index.ts ← SpeciesManifest with `export default`
vertebrae.ts ← VertebralFormula constant
pathologies.ts ← parses pathologies.json via SpeciesFindingsSchema
pathologies.json ← minimal valid catalog skeleton
public/species/<assetFolder>/ (directory created, empty)
```
The script refuses to clobber existing files, so it is safe to rerun.
After scaffolding, drop the anatomy SVGs into the `public/species/...`
folder, fill in `pathologies.json`, and the species shows up
automatically in the species picker — see "How auto-discovery works"
below.
---
## How auto-discovery works
`src/domain/species/registry.ts` no longer hard-codes species. It uses
Vite's `import.meta.glob`:
```ts
const modules = import.meta.glob<{ default: SpeciesManifest }>(
'./*/index.ts',
{ eager: true },
)
```
Every `src/domain/species/<id>/index.ts` that **default-exports** a
`SpeciesManifest` is picked up at build time and registered by its
`manifest.id`. Duplicates are warned about and the first one wins.
What this means in practice:
- **No registry edit needed.** Drop a properly-structured species
folder and it appears in `AnimalForm`, `getSpecies(id)`, the editor,
and the PDF exporter.
- **The `id` must be unique.** Two folders default-exporting manifests
with the same `id` triggers a console warning and the later module
is ignored.
- **A missing default export is silent.** If you forget
`export default`, the species is invisible. The scaffold script
emits the default export for you.
---
## Manual setup (without the script)
The scaffold script just writes the files below. If you'd rather do it
by hand, the same workflow applies — make sure your `index.ts`
default-exports the manifest so auto-discovery sees it.
### 1. Author the anatomy SVGs
All SVG assets must conform to
[`docs/ANATOMY-SVG-CONVENTION.md`](./ANATOMY-SVG-CONVENTION.md). Every
clickable element must carry:
| Attribute | Required | Notes |
| -------------------------- | -------- | -------------------------------------------------------------------------------------- |
| `data-anno-id` | yes | Stable identifier, unique within the SVG. The renderer treats it as opaque. |
| `data-anno-name-fr` | yes | French anatomical label. |
| `data-anno-name-en` | yes | English anatomical label. |
| `data-anno-category` | yes | Must be one of the 7 valid values defined in [`ANATOMY-SVG-CONVENTION.md`](./ANATOMY-SVG-CONVENTION.md) (`articulation`, `charniere`, `spine-zone`, `os`, `os-overlay`, `head`, `cadran-crane`). Parser throws `SvgConventionError` on unknown values. |
| `data-anno-opens-detail` | no | Key of a detail popup SVG. Must match a key in the manifest's `details` map. |
| `data-anno-special` | no | Behavior hint. `vertebral-precision` opens the VertebraPicker on click. |
Drop the SVGs into:
```
public/species/<assetFolder>/<Main>.svg
public/species/<assetFolder>/<Main>_<detail>.svg
```
The `public/` prefix is implicit at runtime — the manifest references
files by absolute path starting with `/species/...`.
### 2. Create the species manifest
`src/domain/species/<id>/index.ts`:
```ts
import type { SpeciesManifest } from '@/domain/species/types'
import { CANINE_VERTEBRAL_FORMULA } from './vertebrae'
const canine: SpeciesManifest = {
id: 'canine',
labelFr: 'Chien',
labelEn: 'Dog',
mainSvg: '/species/canine/Dog.svg',
details: {
head: '/species/canine/Dog_head.svg',
},
vertebralFormula: CANINE_VERTEBRAL_FORMULA,
findings: () => import('./pathologies'),
}
export default canine // <- required for auto-discovery
```
`details` keys must match every distinct `data-anno-opens-detail`
attribute used in the main SVG. There is no filename convention — the
mapping is explicit through this object.
### 3. Provide the vertebral formula
`src/domain/species/<id>/vertebrae.ts`:
```ts
import type { VertebralFormula } from '@/domain/species/types'
export const CANINE_VERTEBRAL_FORMULA: VertebralFormula = {
C: 7,
T: 13,
L: 7,
S: 3,
Cd: 20,
}
```
Cap `Cd` at a sensible maximum (caudal counts vary heavily across
individuals).
### 4. Provide the findings catalog
Two files:
`src/domain/species/<id>/pathologies.json` — authored tree of zones,
categories, sub-categories and leaves. The shape is defined by
`src/domain/schema/findings.ts`, and the full authoring contract
(structural rules, taxonomy patterns, v2.0 vet-referral policy,
changelog) lives in
[`docs/PATHOLOGIES-FORMAT.md`](./PATHOLOGIES-FORMAT.md). The scaffold
script ships a minimal skeleton; populate the `zones` map by mirroring
the equine reference at `src/domain/species/equine/pathologies.json`.
`src/domain/species/<id>/pathologies.ts` — loader:
```ts
import {
SpeciesFindingsSchema,
type SpeciesFindings,
} from '@/domain/schema/findings'
import data from './pathologies.json'
const FINDINGS: SpeciesFindings = SpeciesFindingsSchema.parse(data)
export default FINDINGS
```
The Zod parse runs on first import and **fails fast** if the JSON
violates the schema (missing labels, malformed children, empty
disclaimer, etc.). That is your validation gate — there is no separate
lint step to run.
---
## Updating the findings JSON
The JSON is bundled into the app at build time, so updates flow
through normal dev/deploy paths:
- **In dev (`pnpm dev`)**: edit the JSON, Vite HMR reloads the module,
the editor picks up the new tree on the next interaction. A bad
edit fails loudly because the Zod parse runs at module load.
- **In prod**: rebuild and redeploy. The findings tree is statically
imported and there is no backend serving JSON at runtime.
Snapshots in already-exported PDFs are unaffected — observations carry
`labelFrSnapshot` / `labelEnSnapshot` copied at selection time, so
catalog edits cannot retroactively rewrite past reports.
---
## How findings link back to clicked SVG zones
The catalog keys observations by stable JSON zone ids (e.g.
`sphenoid`). SVG hitboxes carry opaque generator ids
(e.g. `point-mpbymcln`). The bridge is the **FR/EN label** parsed from
`data-anno-name-fr` / `data-anno-name-en`, matched against the JSON's
`zone.name_fr` / `zone.name_en` via the fuzzy matcher in
`src/lib/zoneMatch.ts`.
In practice you do not need to make the SVG ids meaningful; you just
need each zone's label to match its catalog entry under normalization
(lowercase + strip accents + drop non-alphanumerics) or be close
enough that Levenshtein finds it.
---
## CI gate before merging
```bash
pnpm lint
pnpm typecheck
pnpm test:run
pnpm build
```
All four must be green before the new species lands.
@@ -0,0 +1,179 @@
# Anatomy SVG Convention
**Status**: Source of truth. All SVG assets and parser code must conform.
---
## Required data attributes
Every clickable zone element must carry all four attributes:
| Attribute | Type | Description |
|---|---|---|
| `data-anno-id` | `string` | Stable kebab-case identifier. Unique per bone. |
| `data-anno-name-fr` | `string` | French anatomical label (e.g. "Colonne cervicale"). |
| `data-anno-name-en` | `string` | English anatomical label (e.g. "Cervical spine"). |
| `data-anno-category` | `BoneCategory` | One of the seven valid categories below. |
## Optional data attributes
| Attribute | Type | Description |
|---|---|---|
| `data-anno-opens-detail` | `string` | Id of the detail popup SVG to open on click. Key must exist in `SpeciesManifest.details`. |
| `data-anno-special` | `string` | Free-form behavior hint consumed by the app. Known value: `vertebral-precision` → clicking the zone opens VertebraPicker. Opaque to the parser; new values can be added without code changes (just unused). |
| `data-anno-lateral` | `string` | Laterality hint: `bilateral` (zone has left/right instances, e.g. knee) or `unpaired` (no laterality). Default when absent: `unpaired`. Used by the report editor to prompt side selection on bilateral zones. |
---
## Valid categories
| Value | Meaning |
|---|---|
| `articulation` | Joint space |
| `charniere` | Junctional / transitional zone |
| `spine-zone` | Vertebral region bloc — click opens VertebraPicker |
| `os` | Single bone |
| `os-overlay` | Overlapping bone layer |
| `head` | Head region (main SVG entry point for detail popup) |
| `cadran-crane` | Cranial quadrant (inside detail popup) |
---
## Rendering patterns
### Pattern 1 — Hitbox + visible twin
Used for: `articulation`, `charniere`, `os-overlay`, `head`.
Two sibling SVG elements share the **same** `data-anno-id`:
```xml
<!-- hitbox: transparent fill, receives pointer events -->
<polygon
data-anno-id="cervical-spine"
data-anno-name-fr="Colonne cervicale"
data-anno-name-en="Cervical spine"
data-anno-category="spine-zone"
class="bone-hitbox"
fill="transparent"
style="pointer-events: all; cursor: pointer"
/>
<!-- visible twin: colored fill, no pointer events -->
<polygon
data-anno-id="cervical-spine"
class="bone-visible"
fill="#c8d8e8"
style="pointer-events: none"
/>
```
- Hitbox must have `class` containing `hitbox` (case-insensitive substring).
- Visible twin must have `class` containing `visible`.
- Order in DOM does not matter — parser groups by `data-anno-id`.
### Pattern 2 — Single element
Used for: `spine-zone`, standalone `head` zones inside detail SVGs.
One polygon carries everything:
```xml
<polygon
data-anno-id="thoracic-t1-t18"
data-anno-name-fr="Thoracique T1-T18"
data-anno-name-en="Thoracic T1-T18"
data-anno-category="spine-zone"
fill="#d4e8d4"
style="pointer-events: all; cursor: pointer"
/>
```
---
## Parser behavior (`src/anatomy/svgConvention.ts`)
1. `parseSvgBones(svgRoot)` — walks all elements with `data-anno-id`.
2. Groups by `data-anno-id` → one `Bone` per id.
3. For each group, validates required attributes.
4. Classifies elements into `hitboxEls` (class contains "hitbox") and `visibleEls` (class contains "visible"). Elements in neither class land in `visibleEls` by default.
5. Returns `Map<string, Bone>`.
6. Throws `SvgConventionError(message, boneId, missingAttribute)` on first violation.
### Validated rules
- `data-anno-name-fr` must be non-empty.
- `data-anno-name-en` must be non-empty.
- `data-anno-category` must be one of the seven valid values.
- If `data-anno-opens-detail` is present, the value must be a non-empty string (runtime check against species manifest happens in the canvas component).
---
## Click handling (delegated listener)
A single `click` listener on the root `<svg>` element:
```
event.target → walk up ancestors → find data-anno-id
→ if data-anno-opens-detail present → emit requestDetail({id})
→ else if data-anno-special === 'vertebral-precision' →
add zone to current observation (if absent) and open VertebraPicker
→ else → toggle bone in current observation
```
Never attach per-element click listeners — the SVG may have thousands of elements.
Note: `data-anno-category` is opaque to click handling — branching is
driven by `data-anno-opens-detail` and `data-anno-special` only.
---
## Zone visual states
Applied as `data-state` attribute on all elements sharing a `data-anno-id`:
| `data-state` | Condition | Visual |
|---|---|---|
| `current` | Bone is in the active observation | Solid accent fill |
| `linked` | Bone is in another (non-active) observation | Faded dashed border, accent color of owning obs |
| `multi` | Bone is in ≥2 observations | Striped CSS background pattern + indicator badge |
| *(absent)* | Default / unselected | SVG original fill |
Accent colors cycle through 6 HSL tones (defined in `src/styles/tokens.css`):
terracotta → sauge → bleu canard → ambre → prune → ocre.
---
## Detail popup mechanism
When a zone has `data-anno-opens-detail="head"`:
1. Canvas emits `requestDetail({ id: 'head' })`.
2. `DetailModal` resolves the path via `SpeciesManifest.details['head']`.
3. Loads and renders the detail SVG inline.
4. Clicks inside the modal add `ObservationZone` entries with `detailSourceId: 'head'`.
5. The "entry" zone itself (the polygon that triggered the popup) is **never** persisted.
---
## Vertebra picker trigger
When a bone has `data-anno-special="vertebral-precision"`, clicking it adds the
zone to the active observation (if absent) and opens `VertebraPicker`:
- Region tabs: Cervicales (C1–C7), Thoraciques (T1–T18), Lombaires (L1–L6), Sacrales (S1–S5), Caudales (Cd1–Cd18).
- Multi-select chip grid, ≥40 px touch targets.
- Per-region "Tout cocher / Tout décocher".
- Stored as `vertebrae: Vertebra[]` on `ObservationZone`, replacing the bloc semantically.
- PDF prints precise vertebrae: "T12, T15" instead of the zone label.
---
## Adding a new SVG
1. Place SVG at `public/species/<speciesId>/<filename>.svg`.
2. Ensure every clickable element has the four required attributes.
3. Use Pattern 1 or Pattern 2 consistently per category.
4. Add to `SpeciesManifest.details` if it is a detail popup SVG.
5. Run `pnpm test:run` — the convention parser tests will catch missing attributes.
6. See `docs/ADDING-A-SPECIES.md` for adding a full new species.
@@ -0,0 +1,435 @@
# 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.
**Current schema version: `"2.0"`** — see [Changelog](#changelog) for the
breaking changes from v1.x.
---
## Scope (legal périmètre — important)
Catalog entries describe **strictly what an animal osteopath may write
in a bilan** under French law:
- ✅ Palpated osteopathic dysfunctions (SSB lesions, sutures, intra-osseous)
- ✅ Mobility restrictions and muscular tensions observed
- ✅ Visible mechanical asymmetries
- ✅ Clinical observations and consultation motives reported by the owner
- ✅ Anamnesis (reported factors)
- ❌ Medical diagnoses (Cushing, OCM, arthrosis, ankylosis…)
- ❌ Organic pathologies requiring imaging / blood work / biopsy
- ❌ Anything requiring medical, surgical or pharmaceutical intervention
The osteopath may **suspect** and **redirect to a veterinarian** but
never poses a medical diagnosis. Two mechanisms enforce this in data:
the root `scope_disclaimer` field (UI surface) and the boolean
`requires_vet_referral` on sensitive leaves (logic surface — see below).
---
## Top-level shape
```json
{
"schema_version": "2.0",
"scope_disclaimer": "string non vide — affiché 1× par session dans l'éditeur",
"species": {
"id": "equine",
"name_fr": "Cheval",
"name_en": "Horse",
"notes": "optional — clinical context specific to the species"
},
"zones": {
"<zoneKey>": { ... ZoneFindings ... }
}
}
```
| Field | Type | Required | Notes |
| ------------------ | ------ | -------- | ----------------------------------------------------------- |
| `schema_version` | string | yes | non-empty, bump on breaking changes; current `"2.0"` |
| `scope_disclaimer` | string | yes | non-empty, shown once per session via `osteo:disclaimer-shown` flag |
| `species.id` | string | yes | should match the `SpeciesManifest.id` in the manifest |
| `species.name_fr` | string | yes | |
| `species.name_en` | string | yes | |
| `species.notes` | string | no | free-text species context; currently stripped by Zod (extend schema before relying on it) |
| `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).
**SVG ↔ JSON link is via labels, not IDs.** The runtime matches a
clicked SVG element to a JSON zone by comparing `data-anno-name-fr` /
`data-anno-name-en` against `zone.name_fr` / `zone.name_en`. The v2.0
authoring rule prescribes **strict equality** (case + accents + spaces);
`src/lib/zoneMatch.ts` keeps a normalize+Levenshtein fallback as a
safety net but content should not depend on it.
**Zone ordering.** Zones appear in the `zones` dictionary in
**cranio-caudal order** (head → tail). JS object insertion order is
preserved by modern engines for non-numeric keys, and the picker relies
on this — never sort `zones` alphabetically.
---
## 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 | **must equal** SVG `data-anno-name-fr` exactly |
| `name_en` | string | yes | **must equal** SVG `data-anno-name-en` exactly |
| `categories` | `FindingNode[]` | yes | three standardized buckets (see below) |
### Three standardized categories per zone
Each zone exposes exactly three top-level categories in this order:
1. **Dysfonctions ostéopathiques** — palpation / manipulation, the core
work. `id` is zone-prefixed (e.g. `atm-dysfunctions`).
2. **Observations / motifs de consultation** — what the owner reports or
what is observed (varies per species). `id` is zone-prefixed (e.g.
`atm-observations`).
3. **Anamnèse / facteurs rapportés** — context. `id` is always plain
`anamnesis` (not zone-prefixed).
### Five taxonomy patterns for `*-dysfunctions`
The dysfunctions sub-tree follows one of five patterns derived from the
zone type — degrees of freedom enumerated, muscles by insertion, sutures
by adjacency:
| Pattern | Zones (horse) | Sub-categories |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Cranial (SSB axis) | `sphenoid`, `ssb` | `physiological` · `traumatic` · `intraosseous` · `sutures` |
| Cranial (peripheral) | `parietal`, `frontal`, `temporal`, `occipital` | `mobility` · `intraosseous` · `sutures` |
| Articular | `atm`, `shoulder`, `elbow`, `fore-fetlock`, `hind-fetlock`, `hock`, `hip`, `stifle`, `sacroiliac`, `fore-sesamoids` | `articular` · `muscular` · `mechanical` |
| Vertebral hinge | `c0-c1`, `c7-t1`, `t18-l1`, `l6-s1` | `segmental` · `muscular` · `mechanical` |
| Vertebral region | `cervical`, `thoracic`, `lumbar`, `sacral`, `caudal` | `segmental` · [`costovertebral`] · `group` · `muscular` · `mechanical` |
Special cases: `hyoid` (mobility of the hyoid apparatus / associated
muscles / intra-osseous), `thoracic` (extra `costovertebral`
sub-category).
---
## FindingNode (recursive)
```json
{
"id": "tensions",
"name_fr": "Tensions des muscles masticateurs",
"name_en": "Masticatory muscle tensions",
"description_fr": "optionnel — différentiel clinique spécifique uniquement",
"description_en": "optional — currently authored FR-only",
"requires_vet_referral": true,
"sources": [ { ... SourceRef ... } ],
"children": [ { ... FindingNode ... } ]
}
```
| Field | Type | Required | Notes |
| ----------------------- | --------------- | -------- | -------------------------------------------------- |
| `id` | string | yes | unique within its **siblings only** (NOT globally) |
| `name_fr` | string | yes | |
| `name_en` | string | yes | |
| `description_fr` | string | no | see policy below (v2.0) |
| `description_en` | string | no | reserved — current catalog FR-only |
| `requires_vet_referral` | boolean | no | **source of truth** for the vet flag (v2.0) |
| `sources` | `SourceRef[]` | no | citations, see below |
| `children` | `FindingNode[]` | no | absent or `[]` → leaf (selectable checkbox) |
### Leaf vs intermediate
```ts
const isLeaf = (n) => !n.children || n.children.length === 0
```
- `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.
### Structural constraints (authoring rules)
- Maximum depth: **4 levels** (category → sub-category → [sub-sub-category] → leaf).
- Every intermediate node has **at least 2 children**.
- `requires_vet_referral` is **only** set on leaves, never on categories.
- IDs are unique among **siblings only**, not globally — `articular`,
`muscular`, `mechanical`, `anamnesis`, `trauma-direct` legitimately
repeat across zones. Any `findNodeById` helper must therefore be
scoped to a single zone root.
### `requires_vet_referral` and `description_fr` (v2.0)
Since v2.0 the boolean `requires_vet_referral: true` is the **only**
source of truth for the vet-orientation flag. The generic
"orienter vers vétérinaire" wording has been **purged** from
`description_fr` on leaves where the boolean alone suffices.
`description_fr` survives on a vet-flagged leaf **only** when it adds a
clinical differential the boolean cannot carry — a specific cause to
rule out (neurological, sinus, ligament, rotular, cutaneous, osseous,
traumatic…). Example:
```json
{
"id": "deglutition-difficulty",
"name_fr": "Difficulté de déglutition",
"name_en": "Swallowing difficulty",
"description_fr": "Une difficulté de déglutition impose d'écarter une cause médicale/neurologique : orienter vers vétérinaire avant intervention ostéo.",
"requires_vet_referral": true
}
```
**Consumer rule:**
```ts
const requiresVetReferral = (n) => n.requires_vet_referral === true
```
**Breaking change from v1.x.** Any consumer that detected the flag by
scanning `description_fr.includes('vétérinaire')` will silently miss
vet leaves on a v2.0 catalog (25 leaves had that text removed in the
v2.0 purge). All in-tree consumers (`FindingsTreePicker`,
PDF `observationPage`) already key off the boolean.
Picker surface: a ⚠ badge is shown next to vet-flagged leaves. PDF
surface: the snapshot label is prefixed `(!)` in the
`CONSTATS — <ZONE>` section (the picker `⚠` cannot be rendered until
the PDF font path migrates from WinAnsi StandardFonts to TTF). If a
`description_fr` is also present, it is rendered as an additional
context line below the children list.
---
## 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 |
Sources are optional in v2.0; recommended on leaves carrying clinical
weight (vet-referral leaves, differential descriptions).
---
## Minimal complete example
```json
{
"schema_version": "2.0",
"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": "hanche-dysfunctions",
"name_fr": "Dysfonctions ostéopathiques de la hanche",
"name_en": "Hip osteopathic dysfunctions",
"children": [
{
"id": "articular",
"name_fr": "Restrictions de mobilité articulaire",
"name_en": "Joint mobility restrictions",
"children": [
{
"id": "compression",
"name_fr": "Compression articulaire",
"name_en": "Joint compression"
},
{
"id": "laxite",
"name_fr": "Laxité perçue",
"name_en": "Perceived laxity",
"description_fr": "Une laxité perçue peut évoquer une atteinte ligamentaire : orienter vers vétérinaire avant intervention ostéo.",
"requires_vet_referral": true
}
]
}
]
},
{
"id": "hanche-observations",
"name_fr": "Observations / motifs de consultation",
"name_en": "Observations / consultation motives",
"children": [ /* ... */ ]
},
{
"id": "anamnesis",
"name_fr": "Anamnèse / facteurs rapportés",
"name_en": "Anamnesis / reported factors",
"children": [ /* ... */ ]
}
]
}
}
}
```
---
## 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 at the
schema level (authoring rule caps it at 4).
- Unknown fields on objects are **silently stripped** by Zod's default
`z.object` behaviour. Extra metadata (e.g. `species.notes`,
custom per-leaf `metadata`) survives in the JSON file but is not
surfaced at runtime until the schema declares it.
- 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: "<the zone key>",
path: ["<category id>", "<sub id>", ..., "<leaf id>"],
labelFrSnapshot: "<leaf.name_fr at click time>",
labelEnSnapshot: "<leaf.name_en at click time>",
requiresVetReferral?: true
}
```
The snapshot fields freeze the label so already-exported reports stay
legible even if the catalog is later edited or renamed (BDR-010). 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 — <ZONE>` section per zone) followed by a single
`CONSTATS LIBRES` section listing the free-text additions. Vet-referral
leaves are prefixed with `(!)` in the rendered list.
---
## Current `horse.json` stats
| Metric | Count |
| --------------------------------------- | ----------- |
| Zones (9 head + 17 body) | 26 |
| Total nodes | 792 |
| Leaves | 612 |
| Leaves with `requires_vet_referral` | 41 |
| File size (indented) | ~177 KB |
---
## 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 and structural rules above.
3. Ensure every `zone.name_fr` / `zone.name_en` matches the SVG
`data-anno-name-fr` / `data-anno-name-en` exactly (case included).
4. Run `pnpm dev` — Vite HMR reloads the module, Zod parses the new
tree, errors surface immediately on save.
5. 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 (v2.0, 26 zones) |
| `src/lib/zoneMatch.ts` | SVG zone label ↔ JSON zone name fallback matcher |
---
## Changelog
### v2.0 (current) — breaking
- `requires_vet_referral` boolean becomes the **sole source of truth**
for the vet-orientation flag.
- Generic vet wording purged from `description_fr` on 25 leaves where
the boolean already conveyed the same info. `description_fr` survives
on the 16 leaves carrying a clinical differential (cause to rule out).
- Consumer helper simplified to `node.requires_vet_referral === true`.
Any prior `description_fr.includes('vétérinaire')` fallback **must
migrate** to the boolean.
- Horse coverage extended placeholder 3 zones → full 26 zones (9 head +
17 body), 792 nodes, 612 leaves.
### v1.2
- Added the optional boolean `requires_vet_referral` on leaves
(still co-existed with vet wording in `description_fr` for
backward compatibility — removed in v2.0).
- Documented SVG ↔ JSON link via `name_fr` / `name_en` strict match
(not `zones.<id>` ↔ `data-anno-id`).
- Documented the 5 dysfunctions taxonomy patterns.
- Explicit cranio-caudal zone ordering.
- Explicit structural constraints (depth ≤ 4, ≥ 2 children per
intermediate, sibling-scoped ID uniqueness).
### v1.1
- Removed medical diagnoses (OCM, Cushing, hyperthyroidism, arthrosis,
ankylosis…) — out of legal scope.
- Reformulated diagnoses as observations ("Suite de X", "X rapporté(e)").
- Added `scope_disclaimer` at the root + initial `description_fr`
vet-orientation hints on sensitive motives.
- Standardized 3 categories per zone (Dysfunctions / Observations /
Anamnesis).
### v1.0
- Initial schema mixing osteopathic dysfunctions with medical
diagnoses — non-compliant with French legal scope, corrected in v1.1.