Files
faunosteo/docs/faunosteo-audit/05-findings-editor.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

22 KiB
Raw Blame History

05. Système de constats / pathologies et son éditeur

Périmètre : le catalogue pathologies.json (schéma, chargement, structure réelle du cheval), puis l'éditeur autonome public/pathology-editor.html. Le lien zone SVG ↔ catalogue est traité dans 06-svg-findings-link.md. La persistance dans le bilan est traitée dans 08-report-and-pdf.md.

Sources lues

  • src/domain/schema/findings.ts (schéma Zod)
  • src/domain/species/equine/pathologies.ts (chargeur)
  • src/domain/species/equine/pathologies.json et public/species/equine/pathologies.json (données)
  • src/domain/species/types.ts, src/domain/species/equine/index.ts (manifeste)
  • src/app/routes/EditorRoute.tsx, src/pdf/export.ts (consommateurs)
  • src/components/observation/FindingsTreePicker.tsx, ObservationCard.tsx (UI)
  • src/i18n/fr.ts (libellés)
  • public/pathology-editor.html (éditeur, 1700 lignes)
  • docs/PATHOLOGIES-FORMAT.md, docs/ADDING-A-SPECIES.md, docs/superpowers/specs/2026-05-22-pathology-editor-design.md
  • .claude/memory/decisions.md (BDR-010, BDR-016, BDR-020, BDR-021, BDR-022)

1. Vocabulaire : findings, pathologies, constats

Trois mots désignent le même objet selon la couche. FACTUEL :

Couche Terme Preuve
Fichier de données pathologies.json, pathologies.ts noms de fichiers
Schéma et code TS findings, FindingNode, SpeciesFindings, Finding src/domain/schema/findings.ts, SpeciesManifest.findings
Interface praticien "Constats (référentiel)", "Constats (texte libre)" src/i18n/fr.ts:85 et :89
Compteur du picker "constat sélectionné" / "constats sélectionnés" src/i18n/fr.ts:107-108
PDF "CONSTATS — ", "CONSTATS LIBRES" src/i18n/fr.ts:162-163
Page des éditeurs "Éditeur de pathologies" src/i18n/fr.ts:47

Le brief du produit futur parle de "constats / observations / pathologies". Le terme "Observations" existe déjà dans l'app mais avec un autre sens : une Observation est un regroupement de zones + constats + sévérité + commentaire (src/domain/schema/observation.ts:51-59), et c'est aussi le titre de la section (observation.section_title: 'Observations', fr.ts:74). Le nom "Observations / motifs de consultation" désigne par ailleurs une catégorie du catalogue. DEDUIT : le futur produit devra fixer un vocabulaire, car "observation" est déjà surchargé.

2. Le fichier pathologies.json

2.1 Deux copies identiques

FACTUEL : deux fichiers de 174 156 octets, md5 identique f3b11822165d98be24dd7a706a656ac2.

Copie Lecteur Mode d'accès
src/domain/species/equine/pathologies.json src/domain/species/equine/pathologies.ts:5 (import data from './pathologies.json') Bundlé par Vite au build, parsé par Zod au chargement du module
public/species/equine/pathologies.json public/pathology-editor.html:790 (jsonPath: '/species/equine/pathologies.json') Fetch HTTP à l'exécution, sans validation Zod

Conséquences, DEDUIT à partir de ces deux chemins et de docs/ADDING-A-SPECIES.md:188-197 :

  • L'application ne lit jamais la copie public/. L'éditeur ne lit jamais la copie src/.
  • Une édition faite dans l'éditeur produit un téléchargement (pathologies-<species>-<timestamp>.json). Rien ne l'écrit dans le repo. Il faut recopier le fichier à la main aux deux emplacements, puis rebuilder pour que l'application voie le changement.
  • Aucun mécanisme ne vérifie que les deux copies restent identiques. La spec (docs/superpowers/specs/2026-05-22-pathology-editor-design.md:56) décrit la copie public/ comme "read-only pour l'éditeur" et la copie src/ comme source de vérité.

2.2 Schéma Zod (src/domain/schema/findings.ts)

FACTUEL, champ par champ.

SourceRefSchema (l.15-19) :

Champ Type Obligatoire
type enum manual / journal / database / web oui
citation string non vide oui
url string validée .url() non

FindingNode (interface l.23-32, schéma z.lazy l.34-45) :

Champ Type Obligatoire
id string non vide oui
name_fr string non vide oui
name_en string non vide oui
description_fr string non
description_en string non
requires_vet_referral boolean non
sources SourceRef[] non
children FindingNode[] (récursif) non

ZoneFindingsSchema (l.47-52) : id, name_fr, name_en non vides, categories: FindingNode[] (obligatoire, peut être vide).

SpeciesFindingsSchema (l.56-66) : schema_version string non vide, scope_disclaimer string non vide, species { id, name_fr, name_en }, zones: Record<string, ZoneFindings>.

Ce que Zod retire silencieusement (comportement par défaut de z.object, documenté dans docs/PATHOLOGIES-FORMAT.md:318-321) : toute clé inconnue, dont species.notes. FACTUEL : le fichier actuel ne contient aucune clé inconnue (vérifié par jq '[.. | objects | keys[]] | unique').

Ce que Zod ne vérifie pas (DEDUIT du schéma) :

  • l'unicité des id, à aucun niveau (ni global, ni entre frères) ;
  • la profondeur de l'arbre ;
  • la valeur de schema_version (seulement non vide ; "1.1", "2.0" ou "abc" passent) ;
  • la cohérence species.id ↔ SpeciesManifest.id (un test le couvre, tests/unit/species.equineFindings.test.ts, mais pas le schéma) ;
  • la correspondance name_fr / name_en avec les attributs du SVG ;
  • que requires_vet_referral ne soit posé que sur des feuilles (règle d'auteur, PATHOLOGIES-FORMAT.md:179) ;
  • que chaque nœud intermédiaire ait au moins deux enfants.

2.3 Chargement

FACTUEL :

  1. src/domain/species/equine/pathologies.ts:11 : SpeciesFindingsSchema.parse(data) au chargement du module. Un JSON invalide fait planter l'import.
  2. src/domain/species/equine/index.ts:13 : findings: () => import('./pathologies'), chargement paresseux via le type FindingsLoader (src/domain/species/types.ts:13).
  3. src/app/routes/EditorRoute.tsx:136 : species.findings().then((m) => setFindings(m.default)). Le résultat alimente ObservationList et la modale de disclaimer (EditorRoute.tsx:159, findings.scope_disclaimer, affichée une fois par session via la clé sessionStorage osteo:disclaimer-shown).
  4. src/pdf/export.ts:76-88 : loadSpeciesFindings(speciesId) recharge le même module pour résoudre les noms de zones dans le PDF.

Le catalogue est donc une dépendance de build. Il n'existe aucun chargement dynamique par espèce autre que import.meta.glob du registre (src/domain/species/registry.ts).

2.4 Structure réelle du catalogue cheval

FACTUEL (comptes obtenus par jq sur public/species/equine/pathologies.json) :

Mesure Valeur
schema_version "2.0"
species { id: "equine", name_fr: "Cheval", name_en: "Horse" }
Zones 26
Catégories par zone 3 partout
Nœuds (catégories incluses) 792
Feuilles 612
Feuilles directement sous une catégorie 228
Feuilles sous une sous-catégorie 384
Profondeur maximale 3 niveaux : catégorie > sous-catégorie > feuille
requires_vet_referral: true 41, toutes sur des feuilles
description_fr 62
description_en 0
sources 0

Ordre des clés de zones, crânio-caudal, qui est aussi l'ordre d'itération utilisé par le matcher et le picker :

parietal, frontal, sphenoid, temporal, occipital, ssb, atm, hyoid, c0-c1, cervical, c7-t1, shoulder, elbow, fore-fetlock, fore-sesamoids, thoracic, t18-l1, lumbar, l6-s1, sacral, sacroiliac, hip, stifle, hock, hind-fetlock, caudal

Pour chaque zone, zone.id est égal à sa clé dans zones (FACTUEL, vérifié sur les 26).

Les trois catégories de chaque zone :

Position id name_fr réel name_en réel
1 <zone>-dysfunctions "Dysfonctions ostéopathiques" (sauf atm : "Dysfonctions ostéopathiques de l'ATM") "Osteopathic dysfunctions" (atm : "Osteopathic TMJ dysfunctions")
2 <zone>-observations "Observations / motifs de consultation" "Observations / consultation reasons"
3 anamnesis "Anamnèse / facteurs rapportés" "Anamnesis / reported factors"

Anomalie FACTUELLE : la zone sphenoid a pour première catégorie l'id ssb-dysfunctions, pas sphenoid-dysfunctions (jq '.zones.sphenoid.categories[0].id'). La zone ssb a elle aussi ssb-dysfunctions. Les deux arbres portent donc le même id de catégorie sous deux zones différentes. Aucun code ne s'en plaint puisque les chemins (Finding.path) sont relatifs à zoneId.

La catégorie anamnesis existe en trois variantes de contenu (FACTUEL) :

Zones Enfants (id)
9 zones vertébrales : c0-c1, cervical, c7-t1, thoracic, t18-l1, lumbar, l6-s1, sacral, caudal trauma-direct, saddle-context, posture-context, stress-context, post-veterinary, no-identified-cause
9 zones appendiculaires : shoulder, elbow, fore-fetlock, fore-sesamoids, sacroiliac, hip, stifle, hock, hind-fetlock trauma-direct, sport-context, posture-context, stress-context, post-veterinary, no-identified-cause
8 zones de la tête : parietal, frontal, sphenoid, temporal, occipital, ssb, atm, hyoid trauma-direct, stress-context, posture-context, dental-context, post-veterinary, no-identified-cause

Les ids de nœuds sont réutilisés entre zones, parce que la règle d'unicité ne vaut qu'entre frères (PATHOLOGIES-FORMAT.md:180-183). FACTUEL, ids les plus répétés : anamnesis, no-identified-cause, post-veterinary, posture-context, stress-context, trauma-direct (26 fois chacun), mechanical et muscular (19), amplitude-asymmetry (11), articular (9). Un id de feuille n'identifie donc rien à lui seul : seule la paire (zoneId, path) identifie une feuille.

Contradiction avec CLAUDE.md:272 ("Each entry needs ≥1 source with citation") : aucune entrée n'a de sources. FACTUEL. La règle n'est pas appliquée par le schéma ni par un test.

2.5 Exemples réels

Arbre complet de la zone hip (ids et name_fr) :

hip-dysfunctions — Dysfonctions ostéopathiques
  articular — Restrictions de mobilité articulaire
    restriction-flexion — Restriction en flexion
    restriction-extension — Restriction en extension
    restriction-abduction-adduction — Restriction en abduction/adduction
    restriction-rotation — Restriction en rotation
    hypomobility — Hypomobilité globale
    hypermobility — Hypermobilité / laxité perçue
  muscular — Tensions musculaires péri-articulaires
    gluteal-group-tension — Tension du groupe fessier
    iliopsoas-tension — Tension de l'ilio-psoas
    adductors-tension — Tension des adducteurs
    biceps-femoris-tension — Tension du biceps fémoral
    trigger-points — Points de tension myofasciaux
  mechanical — Asymétries mécaniques observées
    weight-bearing-asymmetry — Asymétrie de report de poids au repos
    amplitude-asymmetry — Asymétrie d'amplitude gauche/droite
    croup-asymmetry — Asymétrie de croupe observée
hip-observations — Observations / motifs de consultation
  ridden-work — Locomotion / travail monté
    canter-difficulty — Difficulté / refus au départ au galop
    backing-difficulty — Reculer difficile ou de travers
    limb-engagement — Défaut d'engagement / d'amplitude du membre
    jumping-difficulty — Difficulté / refus à l'obstacle
  limb-lameness — Boiterie rapportée (membre concerné)
anamnesis — Anamnèse / facteurs rapportés
  trauma-direct — Traumatisme rapporté (choc, chute)
  sport-context — Contexte sportif (discipline, intensité, sol)
  posture-context — Contexte postural / d'aplombs
  stress-context — Contexte de stress / changement
  post-veterinary — Suite d'intervention vétérinaire
  no-identified-cause — Pas de cause identifiée

Arbre complet de la zone cervical :

cervical-dysfunctions — Dysfonctions ostéopathiques
  segmental — Restrictions / fixations segmentaires
    restriction-flexion — Restriction en flexion
    restriction-extension — Restriction en extension
    restriction-lateroflexion — Restriction en latéroflexion
    restriction-rotation — Restriction en rotation
    localized-fixation — Fixation segmentaire localisée (C2–C7)
  group — Dysfonctions de groupe
    nsr-group — Dysfonction de groupe en neutralité (NSR)
    functional-scoliotic-attitude — Attitude scoliotique fonctionnelle observée
  muscular — Tensions musculaires paravertébrales
    splenius-tension — Tension du splénius
    longissimus-capitis-cervicis — Tension du longissimus de la tête / du cou
    scalenus-tension — Tension du scalène
    brachiocephalicus-tension — Tension du brachio-céphalique
    multifidus-cervicis — Tension du multifide cervical
  mechanical — Asymétries mécaniques observées
    lateral-bend-asymmetry — Asymétrie d'incurvation gauche/droite
    muscle-relief-asymmetry — Asymétrie de relief musculaire gauche/droite
cervical-observations — Observations / motifs de consultation
  ridden-work — Travail monté / locomotion
    bend-asymmetry-work — Incurvation difficile d'un côté au travail
    head-carriage — Port de tête / encolure anormal rapporté
    contact-resistance — Résistance au contact / mise en main
  stumbling-proprioceptive — Trébuchements / déficit proprioceptif rapporté
  palpation-sensitivity — Sensibilité à la palpation rapportée
  new-stiffness — Raideur nouvelle / récente
anamnesis — Anamnèse / facteurs rapportés
  trauma-direct — Traumatisme rapporté (choc, chute)
  saddle-context — Contexte de sellerie (selle inadaptée, poids du cavalier)
  posture-context — Contexte postural / de travail
  stress-context — Contexte de stress / changement
  post-veterinary — Suite d'intervention vétérinaire
  no-identified-cause — Pas de cause identifiée

Feuille requires_vet_referral, objet brut copié du fichier (zones.hyoid.categories[1].children[]) :

{
  "id": "swallowing-difficulty",
  "name_fr": "Difficulté de déglutition rapportée",
  "name_en": "Reported 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
}

Autres feuilles vet, avec leur chemin depuis la zone :

Zone Chemin name_fr
frontal frontal-observations / head-rubbing Frottements répétés de la tête rapportés
frontal frontal-observations / frontal-relief-asymmetry Asymétrie de relief frontal observée
sphenoid sphenoid-observations / cycle-irregularity Irrégularité de cyclicité rapportée
atm atm-dysfunctions / articular / hypermobility Hypermobilité / laxité perçue
atm atm-observations / headshaking Headshaking (secouement de tête)
c0-c1 c0-c1-observations / headshaking Headshaking (secouement de tête)
cervical cervical-observations / stumbling-proprioceptive Trébuchements / déficit proprioceptif rapporté

Le scope_disclaimer réel : "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."

2.6 Consommation côté praticien

FACTUEL : FindingsTreePicker (src/components/observation/FindingsTreePicker.tsx) reçoit un ZoneFindings et navigue dans categories par chemin d'ids. Une feuille cochée produit un Finding (toggleLeaf, l.137-156) : zoneId = tree.id, path = liste des ids depuis categories, labelFrSnapshot / labelEnSnapshot copiés de la feuille, requiresVetReferral si la feuille le porte, side si le picker est ouvert pour un côté. Les description_* sont affichées sous la feuille ou sous le nœud focalisé, jamais persistées. Les sources ne sont lues nulle part dans src/ (FACTUEL : grep -rn "sources" src/ ne touche que le schéma).

3. L'éditeur public/pathology-editor.html

3.1 Identité

FACTUEL :

Propriété Valeur
Fichier public/pathology-editor.html, 1700 lignes, HTML + CSS + JS vanilla dans une IIFE
Accès /pathology-editor.html, lien depuis /editors (src/app/routes/EditorsRoute.tsx:32)
Dépendances aucune. Zéro import depuis src/. Pas d'étape de build (servi tel quel depuis public/, LRN-029)
i18n dictionnaire inline TRANSLATIONS (l.556), 76 clés FR et 76 clés EN, locale lue et écrite dans localStorage['osteo:locale'] (l.715, l.766), même clé que l'app
Largeur minimale 900 px (@media (max-width: 899px) masque l'outil, l.450)
robots noindex,nofollow
Décisions BDR-020 (standalone), BDR-021 (copie inline du matcher), BDR-022 (asymétrie assumée avec /svg-editor)

Responsabilité : éditer l'arbre de constats d'une zone du catalogue en cliquant la zone sur le SVG, puis télécharger le JSON modifié. Il ne produit ni ne modifie de SVG.

3.2 Entrées

Deux sources (showSourcePicker, l.958) :

  • "Liste pré-câblée" : SPECIES_CONFIG codé en dur (l.786-796), une seule espèce equine, deux vues (/species/equine/Horse.svg, /species/equine/Horse_head.svg), un seul JSON /species/equine/pathologies.json. Il n'y a aucun lien avec src/domain/species/registry.ts : ajouter une espèce à l'app ne l'ajoute pas à cet éditeur (FACTUEL, DEDUIT pour la conséquence).
  • "Upload manuel" : un .svg et un .json obligatoires, chacun limité à 10 485 760 octets (l.1074-1075), currentSpeciesId = 'custom'.

3.3 Chargement (processSource, l.1109)

FACTUEL :

  1. JSON.parse du JSON ; erreurs affichées dans la barre latérale.
  2. Validation minimale : présence de schema_version, species, zones (l.1114-1116). Aucune validation Zod, aucune vérification de la forme des nœuds.
  3. Parsing du SVG par DOMParser, importNode, puis sanitisation : suppression de <script> et <foreignObject>, des attributs on* et des href en javascript: (l.1127-1135).
  4. Ajout d'un viewBox si absent, suppression de width/height.
  5. Refus si aucun élément [data-anno-id].
  6. Pose d'un seul listener click sur la racine SVG (setupSvgClickListener).

3.4 Clic sur une zone (handleZoneClick, l.1172)

FACTUEL :

  1. Lecture de data-anno-id, data-anno-name-fr, data-anno-name-en, data-anno-opens-detail sur l'élément annoté le plus proche.
  2. Surbrillance de tous les éléments portant ce data-anno-id (highlightZone).
  3. Si data-anno-opens-detail : showNavZoneMessage (l.1263), message "zone de navigation", pas d'édition.
  4. Si ni FR ni EN : retour à la barre latérale par défaut.
  5. Sinon matchZone(nameFr, nameEn, Object.values(jsonData.zones)) (l.896), copie inline de src/lib/zoneMatch.ts (voir 06-svg-findings-link.md).
  6. Zone trouvée : showZoneEditor(matched) (l.1326). Sinon showCreateZonePrompt (l.1288) : bouton "Créer cette zone" qui insère { id: generateId(nameEn, nameFr, Object.keys(zones)), name_fr, name_en, categories: [] } (l.1312-1315) et marque le document sale.

data-anno-special et data-anno-lateral ne sont pas lus par cet éditeur.

3.5 Édition de l'arbre

FACTUEL (buildNodeEl l.1386, showInlineForm l.1476) :

Action Comportement
Ajouter une catégorie racine bouton sous l'arbre, formulaire inline, push dans zone.categories
Ajouter un enfant bouton + sur une ligne, crée node.children si absent, push
Éditer bouton ✎, formulaire pré-rempli, modifie l'objet en place
Supprimer bouton ×, confirm avec le nombre de descendants, siblings.splice(idx, 1) (l.1447)
Déplier / replier clic sur la ligne

Formulaire : name_fr et name_en (au moins un ; si un seul est fourni, il est copié dans l'autre, l.1573-1574), description_fr, description_en, case requires_vet_referral, liste de sources (type parmi manual/journal/database/web, citation, url ; une source sans citation est ignorée). En édition, un champ vidé supprime la clé (delete existingNode.description_fr, etc.). En création, l'id est generateId(en, fr, sibIds) (l.912) : slug kebab-case de name_en sinon name_fr, suffixe -2, -3… en cas de collision entre frères. L'id d'un nœud existant n'est jamais modifiable.

Suivi des modifications : markDirty (l.836) affiche un point rouge, beforeunload (l.846) demande confirmation. downloadJson (l.1648) sérialise jsonData en JSON indenté à 2 espaces sous le nom pathologies-<species.id>-<AAAAMMJJ-HHMMSS>.json (l.1659) et remet l'état à propre.

3.6 Ce que l'éditeur ne permet pas

DEDUIT du code (aucune fonction correspondante) :

  • modifier schema_version, scope_disclaimer, species ;
  • renommer ou supprimer une zone, ou changer ses name_fr / name_en (donc impossible de corriger un libellé pour recoller au SVG) ;
  • réordonner les zones ou les nœuds ;
  • modifier l'id d'un nœud existant ;
  • déplacer un nœud vers un autre parent ;
  • écrire dans le repo : seul un téléchargement est produit ;
  • valider la cohérence avec le SVG au-delà du clic courant (pas de liste des zones SVG sans catalogue ni des zones catalogue sans SVG).

4. Comment la structure peut être modifiée aujourd'hui

Opération Par l'éditeur À la main dans le JSON Validé par
Ajouter / éditer / supprimer un nœud oui oui Zod au boot (forme), rien pour les ids
Créer une zone oui (depuis une zone SVG non matchée) oui Zod (id, name_fr, name_en, categories)
Renommer / supprimer une zone non oui aucun contrôle de l'impact sur les bilans existants
Réordonner non oui aucun
Changer schema_version non oui aucun (non vide seulement)
Ajouter des sources oui oui Zod (type, citation, url)
Synchroniser src/ et public/ non copie manuelle aucun

Points non déterminés

  • HYPOTHESE : l'absence totale de sources vient du passage au catalogue v2.0 rédigé par l'expert métier sans citations ; le schéma les a toujours rendues optionnelles. Rien dans le code ne le confirme.
  • HYPOTHESE : l'id ssb-dysfunctions sous la zone sphenoid est un copier-coller de la zone ssb. Les feuilles des deux arbres diffèrent (sphenoid a physiological/traumatic/intraosseous/sutures), donc ce n'est pas un simple doublon de contenu.
  • Non vérifié : si une personne a déjà exporté un JSON depuis l'éditeur et l'a réinjecté dans le repo. L'historique git ne montre que des commits de données directs (6eda7eb, f80e161).