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 commit9cf8a66. docs/PATHOLOGIES-FORMAT.md: - "PDF surface: snapshot label is prefixed ⚠" → "(!)" in two places (after WinAnsi hotfix143fdc3). 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.
436 lines
19 KiB
Markdown
436 lines
19 KiB
Markdown
# 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.
|