Files
faunosteo/docs/faunosteo-audit/07-special-cases.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

18 KiB

07. Cas particuliers

Périmètre : chaque comportement conditionnel ("cas magique") que le code applique à partir des données SVG, du catalogue ou du rapport. Pour chaque cas : déclencheur, code, effet dans l'observation et le PDF, pièges.

Sources lues

  • src/anatomy/types.ts, src/anatomy/svgConvention.ts, src/anatomy/labels.ts, src/i18n/pickLocaleLabel.ts
  • src/app/routes/EditorRoute.tsx, src/app/routes/HomeRoute.tsx, src/app/routes/SvgEditorRoute.tsx
  • src/components/canvas/AnatomyCanvas.tsx, src/components/observation/*.tsx
  • src/lib/spineZones.ts, src/lib/zoneMatch.ts
  • src/domain/schema/observation.ts, src/domain/schema/report.ts, src/domain/schema/findings.ts
  • src/domain/species/equine/{index,vertebrae,pathologies}.ts, public/species/equine/pathologies.json
  • src/state/reportStore.ts, src/pdf/attachment.ts, src/pdf/import.ts, src/pdf/export.ts, src/pdf/render/observationPage.ts
  • public/species/equine/Horse.svg, public/species/equine/Horse_head.svg
  • .claude/memory/decisions.md (BDR-018, BDR-019), .claude/memory/blockers.md (BLK-003)

1. Colonne vertébrale : data-anno-special="vertebral-precision"

Déclencheur (FACTUEL) : 5 polygones de Horse.svg (zone-mpbx5hx2 cervicales, zone-mpbx2rpe thoraciques, zone-mpbx1rm9 lombaires, zone-mpbx0xnp sacrales, zone-mpbx00jq caudales), catégorie zone-colonne, attribut data-anno-special="vertebral-precision". Le parser le remonte dans Bone.special (svgConvention.ts:55), valeur opaque (types.ts:27-35).

Code :

  • Clic : onZoneClick teste bone.special === 'vertebral-precision' avant la latéralité (EditorRoute.tsx:309-312) et appelle handleSpineZone (EditorRoute.tsx:226-243) : ajoute la zone si absente, puis ouvre VertebraPicker sur son index. Un clic ne retire jamais une zone colonne (commentaire EditorRoute.tsx:222-225, retrait uniquement via ✕).
  • Picker : VertebraPicker (VertebraPicker.tsx:29-115), onglets C T L S Cd, grille de chips 1..formula[region], boutons tout cocher / tout décocher par région. Onglet initial = initialRegion (région déduite du libellé de la zone cliquée) sinon région du premier vertèbre sinon C (VertebraPicker.tsx:40-42).
  • Seed : collectSpineVertebrae(zones, bones, clickedBoneId) (spineZones.ts:56-79) : union dédoublonnée des vertèbres de toutes les zones colonne de l'observation, celles de la zone cliquée en premier. Une zone est "colonne" si elle n'a pas de detailSourceId et si son bone a le special (spineZones.ts:45-46).
  • Confirmation : syncSpineZones(fresh.zones, vertebrae, bones) (EditorRoute.tsx:470-482, spineZones.ts:93-131), autoritaire par région :
    • zone colonne existante dont la région a des vertèbres cochées → vertebrae remplacé ;
    • région cochée à zéro → la zone est supprimée (spineZones.ts:118) ;
    • région cochée sans zone existante → une zone est créée avec le boneId trouvé par findSpineZoneId (spineZones.ts:124-128, spineZones.ts:31-41) ; si le SVG n'a pas de zone pour cette région, les vertèbres sont perdues silencieusement (test drops vertebrae of a region with no spine zone in the SVG) ;
    • zones non colonne, zones de détail et zones au libellé non reconnu passent inchangées.
  • Bouton "Vertèbres…" dans la carte, affiché seulement si le bone a le special (ObservationCard.tsx:253-268), rouvre le picker sur cet index.

Effet : ObservationZone.vertebrae: { region, index }[] (observation.ts:11-14, observation.ts:27). Badge "Vertèbres lombaires (L1, L2)" (ObservationCard.tsx:52-57). PDF : même suffixe (observationPage.ts:408-410). Le libellé de zone est toujours imprimé, les vertèbres ne le remplacent pas (contrairement à docs/ANATOMY-SVG-CONVENTION.md:168-169 qui annonce "T12, T15 instead of the zone label").

Pièges :

  • Une zone colonne sans vertebrae (ajoutée par le clic, picker annulé) reste dans l'observation sans précision.
  • La suppression d'une région (pruning) laisse les findings dont le zoneId est le catalogue de cette région : rien ne les nettoie (BDR-019, "known wart"). Voir section 12.
  • Historique : le modèle additif de BDR-018 a été remplacé par BDR-019 le même jour. Le code actuel est BDR-019.

2. Régions vertébrales C / T / L / S / Cd

FACTUEL.

  • Enum VertebralRegionSchema = ['C','T','L','S','Cd'] (observation.ts:7), index int().positive() sans borne haute (observation.ts:13). Zod accepte C99.
  • Formule équine EQUINE_VERTEBRAL_FORMULA = { C: 7, T: 18, L: 6, S: 5, Cd: 18 } (vertebrae.ts:7-13), Cd plafonné à 18 par commentaire alors que l'espèce varie de 15 à 21. La formule ne borne que l'interface du picker (VertebraPicker.tsx:65), pas le schéma.
  • Région déduite du libellé par regionFromLabel (spineZones.ts:13-24) : normalisation NFD, minuscules, puis racines cervic → C, thorac ou dors → T, lombair ou lumbar → L, sacral ou sacre → S, caudal ou coccyg → Cd. Essai sur le FR puis sur l'EN. Première racine trouvée gagne : un libellé contenant deux racines est classé par ordre de test.
  • findSpineZoneId parcourt les bones avec special et prend le premier dont la région correspond (spineZones.ts:35-39). Deux zones colonne de même région : la première du Map gagne.

Pièges : le mapping zone ↔ région repose sur des sous-chaînes de libellés humains et non sur une donnée explicite ; une espèce dont la zone s'appelle "Rachis dorsal" serait classée T par dors, un libellé anglais "Back" ne serait pas reconnu.

3. Charnières vertébrales

FACTUEL. 4 points de catégorie charni-res-vert-brales : C0-C1 (point-mpbyqxbg, dans la tête), C7-T1 (point-mpbwyyc9), T18-L1 (point-mpbwyd9i), L6-S1 (point-mpbwxnb4). Aucun special, aucun lateral. Ils se comportent comme des zones simples (toggleZone). Le catalogue a une zone dédiée par charnière (c0-c1, c7-t1, t18-l1, l6-s1) avec le motif "segmental / muscular / mechanical" (docs/PATHOLOGIES-FORMAT.md:129). regionFromLabel("Charnière C7-T1 (cervico-thoracique)") renverrait C (racine cervic) mais n'est jamais appelé pour eux, faute de special.

4. Latéralité : data-anno-lateral="bilateral"

Déclencheur (FACTUEL) : 9 points du corps (18 éléments) : boulets antérieur et postérieur, jarret, grasset, hanche, sacro-iliaque, épaule, coude, sésamoïdes antérieurs. Parser : Bone.lateral (svgConvention.ts:56-59), typé 'bilateral' | 'unpaired' sans validation de valeur (une autre chaîne passe le cast).

Code :

  • onZoneClick teste bone.lateral === 'bilateral' après le cas colonne (EditorRoute.tsx:314-317) → handleBilateralZone (EditorRoute.tsx:246-270) :
    • si gauche et droite sont déjà présents pour ce (boneId, detailSourceId) → les deux zones sont retirées ;
    • sinon → LateralityPicker (LateralityPicker.tsx:25-58) avec trois boutons Gauche / Droite / Les deux, les côtés déjà présents étant désactivés.
  • onSelect ajoute une ObservationZone par côté manquant, avec side (EditorRoute.tsx:520-547).
  • Constats : ObservationCard construit un picker par couple (tree.id, side) (ObservationCard.tsx:126-145, clé tree.id:side). FindingsTreePicker filtre et écrit side sur chaque Finding (FindingsTreePicker.tsx:117-120, FindingsTreePicker.tsx:153).

Effet : ObservationZone.side et Finding.side (observation.ts:29, observation.ts:46). Badge "Hanche (coxo-fémorale) (G)" (ObservationCard.tsx:59-64). PDF : suffixe (Gauche) sur la zone et sur l'en-tête de section de constats (observationPage.ts:411-413, observationPage.ts:447-450).

Pièges :

  • Aucune différenciation visuelle gauche/droite sur le SVG : boneStates est indexé par boneId seul (EditorRoute.tsx:186-195), les deux côtés allument le même point.
  • Même catalogue pour les deux côtés (exclusion explicite dans la spec latéralité, section 9).
  • Une zone bilatérale déjà sélectionnée d'un seul côté ne peut pas être retirée par clic : il faut le ✕ ou ajouter l'autre côté puis recliquer.
  • Une zone colonne bilatérale serait traitée comme colonne (ordre des if).

5. Zones sans latéralité

FACTUEL. Absence d'attribut → Bone.lateral undefined → flux toggleZone (EditorRoute.tsx:273-288), clic = bascule. La valeur unpaired acceptée par le type n'apparaît dans aucun SVG (0 occurrence) et n'est testée nulle part dans l'application ; l'éditeur SVG l'exprime par l'absence d'attribut (SvgEditorRoute.tsx:169, option vide).

6. Zones ouvrant un détail

Voir 04-detail-svg-generation.md. Rappel : test bone.opensDetail && species?.details[...] en tête de onZoneClick (EditorRoute.tsx:295-298), avant toute autre règle, et retour immédiat : le déclencheur n'est jamais une zone d'observation.

7. Tête

FACTUEL. Horse_head.svg porte 9 points et quatre catégories dans le même fichier : cadrans-du-cr-ne (pariétal, frontal, sphénoïde, temporal, occipital), articulations (ATM, SSB), os (hyoïde), charni-res-vert-brales (C0-C1). Aucun polygone, aucun special, aucun lateral. Toutes les zones cliquées depuis le modal reçoivent detailSourceId: 'head'.

Effet PDF : image "VUE DÉTAIL — HEAD" rendue sans halo (observationPage.ts:230-231). Si l'observation ne contient que des zones de tête, la vue générale n'est pas rendue (observationPage.ts:367).

Piège historique : BLK-003, les clics dans le détail étaient ignorés tant que detailBones n'existait pas. Le correctif est le ?? detailBones.get(boneId) (EditorRoute.tsx:292).

8. Points de catégorie os

FACTUEL. Deux points : sésamoïdes antérieurs (point-mpbwwxvn, bilatéral, corps) et hyoïde (point-mpbyq841, tête). Aucun traitement spécifique : la catégorie est opaque (types.ts:1-9). Ils apparaissent dans le catalogue comme fore-sesamoids et hyoid.

9. Catégories

FACTUEL types.ts:1-9 et svgConvention.ts:11-13 : data-anno-category est une chaîne libre, exigée non vide, jamais interprétée par l'application. Le test accepts any string as data-anno-category le garantit. Seuls opensDetail, special et lateral pilotent un comportement. Les sept "valid categories" de docs/ANATOMY-SVG-CONVENTION.md:28-38 ne sont ni celles des SVG ni vérifiées par le code : ce document est périmé sur ce point.

data-anno-category-name (18 occurrences) n'est lu que par l'éditeur SVG (SvgEditorRoute.tsx:640), jamais par parseSvgBones.

10. Zones générées par l'éditeur

FACTUEL. Préfixes point- et zone- + horodatage base 36 (SvgEditorRoute.tsx:1245, SvgEditorRoute.tsx:1353). Pas de signification pour l'application. fixDuplicateIds (SvgEditorRoute.tsx:610-633) peut renommer un id en <id>-<cat> au chargement dans l'éditeur si un même id porte deux catégories ; un tel renommage casserait les boneId déjà présents dans des PDF exportés (DEDUIT : ObservationZone.boneId est comparé en égalité stricte).

11. Zones supprimées

FACTUEL, trois sens différents, aucun lien entre eux :

  • Suppression dans l'éditeur SVG (SvgEditorRoute.tsx:1216-1231) : le fichier téléchargé n'a plus l'élément. Le catalogue pathologies.json garde sa zone (il est indépendant). Un rapport existant garde son boneId : badge et PDF retombent sur l'id brut (section 13).
  • Suppression dans le catalogue (éditeur de pathologies) : le SVG garde son élément ; le clic ne trouve plus de catalogue (observation.findings_no_catalog) ; les Finding existants gardent leurs snapshots.
  • Retrait d'une zone d'observation via ✕ (EditorRoute.tsx:370-375, ObservationCard.tsx:269-276) ou pruning colonne : observation.findings n'est pas filtré.

12. Constats orphelins

Définition : un Finding dont zoneId ne correspond plus à aucune zone de observation.zones (après ✕, pruning, ou édition du catalogue).

FACTUEL :

  • UI : zonesWithTree est dérivé de observation.zones (ObservationCard.tsx:126-145) ; un constat orphelin n'est affiché dans aucun picker, mais reste compté dans findingCount (ObservationCard.tsx:95-96).
  • PDF : buildFindingsSections itère sur observation.findings seuls (observationPage.ts:420-463) ; les orphelins sont imprimés dans leur section CONSTATS — <ZONE>, le nom de zone venant du catalogue courant ou, à défaut, de zoneId brut (observationPage.ts:441-446).
  • Import PDF : le schéma n'impose aucune cohérence entre findings[].zoneId et zones[] (observation.ts:51-59).

13. Fallbacks

FACTUEL :

Situation Fallback Code
Libellé manquant dans la locale autre langue, puis valeur de repli (en général boneId) pickLocaleLabel.ts:8-16, labels.ts:12-19
Aucune observation dépliée au clic la dernière observation est activée, le clic est perdu (il faut recliquer) EditorRoute.tsx:215-220, EditorRoute.tsx:300-303
Bone inconnu (id absent des deux maps) clic ignoré silencieusement EditorRoute.tsx:292-293
Catalogue non chargé (findings null) message "choisir une zone / pas de catalogue" ; PDF imprime zoneId brut ObservationCard.tsx:287-292, observationPage.ts:441-446
zoneLabels sans l'id PDF imprime boneId brut observationPage.ts:406-407
Détail SVG en 404 avertissement console, les autres labels survivent EditorRoute.tsx:149-151, export.ts:62-64
Zone sans match catalogue aucun picker, les zones sans libellé (déclencheur) aussi ObservationCard.tsx:132-138
Logo manquant PDF sans logo export.ts:111-137

14. Matching approximatif

Résumé : le lien SVG → catalogue passe par les libellés FR/EN normalisés, EN d'abord, FR ensuite, Levenshtein en dernier recours (zoneMatch.ts:110-130). Sur les données actuelles, 26 zones sur 26 sont en égalité stricte et aucun fuzzy n'est exercé. Détail et exemples dans 06-svg-findings-link.md.

15. Données invalides

FACTUEL :

Entrée Contrôle Conséquence
Élément SVG sans data-anno-id ou data-anno-category SvgConventionError (svgConvention.ts:15-32) loadSvg(...).then(parseSvgBones) rejette ; dans EditorRoute.tsx:135 la promesse n'a pas de catch : la carte des bones reste vide, l'erreur part en console
SVG non parsable ou racine non <svg> loadSvg lève (svgLoader.ts:8-15) idem
pathologies.json invalide SpeciesFindingsSchema.parse au chargement du module (pathologies.ts:11) le chunk lazy échoue ; species.findings() rejette sans catch dans EditorRoute.tsx:136
Brouillon sessionStorage invalide safeParse silencieux (reportStore.ts:42-52) démarrage à vide
PDF importé : pas un PDF ImportError('invalid_pdf') (import.ts:27-31) message i18n (HomeRoute.tsx:29-44)
PDF importé : version ≠ 2 IncompatibleReportVersionError → ImportError('incompatible_version', v) (attachment.ts:44-57) message avec numéro de version
PDF importé : JSON non conforme ou absent ImportError('no_attachment') (import.ts:38) message générique, la cause Zod est perdue
Pièce jointe compressée > 16 Mo inflateFlate renvoie null (attachment.ts:68-98) on retombe sur les octets bruts, qui échouent au JSON.parse
Catalogue : url de source invalide z.string().url() (findings.ts:18) parse refusé

Note : le catalogue actuel n'a aucune sources (0 occurrence) malgré la règle CLAUDE.md "Each entry needs ≥1 source". Rien ne l'impose dans le schéma.

16. Compatibilité de versions

FACTUEL :

  • ReportSchema.version = z.literal(2) (report.ts:18). Un rapport v1 est refusé à l'import avec incompatible_version, aucune migration (BDR-011, test rejects a legacy v1 PDF). Un v3 est refusé de la même façon.
  • schema_version du catalogue ("2.0") est une chaîne non vide jamais comparée (findings.ts:57). L'éditeur de pathologies vérifie seulement sa présence (pathology-editor.html:1114). scaffold-species.mjs:123 écrit encore "1.1".
  • Anciens attributs data-bone-* : migrés uniquement par l'éditeur SVG (SvgEditorRoute.tsx:591-608), jamais par l'application.
  • Les champs inconnus du JSON de catalogue sont supprimés par Zod (z.object par défaut), ceux du rapport aussi : un futur champ ajouté à un PDF par une version plus récente disparaît au réimport par une version plus ancienne.
  • La description de pièce jointe "Faunosteo state v2" et le nom osteo-report.json (attachment.ts:4, attachment.ts:19-27) sont des constantes de contrat ; l'extraction cherche un nom commençant par osteo-report (attachment.ts:35).

17. Autres cas ponctuels

  • Disclaimer : affiché une fois par onglet via sessionStorage['osteo:disclaimer-shown'] (EditorRoute.tsx:33, EditorRoute.tsx:113-118, EditorRoute.tsx:155-160), texte = scope_disclaimer du catalogue.
  • sphenoid : sa première catégorie porte l'id ssb-dysfunctions (pathologies.json, zone sphenoid), unique écart à la règle "id de catégorie préfixé par la zone" (docs/PATHOLOGIES-FORMAT.md:111-112). Aucun effet fonctionnel : les ids ne sont uniques qu'entre frères et le chemin d'un Finding est ancré à la zone.
  • anamnesis : même id dans les 26 zones, mais trois contenus distincts selon la zone (comptage jq). Le Finding.path ne distingue pas ces variantes autrement que par zoneId.
  • Ids de nœuds dupliqués entre zones : amplitude-asymmetry apparaît 11 fois, articular 9 fois, etc. Toute recherche de nœud doit partir de la zone (FindingsTreePicker.tsx:45-57).
  • Sévérité : enum en français légère | modérée | sévère dans le schéma (observation.ts:3), persistée telle quelle, traduite à l'affichage par les clés severity.*.
  • Clic sur le déclencheur de détail depuis pathology-editor.html : message "zone de navigation" sans édition (pathology-editor.html:1181, pathology-editor.html:1263-1284).

Points non déterminés

  • Comportement exact en cas de SvgConventionError dans EditorRoute (DEDUIT : rejet de promesse non attrapé, bones vide, canvas affiché sans interaction). Non testé.
  • HYPOTHESE sur joint-detail : suggestion sans consommateur, probablement une intention abandonnée.