Files
faunosteo/docs/PATHOLOGIES-FORMAT.md
T
Bastien Chanot 8385b49bbe docs: sync drift after catalog v2.0 + i18n + WinAnsi hotfix
doc-syncer audit applied 10 AUTO patches and 1 HUMAN reword (#5)
across the doc set.

README.md:
- Test count "7 tests pass on skeleton" / "88 tests across 23 files"
  → "155 tests" / "155 tests across 29 files".
- Reword "Observation builder" bullet + add hierarchical findings
  tree + browser-detected locale bullets (HUMAN #5).
- Status paragraph: pathology DB "intentionally empty" → full
  26-zone v2.0 catalog (792 nodes, 612 leaves, 41 vet leaves).
- Documentation section: add PATHOLOGIES-FORMAT.md link; tidy the
  DEPLOY.md mention (DEPLOY.md itself comes in the next commit).

CLAUDE.md:
- Architecture block: "embedFonts (Inter body + Fraunces heading)"
  → reality (Helvetica + TimesRoman / WinAnsi StandardFonts; TTF
  Inter/Fraunces planned).
- PDF convention: "Fonts are TTF" → "Fonts are StandardFonts
  (Helvetica/TimesRoman, WinAnsi)" with the ASCII-surrogate caveat.
- Folder map: add src/anatomy/labels.ts, include zoneMatch.ts in
  src/lib/{...}.ts.
- i18n: locale default "fr" → "navigator-detected fr/en, or 'fr'
  if no match" to match commit 9cf8a66.

docs/PATHOLOGIES-FORMAT.md:
- "PDF surface: snapshot label is prefixed ⚠" → "(!)" in two
  places (after WinAnsi hotfix 143fdc3). Picker ⚠ statement
  kept — browser renders U+26A0 natively.

docs/ADDING-A-SPECIES.md:
- data-anno-category: "Free-form" → enum of 7 valid values per
  ANATOMY-SVG-CONVENTION.md; parser throws SvgConventionError on
  unknown values.
- Section 4 (findings catalog): cross-link to
  docs/PATHOLOGIES-FORMAT.md so authors find the v2.0 contract.
2026-05-21 04:13:13 +02:00

436 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.