Files
faunosteo/docs/faunosteo-audit/06-svg-findings-link.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

21 KiB
Raw Blame History

06. Lien SVG ↔ constats

Périmètre : comment l'application décide que "cette zone du SVG possède ces constats". Algorithme, point d'appel, pièges, table complète cheval, exemples bout en bout, et ce que le bilan garde de ce lien. Le catalogue lui-même est décrit dans 05-findings-editor.md, la persistance dans 08-report-and-pdf.md.

Sources lues

  • src/lib/zoneMatch.ts (algorithme)
  • src/components/observation/ObservationCard.tsx (point d'appel)
  • src/components/observation/FindingsTreePicker.tsx (production du Finding)
  • src/anatomy/svgConvention.ts, src/anatomy/types.ts (ce que porte un Bone)
  • public/pathology-editor.html:850-908 (copie inline)
  • public/species/equine/Horse.svg, Horse_head.svg, pathologies.json (données)
  • tests/unit/lib.zoneMatch.test.ts
  • docs/PATHOLOGIES-FORMAT.md:71-79, docs/ADDING-A-SPECIES.md:205-217
  • .claude/memory/decisions.md BDR-013, BDR-021 ; learnings.md LRN-014, LRN-026 ; journal.md:73

1. Constat principal

FACTUEL : aucun identifiant n'est partagé entre un élément SVG et une zone du catalogue.

  • Côté SVG, l'identifiant est data-anno-id (point-mpbwtst0, zone-mpbx5hx2…), généré par l'éditeur SVG à partir d'un horodatage ('point-' + Date.now().toString(36), src/app/routes/SvgEditorRoute.tsx:1245).
  • Côté catalogue, l'identifiant est la clé de zones (hip, cervical…), slug lisible.
  • Aucun fichier ne contient une table data-anno-id → zoneId.

Le lien est calculé à chaque rendu par comparaison des libellés FR et EN. Il n'est écrit nulle part. Décision documentée dans BDR-013 ("SVG↔JSON zone bridge via fuzzy FR/EN label match") et docs/PATHOLOGIES-FORMAT.md:74-79, qui prescrit l'égalité stricte comme règle d'auteur et garde le fuzzy en filet de sécurité.

2. Point d'appel dans l'application

FACTUEL, src/components/observation/ObservationCard.tsx:126-145, useMemo nommé zonesWithTree :

for (const z of observation.zones) {
  const bone = bones.get(z.boneId)
  if (!bone) continue
  const tree = matchZoneFindings({ fr: bone.fr, en: bone.en }, zonesArray)
  if (!tree) continue
  const key = z.side ? `${tree.id}:${z.side}` : tree.id
  if (seen.has(key)) continue
  seen.add(key)
  out.push({ tree, side: z.side })
}

Observations sur ce code :

  • zonesArray est Object.values(findings.zones) (l.121-124), donc dans l'ordre du dictionnaire JSON (crânio-caudal).
  • bones est la fusion carte principale + cartes de détail (allBones, EditorRoute.tsx:175-181). Un boneId absent (SVG renommé, détail non chargé) est ignoré en silence : pas de picker, pas de message spécifique.
  • Un boneId présent mais sans zone catalogue est aussi ignoré en silence. Le seul message utilisateur est observation.findings_no_catalog ("Aucun référentiel disponible pour ces zones. Utilisez le texte libre ci-dessous.", src/i18n/fr.ts:87-88), affiché seulement si aucune des zones de l'observation n'a de catalogue (ObservationCard.tsx:287-291).
  • detailSourceId n'intervient pas dans le matching. Une zone de détail et une zone du corps portant le même libellé donneraient le même arbre.
  • Déduplication par tree.id ou tree.id:side : deux zones SVG différentes qui matchent la même zone catalogue ne produisent qu'un picker.
  • Le résultat n'est pas mémorisé entre deux rendus au-delà du useMemo ; il est recalculé si observation.zones, bones ou zonesArray change.

Le même matcher n'est appelé nulle part ailleurs dans src/ (FACTUEL : seul import dans ObservationCard.tsx:13). Le PDF ne matche pas : il lit Finding.zoneId déjà résolu (voir 08-report-and-pdf.md).

3. L'algorithme src/lib/zoneMatch.ts

FACTUEL, fonction par fonction.

normalizeLabel (l.21-28)

toLowerCase() → normalize('NFD') → suppression des diacritiques [̀-ͯ] → suppression de tout ce qui n'est pas [a-z0-9]. Exemples : "Sphénoïde" → sphenoide ; "Charnière C0-C1 (occipito-atloïdienne)" → charnierec0c1occipitoatloidienne ; "Temporomandibular Joint (TMJ)" → temporomandibularjointtmj. Valeur vide ou nulle → chaîne vide.

levenshtein (l.30-50)

Distance d'édition classique, deux lignes glissantes, coût 1 par insertion, suppression ou substitution.

scorePair(boneLabel, zoneLabel) (l.62-75)

Condition Score
l'une des deux chaînes normalisées est vide +∞ (SCORE_NO_MATCH)
égalité après normalisation 0 (SCORE_EXACT)
l'une contient l'autre (`a.includes(b)
distance d ≤ max(2, floor(0.25 × longueur max)) 2 + d
sinon +∞

Le test de sous-chaîne est symétrique : le libellé court peut être contenu dans le long, ou l'inverse.

bestOnLanguage(label, zones, pick) (l.87-99)

Parcourt les zones dans l'ordre, garde le score strictement le plus bas. À score égal, la première zone rencontrée gagne. L'ordre est donc celui du dictionnaire zones.

matchZoneFindings(bone, zones) (l.110-130)

  1. enOnEn : EN du SVG contre name_en. Si score ≤ 1 (exact ou sous-chaîne), retour immédiat.
  2. frOnFr : FR du SVG contre name_fr. Si score ≤ 1, retour.
  3. Sinon, prend le plus petit score parmi enOnEn, frOnFr, enOnFr, frOnEn (fuzzy accepté, croisement de langues accepté). Tri stable, donc à égalité l'ordre EN→EN, FR→FR, EN→FR, FR→EN tranche.
  4. Catalogue vide → undefined.

Pièges, DEDUIT du code et vérifiés sur les données :

  • Un libellé court contenu dans un libellé long matche avec score 1. "Frontal" seul matcherait "Frontal bone" (frontal ⊂ frontalbone). Ce cas n'existe pas aujourd'hui puisque le SVG porte "Frontal bone", mais il montre qu'une abréviation côté SVG suffit à accrocher une zone.
  • Une sous-chaîne (score 1) ne bat jamais une égalité (score 0) : bestOnLanguage garde le minimum. Le risque apparaît seulement si la zone exacte disparaît du catalogue : le libellé retomberait alors sur la zone la plus proche sans avertissement.
  • Vérification FACTUELLE sur les 26 zones du catalogue : aucun name_en normalisé n'est contenu dans un autre name_en, idem en FR. Par exemple temporal n'est pas contenu dans temporomandibularjointtmj (le o de "temporo" casse la séquence). Le brief pouvait le laisser croire ; le calcul dit non.
  • Vérification FACTUELLE des paires proches au sens Levenshtein, avec le seuil réel : en FR, "Boulet ant. (métacarpo-phalangien)" / "Boulet post. (métatarso-phalangien)" sont à distance 5 pour un seuil de 7, et "Vertèbres sacrales" / "Vertèbres caudales" à distance 3 pour un seuil de 4. En EN aucune paire n'est sous le seuil. Conséquence DEDUITE : si l'attribut EN d'un boulet ou d'une zone vertébrale venait à manquer ou à diverger, l'étape 3 pourrait accrocher la mauvaise zone FR. Tant que les 26 paires EN sont strictement égales (cas actuel), l'étape 1 répond toujours avec score 0 et ces collisions sont inatteignables.
  • Le matcher ne connaît pas la catégorie SVG (articulations, zone-colonne…) ni data-anno-special. Deux zones de catégories différentes avec le même libellé seraient confondues.
  • Le déclencheur de détail (zone-mpby55kd) n'a ni FR ni EN : scorePair renvoie +∞ partout, matchZoneFindings renvoie undefined. C'est voulu : cette zone ne doit pas porter de constats (docs/ANATOMY-SVG-CONVENTION.md:155).

Copie inline dans public/pathology-editor.html:850-908

FACTUEL : normalizeLabel, levenshtein, scorePair, bestOnLanguage, matchZone reproduisent l'original. Comparaison ligne à ligne :

Point zoneMatch.ts pathology-editor.html Identique
Diacritiques /[̀-ͯ]/g (l.26) /[̀-ͯ]/g (l.854, caractères littéraux U+0300 et U+036F) oui, même plage
Seuil fuzzy Math.max(2, Math.floor(longest * 0.25)) identique (l.881) oui
Ordre EN→EN, FR→FR, croisés identique identique (l.897-908) oui
Retour sans match undefined null sans effet

BDR-021 assume cette duplication (un .html sans build ne peut pas importer un module TS). LRN-026 recommande un test comparant les deux implémentations sur un jeu de libellés commun ; ce test n'existe pas (FACTUEL : tests/unit/lib.zoneMatch.test.ts ne teste que le module TS). Toute évolution de l'un sans l'autre fera diverger la sélection de zone entre l'éditeur et l'application.

4. Table complète cheval : annotation SVG → zone catalogue

Méthode : égalité stricte vérifiée par comparaison de chaînes (FACTUEL). Résultat du matcher reproduit par réimplémentation de l'algorithme hors vitest, en Python, sur les attributs réels des deux SVG et les 26 zones (DEDUIT : le code TS n'a pas été exécuté dans cet audit). Les 26 annotations nommées obtiennent un score 0 à l'étape EN→EN ; le FR est aussi strictement égal. 0 zone du catalogue reste orpheline.

Horse.svg (18 annotations)

data-anno-id Catégorie SVG Attributs spéciaux name-fr name-en → zoneId Catégories du catalogue
point-mpbwrkp0 articulations lateral=bilateral Boulet post. (métatarso-phalangien) Hind fetlock hind-fetlock hind-fetlock-dysfunctions, hind-fetlock-observations, anamnesis
point-mpbwsi9q articulations lateral=bilateral Jarret (tarsien) Hock hock hock-dysfunctions, hock-observations, anamnesis
point-mpbwt4fa articulations lateral=bilateral Grasset (fémoro-tibial) Stifle stifle stifle-dysfunctions, stifle-observations, anamnesis
point-mpbwtst0 articulations lateral=bilateral Hanche (coxo-fémorale) Hip joint hip hip-dysfunctions, hip-observations, anamnesis
point-mpbwugty articulations lateral=bilateral Articulation Sacro-Iliaque Sacroiliac Joint sacroiliac sacroiliac-dysfunctions, sacroiliac-observations, anamnesis
point-mpbwv4xy articulations lateral=bilateral Épaule (scapulo-humérale) Shoulder joint shoulder shoulder-dysfunctions, shoulder-observations, anamnesis
point-mpbwvpvt articulations lateral=bilateral Coude (huméro-radial) Elbow joint elbow elbow-dysfunctions, elbow-observations, anamnesis
point-mpbwwaru articulations lateral=bilateral Boulet ant. (métacarpo-phalangien) Fore fetlock fore-fetlock fore-fetlock-dysfunctions, fore-fetlock-observations, anamnesis
point-mpbwwxvn os lateral=bilateral Sésamoïdes ant. (boulet) Forelimb Sesamoids fore-sesamoids fore-sesamoids-dysfunctions, fore-sesamoids-observations, anamnesis
point-mpbwxnb4 charni-res-vert-brales Charnière L6-S1 (lombo-sacrée) L6-S1 (Lumbosacral) l6-s1 l6-s1-dysfunctions, l6-s1-observations, anamnesis
point-mpbwyd9i charni-res-vert-brales Charnière T18-L1 (dorso-lombaire) T18-L1 (Thoracolumbar) t18-l1 t18-l1-dysfunctions, t18-l1-observations, anamnesis
point-mpbwyyc9 charni-res-vert-brales Charnière C7-T1 (cervico-thoracique) C7-T1 (Cervicothoracic) c7-t1 c7-t1-dysfunctions, c7-t1-observations, anamnesis
zone-mpbx00jq zone-colonne special=vertebral-precision Vertèbres caudales Coccygeal Vertebrae caudal caudal-dysfunctions, caudal-observations, anamnesis
zone-mpbx0xnp zone-colonne special=vertebral-precision Vertèbres sacrales Sacral Vertebrae sacral sacral-dysfunctions, sacral-observations, anamnesis
zone-mpbx1rm9 zone-colonne special=vertebral-precision Vertèbres lombaires Lumbar Vertebrae lumbar lumbar-dysfunctions, lumbar-observations, anamnesis
zone-mpbx2rpe zone-colonne special=vertebral-precision Vertèbres thoraciques Thoracic Vertebrae thoracic thoracic-dysfunctions, thoracic-observations, anamnesis
zone-mpbx5hx2 zone-colonne special=vertebral-precision Vertèbres cervicales Cervical Vertebrae cervical cervical-dysfunctions, cervical-observations, anamnesis
zone-mpby55kd articulations opens-detail=head (absent) (absent) aucune aucune

Horse_head.svg (9 annotations)

data-anno-id Catégorie SVG name-fr name-en → zoneId Catégories du catalogue
point-mpbykomv cadrans-du-cr-ne Pariétal Parietal bone parietal parietal-dysfunctions, parietal-observations, anamnesis
point-mpbylh35 cadrans-du-cr-ne Frontal Frontal bone frontal frontal-dysfunctions, frontal-observations, anamnesis
point-mpbymcln cadrans-du-cr-ne Sphénoïde Sphenoid sphenoid ssb-dysfunctions, sphenoid-observations, anamnesis
point-mpbyn2k3 cadrans-du-cr-ne Temporel Temporal temporal temporal-dysfunctions, temporal-observations, anamnesis
point-mpbynls5 cadrans-du-cr-ne Occipital Occipital occipital occipital-dysfunctions, occipital-observations, anamnesis
point-mpbyo7zq articulations Articulation Temporo-Mandibulaire (ATM) Temporomandibular Joint (TMJ) atm atm-dysfunctions, atm-observations, anamnesis
point-mpbyphay articulations Synchondrose Sphéno-Basilaire (SSB) Spheno-Basilar Synchondrosis (SBS) ssb ssb-dysfunctions, ssb-observations, anamnesis
point-mpbyq841 os Hyoïde Hyoid hyoid hyoid-dysfunctions, hyoid-observations, anamnesis
point-mpbyqxbg charni-res-vert-brales Charnière C0-C1 (occipito-atloïdienne) C0-C1 (Occipito-atlantal) c0-c1 c0-c1-dysfunctions, c0-c1-observations, anamnesis

Historique : le journal (.claude/memory/journal.md:73) note qu'une seule différence de casse existait (hyoïde vs Hyoïde dans Horse_head.svg), corrigée par l'utilisateur. Depuis, l'égalité stricte tient sur les 26 paires. Le fuzzy n'est plus exercé par les données réelles.

5. Exemples bout en bout

Format : SVG → identifiant → zone → clé du catalogue → catégories → constats disponibles.

(a) Zone normale, sans latéralité : charnière C7-T1

Horse.svg
→ point-mpbwyyc9  (deux <circle> : hitbox r=30 fill=transparent + visible r=18 fill=#ff0000)
→ "Charnière C7-T1 (cervico-thoracique)" / "C7-T1 (Cervicothoracic)", catégorie SVG charni-res-vert-brales, pas de lateral, pas de special
→ c7-t1  (score 0, EN exact)
→ c7-t1-dysfunctions · c7-t1-observations · anamnesis
→ feuilles réelles, par exemple :
     c7-t1-dysfunctions / segmental / restriction-flexion      "Restriction en flexion"
     c7-t1-dysfunctions / segmental / fixation                 "Fixation de la charnière"
     c7-t1-dysfunctions / muscular / scalenus-tension          "Tension du scalène"
     c7-t1-dysfunctions / mechanical / amplitude-asymmetry     "Asymétrie d'amplitude gauche/droite"
     c7-t1-observations / base-neck-stiffness                  "Raideur de la base de l'encolure"
     c7-t1-observations / forelimb-lameness                    "Boiterie antérieure rapportée"
     anamnesis / saddle-context                                "Contexte de sellerie (selle inadaptée, poids du cavalier)"

Clic : toggleZone (EditorRoute.tsx:273), la zone est ajoutée telle quelle, { boneId: 'point-mpbwyyc9' }. Un constat coché donne { zoneId: 'c7-t1', path: ['c7-t1-dysfunctions','segmental','fixation'], labelFrSnapshot: 'Fixation de la charnière', labelEnSnapshot: '…' }.

(b) Zone bilatérale : hanche

Horse.svg
→ point-mpbwtst0, data-anno-lateral="bilateral"
→ "Hanche (coxo-fémorale)" / "Hip joint"
→ hip  (score 0)
→ hip-dysfunctions · hip-observations · anamnesis   (arbre complet dans 05-findings-editor.md §2.5)

Clic : handleBilateralZone (EditorRoute.tsx:246) ouvre LateralityPicker. Le choix "gauche" ajoute { boneId: 'point-mpbwtst0', side: 'left' }. La carte d'observation affiche alors un picker "Hanche (coxo-fémorale) (Gauche)" avec la clé hip:left. Un constat coché porte side: 'left'. Choisir ensuite "droite" ajoute une deuxième zone et un deuxième picker hip:right, sur le même arbre. Le catalogue ne distingue pas les côtés : le même arbre hip sert aux deux.

(c) Vertèbres : zone cervicale

Horse.svg
→ zone-mpbx5hx2  (un seul <polygon>), data-anno-special="vertebral-precision", catégorie zone-colonne
→ "Vertèbres cervicales" / "Cervical Vertebrae"
→ cervical  (score 0)
→ cervical-dysfunctions · cervical-observations · anamnesis   (arbre complet dans 05-findings-editor.md §2.5)

Clic : handleSpineZone (EditorRoute.tsx:226) ajoute la zone si absente et ouvre VertebraPicker (onglet C présélectionné via regionFromLabel('Vertèbres cervicales') → 'C'). Confirmer C3 et C4 donne { boneId: 'zone-mpbx5hx2', vertebrae: [{ region: 'C', index: 3 }, { region: 'C', index: 4 }] }. Les vertèbres ne filtrent pas les constats : le catalogue est par région, pas par vertèbre (FACTUEL : cervical n'a aucun nœud par numéro de vertèbre ; FindingsTreePicker ne reçoit pas vertebrae). Elles n'apparaissent que dans le libellé de zone, "Vertèbres cervicales (C3, C4)".

(d) Zone dans un SVG de détail : ATM

Horse.svg → zone-mpby55kd (opens-detail=head) → ouverture de DetailModal avec Horse_head.svg
Horse_head.svg
→ point-mpbyo7zq
→ "Articulation Temporo-Mandibulaire (ATM)" / "Temporomandibular Joint (TMJ)"
→ atm  (score 0)
→ atm-dysfunctions ("Dysfonctions ostéopathiques de l'ATM") · atm-observations · anamnesis
→ feuilles réelles :
     atm-dysfunctions / articular / restriction-opening        "Restriction à l'ouverture"
     atm-dysfunctions / articular / hypermobility              "Hypermobilité / laxité perçue"  (requires_vet_referral)
     atm-dysfunctions / muscular / masseter-tension            "Tension du masséter"
     atm-dysfunctions / mechanical / lateral-deviation-jaw     "Latéro-déviation de la mâchoire"
     atm-observations / headshaking                            "Headshaking (secouement de tête)"  (requires_vet_referral)

La zone persistée est { boneId: 'point-mpbyo7zq', detailSourceId: 'head' }. Le detailSourceId sert au PDF (quelle image rendre) et à l'identité de zone (matches dans onZoneClick), pas au matching. Le libellé est résolu grâce à detailBones, préchargés pour tous les détails du manifeste (EditorRoute.tsx:143-152).

(e) Zone à plusieurs catégories : sphénoïde

Toutes les zones ont trois catégories. Le cas sphenoid montre en plus l'anomalie d'id :

Horse_head.svg
→ point-mpbymcln
→ "Sphénoïde" / "Sphenoid"
→ sphenoid  (score 0 ; la zone ssb, "Spheno-Basilar Synchondrosis (SBS)", est à +∞ : pas de sous-chaîne, distance au-delà du seuil)
→ ssb-dysfunctions (id hérité de la zone ssb, libellé "Dysfonctions ostéopathiques")
   · sphenoid-observations
   · anamnesis
→ un Finding coché sous la première catégorie a path[0] === 'ssb-dysfunctions' avec zoneId 'sphenoid'

Le test lib.zoneMatch.test.ts:147-149 vérifie explicitement que "Sphénoïde" ne tombe pas dans la zone ssb.

6. Ce que le bilan garde de ce lien

FACTUEL (src/domain/schema/observation.ts) :

Donnée Champ persisté Provenance
Identité SVG de la zone ObservationZone.boneId data-anno-id
Vue d'origine ObservationZone.detailSourceId id du détail, si clic dans la modale
Côté ObservationZone.side, Finding.side LateralityPicker
Vertèbres ObservationZone.vertebrae VertebraPicker
Identité catalogue Finding.zoneId tree.id au moment du clic sur la feuille
Chemin Finding.path ids des nœuds depuis categories
Libellés du constat Finding.labelFrSnapshot, labelEnSnapshot copiés de la feuille (BDR-010)

Ce qui n'est pas persisté : le libellé de la zone SVG, la catégorie SVG, le nom de la zone catalogue, et surtout la correspondance boneId ↔ zoneId. DEDUIT : après export, rien dans le JSON du bilan ne dit que point-mpbwtst0 et hip désignent la même hanche. Les deux listes zones[] et findings[] d'une observation coexistent sans clé de jointure. À la réouverture, le lien est recalculé depuis le SVG et le catalogue courants ; si l'un des deux a changé de libellé, le picker de cette zone disparaît alors que les findings déjà cochés restent dans le bilan (orphelins affichables grâce aux snapshots, mais plus modifiables depuis un picker). Voir 08-report-and-pdf.md §A.4 et 10-current-limitations.md.

Points non déterminés

  • DEDUIT, non exécuté : la table §4 repose sur une réimplémentation fidèle de l'algorithme. Un test vitest dédié (chargement des deux SVG réels + matchZoneFindings sur les 26 zones) donnerait le même tableau en FACTUEL ; il n'existe pas aujourd'hui (voir 13-tests.md).
  • HYPOTHESE : le choix "EN d'abord" (commentaire zoneMatch.ts:16-18, "no accents → fewer normalization edge cases") suppose que les libellés EN sont toujours renseignés et plus stables que les FR. Rien ne l'impose dans le SVG (data-anno-name-en est optionnel pour le parseur, svgConvention.ts:51).