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.
22 KiB
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.jsonetpublic/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 |
| "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 copiesrc/. - 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 copiepublic/comme "read-only pour l'éditeur" et la copiesrc/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_enavec les attributs du SVG ; - que
requires_vet_referralne 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 :
src/domain/species/equine/pathologies.ts:11:SpeciesFindingsSchema.parse(data)au chargement du module. Un JSON invalide fait planter l'import.src/domain/species/equine/index.ts:13:findings: () => import('./pathologies'), chargement paresseux via le typeFindingsLoader(src/domain/species/types.ts:13).src/app/routes/EditorRoute.tsx:136:species.findings().then((m) => setFindings(m.default)). Le résultat alimenteObservationListet la modale de disclaimer (EditorRoute.tsx:159,findings.scope_disclaimer, affichée une fois par session via la clésessionStorageosteo:disclaimer-shown).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_CONFIGcodé en dur (l.786-796), une seule espèceequine, deux vues (/species/equine/Horse.svg,/species/equine/Horse_head.svg), un seul JSON/species/equine/pathologies.json. Il n'y a aucun lien avecsrc/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
.svget un.jsonobligatoires, chacun limité à 10 485 760 octets (l.1074-1075),currentSpeciesId = 'custom'.
3.3 Chargement (processSource, l.1109)
FACTUEL :
JSON.parsedu JSON ; erreurs affichées dans la barre latérale.- Validation minimale : présence de
schema_version,species,zones(l.1114-1116). Aucune validation Zod, aucune vérification de la forme des nœuds. - Parsing du SVG par
DOMParser,importNode, puis sanitisation : suppression de<script>et<foreignObject>, des attributson*et deshrefenjavascript:(l.1127-1135). - Ajout d'un
viewBoxsi absent, suppression dewidth/height. - Refus si aucun élément
[data-anno-id]. - Pose d'un seul listener
clicksur la racine SVG (setupSvgClickListener).
3.4 Clic sur une zone (handleZoneClick, l.1172)
FACTUEL :
- Lecture de
data-anno-id,data-anno-name-fr,data-anno-name-en,data-anno-opens-detailsur l'élément annoté le plus proche. - Surbrillance de tous les éléments portant ce
data-anno-id(highlightZone). - Si
data-anno-opens-detail:showNavZoneMessage(l.1263), message "zone de navigation", pas d'édition. - Si ni FR ni EN : retour à la barre latérale par défaut.
- Sinon
matchZone(nameFr, nameEn, Object.values(jsonData.zones))(l.896), copie inline desrc/lib/zoneMatch.ts(voir06-svg-findings-link.md). - Zone trouvée :
showZoneEditor(matched)(l.1326). SinonshowCreateZonePrompt(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'
idd'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
sourcesvient 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-dysfunctionssous la zonesphenoidest un copier-coller de la zonessb. Les feuilles des deux arbres diffèrent (sphenoidaphysiological/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).