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:
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.
|
||||
Reference in new issue
Block a user