Files
faunosteo/docs/faunosteo-audit/02-anatomical-sheet.md
T
bastien e471d41c6b 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.
2026-10-06 23:51:35 +02:00

284 lines
22 KiB
Markdown

# 02. La "fiche anatomique" actuelle, reconstruite
Périmètre : ce que serait aujourd'hui une fiche anatomique dans Faunosteo (sections 2 et 8 du brief), à partir du code et des données réelles du cheval. Aucun concept nommé "fiche anatomique" n'existe dans le code. Ce document reconstruit l'ensemble implicite.
## Sources lues
- `src/domain/species/types.ts`, `src/domain/species/registry.ts`, `src/domain/species/equine/{index,vertebrae,pathologies}.ts`
- `src/domain/schema/{findings,observation,report}.ts`
- `src/anatomy/{types,svgConvention,svgLoader,labels}.ts`
- `src/lib/{zoneMatch,spineZones}.ts`
- `src/app/routes/EditorRoute.tsx`, `src/components/observation/ObservationCard.tsx`
- `public/species/equine/Horse.svg`, `public/species/equine/Horse_head.svg`, `public/species/equine/pathologies.json`
- `docs/ANATOMY-SVG-CONVENTION.md`, `docs/PATHOLOGIES-FORMAT.md` (lus, mais le code fait foi quand ils divergent)
Le fichier `anatomical-sheet-example.json` à côté de ce document contient la même reconstruction sous forme de données, avec toutes les annotations et toutes les zones du catalogue.
## 1. Ce qui tient lieu de fiche anatomique aujourd'hui
FACTUEL. Une "espèce" est assemblée à partir de quatre sources sans objet commun :
| Composant | Fichier | Nature | Chargement |
|---|---|---|---|
| Manifeste | `src/domain/species/equine/index.ts:4-14` | objet TS `SpeciesManifest` compilé dans le bundle | `import.meta.glob` au build (`src/domain/species/registry.ts:16`) |
| Formule vertébrale | `src/domain/species/equine/vertebrae.ts:7-13` | constante TS | importée par le manifeste |
| SVG principal | `public/species/equine/Horse.svg` | fichier statique | `fetch` + `DOMParser` à l'ouverture de l'éditeur (`EditorRoute.tsx:135`) |
| SVG de détail | `public/species/equine/Horse_head.svg` | fichier statique | `fetch` préchargé pour chaque clé de `details` (`EditorRoute.tsx:143`) |
| Catalogue de constats | `src/domain/species/equine/pathologies.json` | JSON importé et validé Zod au boot (`pathologies.ts:11`) | `species.findings()` lazy |
| Copie du catalogue | `public/species/equine/pathologies.json` | copie octet pour octet (md5 identique) | lue seulement par `public/pathology-editor.html:790` |
DEDUIT : la fiche anatomique est donc "le manifeste + les fichiers qu'il référence + le catalogue qu'il importe". Elle n'a ni identifiant propre, ni version, ni date, ni auteur. Son identité est la chaîne `'equine'` répétée dans `index.ts:5`, `pathologies.json` (`species.id`) et `NewReportRoute.tsx:20`.
## 2. Inventaire composant par composant
| Composant demandé | Existe ? | Forme réelle | Où | Statut |
|---|---|---|---|---|
| SVG principal | oui | `mainSvg: '/species/equine/Horse.svg'`, viewBox `0 0 2073.4 1629.4` | `index.ts:8`, `Horse.svg` ligne 2 | FACTUEL |
| SVG de détail | oui, un seul | `details: { head: '/species/equine/Horse_head.svg' }`, viewBox `60 100 500 380` | `index.ts:9-11` | FACTUEL |
| Relations entre SVG | oui, unidirectionnelle | attribut `data-anno-opens-detail="head"` sur un polygone du SVG principal + clé `details.head` du manifeste | `Horse.svg` (élément `zone-mpby55kd`), `index.ts:10` | FACTUEL ; le détail ne connaît pas son parent (DEDUIT : aucun attribut inverse) |
| Points anatomiques | oui | `<circle>` en paire hitbox (fill `transparent`, r+12) + visible, même `data-anno-id` préfixé `point-` | `Horse.svg` 12 points, `Horse_head.svg` 9 points | FACTUEL |
| Zones (surfaces) | oui | `<polygon>` seul, `data-anno-id` préfixé `zone-` | `Horse.svg` 5 polygones colonne + 1 déclencheur | FACTUEL |
| Distinction point / zone côté application | non | le parser regroupe tout élément `[data-anno-id]` en un `Bone` sans regarder la balise | `svgConvention.ts:46-52` | FACTUEL |
| Catégories SVG | oui, libres | `data-anno-category`, chaîne opaque ; valeurs réelles `articulations`, `os`, `charni-res-vert-brales`, `zone-colonne`, `cadrans-du-cr-ne` | `svgConvention.ts:52`, `types.ts:9` | FACTUEL |
| Nom lisible de catégorie SVG | partiel | `data-anno-category-name` sur 18 éléments, non lu par le parser, lu par l'éditeur SVG | `Horse.svg`, `SvgEditorRoute.tsx:640` | FACTUEL |
| Sous-catégories SVG | non | aucun attribut de hiérarchie | | FACTUEL |
| Vertèbres | oui | régions `C|T|L|S|Cd` codées dans `VertebralRegionSchema` + comptes dans `vertebralFormula` ; déclenchées par `data-anno-special="vertebral-precision"` | `observation.ts:7`, `vertebrae.ts`, `EditorRoute.tsx:309` | FACTUEL |
| Latéralité | oui | `data-anno-lateral="bilateral"` sur 9 points ; valeur `unpaired` documentée mais jamais présente dans les SVG | `svgConvention.ts:56`, `Horse.svg` | FACTUEL |
| Paramètres spéciaux | oui, un seul utilisé | `data-anno-special`, seule valeur consommée `vertebral-precision` ; `joint-detail` proposé par l'éditeur SVG mais ignoré par l'app | `types.ts:28-35`, `SvgEditorRoute.tsx:296-299` | FACTUEL |
| Catalogue de constats | oui | `SpeciesFindings` : `schema_version`, `scope_disclaimer`, `species`, `zones` (record) | `findings.ts:56-65` | FACTUEL |
| Pathologies | oui, sous le nom "findings" | arbre `FindingNode` récursif, feuilles cochables | `findings.ts:23-45` | FACTUEL |
| Observations / motifs de consultation | oui | 2e catégorie de chaque zone, id `<zone>-observations` | `pathologies.json` | FACTUEL (convention d'auteur, non imposée par Zod) |
| Anamnèse | oui | 3e catégorie de chaque zone, id `anamnesis` ; 3 variantes de contenu selon les zones | `pathologies.json` | FACTUEL |
| Métadonnées (auteur, date, licence) | non | aucune dans les SVG ni dans le JSON | | FACTUEL |
| Disclaimer | oui | `scope_disclaimer` racine, affiché une fois par session (`osteo:disclaimer-shown`) | `findings.ts:58`, `EditorRoute.tsx:33` | FACTUEL |
| Version | partiel | `schema_version: "2.0"` du catalogue ; `Report.version: 2` du bilan ; aucune version pour le SVG ni pour le manifeste | `pathologies.json`, `report.ts:18` | FACTUEL |
| Espèce | oui | `SpeciesManifest.id/labelFr/labelEn` + `species{id,name_fr,name_en}` dans le JSON, dupliqués | `index.ts:5-7`, `pathologies.json` | FACTUEL |
| Sources / citations | prévu, vide | `sources?: SourceRef[]` validé Zod ; 0 nœud en porte dans le catalogue réel | `findings.ts:15-19` | FACTUEL |
## 3. Homonymes à lever avant toute migration
Le mot "zone" a trois sens dans le code, et "catégorie" en a deux. Les confondre est la principale source d'ambiguïté du brief.
| Terme | Sens SVG | Sens catalogue | Sens bilan |
|---|---|---|---|
| zone | un `<polygon>` annoté, `data-anno-id` préfixé `zone-` (convention de l'éditeur SVG, `SvgEditorRoute.tsx:1353`) | une entrée `zones[<key>]` du JSON, avec `id`, `name_fr`, `name_en`, `categories` (`findings.ts:47-52`) | un `ObservationZone { boneId, detailSourceId?, vertebrae?, side? }` (`observation.ts:21-30`) |
| point | un `<circle>` annoté, `data-anno-id` préfixé `point-` (`SvgEditorRoute.tsx:1245`) | n'existe pas | n'existe pas : un point cliqué devient un `ObservationZone` comme un polygone |
| catégorie | `data-anno-category`, bucket visuel libre, 5 valeurs réelles | `categories[]`, premier niveau de l'arbre d'une zone, 3 par zone | n'existe pas ; le `Finding.path[0]` est l'id de catégorie catalogue |
| id | `data-anno-id` généré (`point-<base36 time>`), opaque | `zone.id`, lisible (`hip`), égal à la clé | `boneId` = `data-anno-id` ; `zoneId` = `zone.id` catalogue ; les deux coexistent dans une observation sans lien explicite |
DEDUIT : dans l'application de bilan, "point" et "zone" SVG sont strictement équivalents. La seule différence de comportement vient des attributs (`special`, `lateral`, `opens-detail`), pas de la géométrie.
## 4. Arbre logique de la fiche anatomique réelle (cheval)
```text
Fiche anatomique "equine" [concept implicite, DEDUIT]
├── identité
│ ├── id: "equine" src/domain/species/equine/index.ts:5
│ ├── labelFr: "Cheval" / labelEn: "Horse" index.ts:6-7
│ └── species {id,name_fr,name_en} dupliqué pathologies.json (racine)
├── version
│ ├── SVG : aucune [ABSENT]
│ ├── manifeste : aucune [ABSENT]
│ ├── catalogue : schema_version "2.0" pathologies.json
│ └── bilan : Report.version 2 src/domain/schema/report.ts:18
├── SVG principal /species/equine/Horse.svg index.ts:8
│ ├── viewBox "0 0 2073.4 1629.4"
│ ├── dessin anatomique (groupes <g> sans annotation, ~700 lignes)
│ └── <g id="osteo-overlays"> dernière ligne du fichier
│ ├── 12 points (circle hitbox + circle visible, même data-anno-id)
│ │ ├── 9 articulations bilatérales (épaule, coude, boulets, hanche, grasset, jarret, sacro-iliaque, sésamoïdes)
│ │ └── 3 charnières (C7-T1, T18-L1, L6-S1), catégorie charni-res-vert-brales
│ ├── 5 polygones zone-colonne, data-anno-special="vertebral-precision"
│ │ (cervicales, thoraciques, lombaires, sacrales, caudales)
│ └── 1 polygone déclencheur zone-mpby55kd
│ data-anno-opens-detail="head", sans name-fr/en, catégorie articulations
├── SVG de détail "head" /species/equine/Horse_head.svg index.ts:10
│ ├── même dessin que Horse.svg, viewBox "60 100 500 380" [DEDUIT : copie recadrée]
│ └── <g id="osteo-overlays">
│ ├── 5 points cadrans-du-cr-ne (pariétal, frontal, sphénoïde, temporal, occipital)
│ ├── 2 points articulations (ATM, SSB)
│ ├── 1 point os (hyoïde)
│ └── 1 point charni-res-vert-brales (C0-C1)
├── relations entre SVG
│ └── zone-mpby55kd --opens-detail="head"--> details.head [codée à la main, unidirectionnelle]
├── configuration vertébrale
│ ├── formule C7 T18 L6 S5 Cd18 vertebrae.ts:7-13
│ └── régions autorisées C|T|L|S|Cd observation.ts:7 (schéma, pas le manifeste)
├── catalogue de constats pathologies.json (26 zones, 792 nœuds, 612 feuilles, 41 vet, 0 sources)
│ ├── scope_disclaimer (texte légal, affiché 1 fois/session)
│ ├── zones (record ordonné cranio-caudal, 26 clés)
│ │ └── <zone> {id, name_fr, name_en}
│ │ ├── categories[0] "<zone>-dysfunctions" (arbre à 2 niveaux : sous-catégorie > feuille)
│ │ ├── categories[1] "<zone>-observations" (feuilles directes ou 1 sous-niveau)
│ │ └── categories[2] "anamnesis" (feuilles directes)
│ └── feuille {id, name_fr, name_en, description_fr?, requires_vet_referral?}
├── lien SVG <-> catalogue [CALCULÉ, jamais stocké]
│ └── matchZoneFindings({fr: bone.fr, en: bone.en}, zones) ObservationCard.tsx:134
│ (égalité stricte vérifiée pour 26/26 annotations nommées, cf. 06-svg-findings-link.md)
└── métadonnées : aucune (auteur, date, licence, provenance du dessin) [ABSENT]
```
Chiffres vérifiés sur les fichiers : 48 éléments porteurs de `data-anno-id` (30 dans `Horse.svg`, 18 dans `Horse_head.svg`), 27 annotations uniques, 26 nommées, toutes appariées au catalogue.
## 5. Exemple complet reconstruit (données réelles)
Format : `Fiche anatomique cheval → SVG → élément → ObservationZone produit → zone catalogue → constats disponibles`.
### 5.1 Zone normale, sans latéralité : charnière C7-T1
```text
Fiche "equine"
└─ Horse.svg
└─ point-mpbwyyc9 (circle r=30 hitbox + circle r=18 fill #ff0000)
data-anno-name-fr="Charnière C7-T1 (cervico-thoracique)"
data-anno-name-en="C7-T1 (Cervicothoracic)"
data-anno-category="charni-res-vert-brales" (pas de lateral, pas de special)
└─ clic → toggleZone → ObservationZone { boneId: "point-mpbwyyc9" }
└─ match EN exact → zones["c7-t1"]
├─ c7-t1-dysfunctions
│ ├─ segmental : restriction-flexion, restriction-extension,
│ │ restriction-lateroflexion, restriction-rotation, fixation
│ ├─ muscular : scalenus-tension, serratus-tension,
│ │ brachiocephalicus-tension, deep-cervical-tension
│ └─ mechanical: amplitude-asymmetry, alignment-asymmetry
├─ c7-t1-observations
│ base-neck-stiffness, forelimb-engagement, ewe-neck-posture,
│ forelimb-lameness [requires_vet_referral]
└─ anamnesis
trauma-direct, saddle-context, posture-context,
stress-context, post-veterinary, no-identified-cause
```
Un constat coché produit par exemple `Finding { zoneId: "c7-t1", path: ["c7-t1-dysfunctions","segmental","fixation"], labelFrSnapshot: "Fixation de la charnière", labelEnSnapshot: "Junction fixation" }` (FACTUEL : `FindingsTreePicker.tsx:146-155`).
### 5.2 Zone avec latéralité : hanche
```text
Fiche "equine"
└─ Horse.svg
└─ point-mpbwtst0 (circle r=34 hitbox + circle r=22 fill #ff9500)
name-fr="Hanche (coxo-fémorale)" name-en="Hip joint"
category="articulations" data-anno-lateral="bilateral"
└─ clic → handleBilateralZone → LateralityPicker (gauche / droite / les deux)
└─ ObservationZone { boneId: "point-mpbwtst0", side: "left" }
ObservationZone { boneId: "point-mpbwtst0", side: "right" } (deux entrées distinctes)
└─ match EN exact → zones["hip"] (un picker par côté, clé "hip:left" / "hip:right")
├─ hip-dysfunctions
│ ├─ articular : restriction-flexion, restriction-extension,
│ │ restriction-abduction-adduction, restriction-rotation,
│ │ hypomobility, hypermobility [vet]
│ ├─ muscular : gluteal-group-tension, iliopsoas-tension,
│ │ adductors-tension, biceps-femoris-tension, trigger-points
│ └─ mechanical: weight-bearing-asymmetry, amplitude-asymmetry, croup-asymmetry
├─ hip-observations
│ ├─ ridden-work : canter-difficulty, backing-difficulty,
│ │ limb-engagement, jumping-difficulty
│ └─ limb-lameness [vet]
└─ anamnesis
trauma-direct, sport-context, posture-context,
stress-context, post-veterinary, no-identified-cause
```
Le `Finding` porte alors `side: "left"` (FACTUEL : `FindingsTreePicker.tsx:154`). Le catalogue lui-même ignore la latéralité : la même liste sert aux deux côtés.
### 5.3 Zone vertébrale : vertèbres cervicales
```text
Fiche "equine"
└─ Horse.svg
└─ zone-mpbx5hx2 (polygon 16 sommets, fill #e100ff)
name-fr="Vertèbres cervicales" name-en="Cervical Vertebrae"
category="zone-colonne" data-anno-special="vertebral-precision"
└─ clic → handleSpineZone → VertebraPicker
│ région initiale = regionFromLabel("Vertèbres cervicales") → "C" (spineZones.ts:18)
│ onglets C(7) T(18) L(6) S(5) Cd(18) depuis vertebralFormula
└─ ObservationZone { boneId: "zone-mpbx5hx2", vertebrae: [{region:"C",index:3},{region:"C",index:4}] }
└─ match EN exact → zones["cervical"]
├─ cervical-dysfunctions
│ ├─ segmental : restriction-flexion, restriction-extension,
│ │ restriction-lateroflexion, restriction-rotation, localized-fixation
│ ├─ group : nsr-group, functional-scoliotic-attitude
│ ├─ muscular : splenius-tension, longissimus-capitis-cervicis,
│ │ scalenus-tension, brachiocephalicus-tension, multifidus-cervicis
│ └─ mechanical: lateral-bend-asymmetry, muscle-relief-asymmetry
├─ cervical-observations
│ ├─ ridden-work : bend-asymmetry-work, head-carriage, contact-resistance
│ ├─ stumbling-proprioceptive [vet]
│ ├─ palpation-sensitivity [vet]
│ └─ new-stiffness [vet]
└─ anamnesis (6 feuilles)
```
Le catalogue ne connaît pas les vertèbres individuelles : `C3` et `C4` vivent dans `ObservationZone.vertebrae`, le constat est attaché à la zone `cervical` entière (FACTUEL : `Finding` n'a pas de champ vertèbre, `observation.ts:40-47`).
### 5.4 Zone qui ouvre un détail : tête, puis ATM
```text
Fiche "equine"
└─ Horse.svg
└─ zone-mpby55kd (polygon 15 sommets, fill #ff9500 opacité 0.06, pointillés)
data-anno-opens-detail="head" category="articulations" (aucun name-fr/en)
└─ clic → handleDetailOpen → species.details["head"] → DetailModal
│ (zone-mpby55kd n'est JAMAIS ajoutée au bilan ; EditorRoute.tsx:295-297)
└─ Horse_head.svg (viewBox 60 100 500 380)
└─ point-mpbyo7zq (circle r=27 hitbox + circle r=15 fill #ff8800)
name-fr="Articulation Temporo-Mandibulaire (ATM)"
name-en="Temporomandibular Joint (TMJ)" category="articulations"
└─ clic → toggleZone → ObservationZone { boneId: "point-mpbyo7zq", detailSourceId: "head" }
└─ match EN exact → zones["atm"]
├─ atm-dysfunctions
│ ├─ articular : restriction-opening, restriction-closing,
│ │ restriction-lateral, restriction-protrusion,
│ │ hypomobility, hypermobility [vet]
│ ├─ muscular : masseter-tension, temporalis-tension,
│ │ pterygoid-tension, trigger-points
│ └─ mechanical: lateral-deviation-jaw, asymmetric-dental-wear,
│ opening-deviation, asymmetric-amplitude
├─ atm-observations (8 feuilles, dont headshaking [vet])
└─ anamnesis (6 feuilles, dont dental-context)
```
`detailSourceId: "head"` sert ensuite au PDF pour choisir le SVG à rasteriser (FACTUEL : `observationPage.ts:367-384`).
### 5.5 Zone à plusieurs catégories de constats : sphénoïde
Toutes les zones ont trois catégories. Le sphénoïde illustre en plus une anomalie d'identifiant : sa première catégorie s'appelle `ssb-dysfunctions`, comme celle de la zone `ssb` (FACTUEL, `pathologies.json`).
```text
Horse_head.svg
└─ point-mpbymcln name-fr="Sphénoïde" name-en="Sphenoid" category="cadrans-du-cr-ne"
└─ zones["sphenoid"]
├─ ssb-dysfunctions (id identique à zones["ssb"].categories[0].id)
│ ├─ physiological : flexion, extension, torsion-right, torsion-left,
│ │ sidebending-rotation-right, sidebending-rotation-left
│ ├─ traumatic : vertical-strain-superior, vertical-strain-inferior,
│ │ lateral-strain-right, lateral-strain-left, compression
│ ├─ intraosseous : pre-post-sphenoid, lesser-wings, greater-wings
│ └─ sutures : 8 sutures (sphenopetrosal … sphenopalatine)
├─ sphenoid-observations
│ ├─ behavior-change : irritability, withdrawal, hypersensitivity
│ ├─ performance-drop
│ ├─ cycle-irregularity [vet]
│ └─ post-trauma-head
└─ anamnesis : trauma-direct, stress-context, posture-context, dental-context, …
```
Conséquence DEDUITE : un `Finding` de la zone `sphenoid` et un `Finding` de la zone `ssb` peuvent porter le même `path[0]`. Ils restent distinguables par `zoneId`, jamais par le chemin seul.
## 6. Ce qui manque pour que cette fiche existe en tant qu'objet
DEDUIT, à partir de l'inventaire ci-dessus :
- aucun identifiant de fiche, aucune version, aucune date, aucun auteur ;
- aucune table d'annotations : la liste des points et zones n'existe que dans le DOM SVG ;
- aucun lien persisté entre une annotation et une zone du catalogue (voir `06-svg-findings-link.md`) ;
- aucune table des vues de détail en données : elle est codée dans un fichier TS (`index.ts:9-11`) et recopiée dans `public/pathology-editor.html:786-796` ;
- aucune métadonnée d'affichage (couleur de catégorie, ordre) hors du style inline des éléments SVG ;
- deux copies du catalogue à garder synchronisées à la main.
## Points non déterminés
- Origine du dessin anatomique (tracé Inkscape ? source externe ?) : aucune métadonnée dans les SVG. HYPOTHESE : export Inkscape nettoyé, au vu des `linearGradient`/`filter` en tête de fichier.
- Si `zone-mpby55kd` porte la catégorie `articulations` par choix ou par oubli (l'éditeur SVG retire normalement `data-anno-category` d'une zone de détail, `SvgEditorRoute.tsx:1139`). HYPOTHESE : annotation faite avant cette règle de l'éditeur.
- Pourquoi la première catégorie de `sphenoid` s'appelle `ssb-dysfunctions` : erreur d'auteur ou choix clinique (le sphénoïde est l'os de la SSB). Non tranché par le code.