Files
faunosteo/docs/faunosteo-audit/10-current-limitations.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

17 KiB

10. Points à surveiller lors de la migration SaaS

Périmètre : dettes techniques, approximations et contraintes historiques de l'existant qui pèseront sur une migration vers une base PostgreSQL/Supabase et un modèle multi-praticiens. Chaque point cite sa preuve dans le code ou les données et décrit l'impact. Aucun schéma SQL n'est proposé ici.

Sources lues

  • src/anatomy/svgConvention.ts, src/anatomy/types.ts, src/anatomy/labels.ts
  • src/lib/zoneMatch.ts, src/lib/spineZones.ts
  • src/domain/schema/findings.ts, observation.ts, report.ts
  • src/domain/species/types.ts, registry.ts, equine/*
  • src/app/routes/EditorRoute.tsx, SvgEditorRoute.tsx
  • src/components/observation/ObservationCard.tsx, VertebraPicker.tsx, FindingsTreePicker.tsx
  • src/pdf/export.ts, src/pdf/attachment.ts, src/pdf/import.ts, src/pdf/render/observationPage.ts
  • public/pathology-editor.html, public/species/equine/*
  • docs/ANATOMY-SVG-CONVENTION.md, docs/PATHOLOGIES-FORMAT.md, CLAUDE.md, .claude/memory/decisions.md (BDR-013, BDR-017, BDR-019, BDR-021), .claude/audits/TOUR.md, .claude/audits/BUGS-FOUND.md

Classement : Critique (peut casser une migration ou corrompre des bilans), Important (devra être refactoré pour un SaaS), Faible (peut être conservé).

Critique

C1. Deux espaces d'identifiants reliés seulement par un libellé au moment du clic

FACTUEL : ObservationZone.boneId est le data-anno-id du SVG (observation.ts:23), Finding.zoneId est la clé du catalogue (observation.ts:41). Aucun des deux objets ne porte l'autre identifiant. Le lien est reconstruit à chaque rendu par matchZoneFindings({ fr: bone.fr, en: bone.en }, zonesArray) (ObservationCard.tsx:134-137), à partir des libellés lus dans le SVG.

Impact : un bilan stocké en base ne peut pas répondre à "quelle zone SVG porte ce constat" sans recharger le SVG et rejouer le matcher. Si un libellé change dans le SVG ou le catalogue, les anciens bilans perdent le lien zone ↔ picker (les findings restent affichés dans le PDF grâce aux snapshots, mais plus éditables sous la bonne zone). Une table de liaison explicite devra être créée à la migration, et les bilans existants devront être réconciliés par rejeu du matcher.

C2. Identifiants SVG opaques, non stables entre fichiers, non sémantiques

FACTUEL : point-mpbwtst0 (hanche), zone-mpbx5hx2 (cervicales) sont des horodatages base 36 (SvgEditorRoute.tsx:1245,1353). Le même point redessiné dans un nouveau SVG obtient un nouvel id. Deux espèces n'auront jamais le même id pour la "hanche".

Impact : un boneId n'a de sens que relativement à un fichier SVG précis. Le bilan ne stocke ni le nom ni la version de ce fichier (voir C5). Toute migration doit figer la paire (fichier SVG, data-anno-id) ou remplacer ces ids par des identifiants gérés en base.

C3. Matching par libellé, dupliqué en deux implémentations

FACTUEL : src/lib/zoneMatch.ts:110-130 (application) et public/pathology-editor.html:850-908 (éditeur, "ported from src/lib/zoneMatch.ts"). BDR-021 assume la duplication. Aucun test ne compare les deux. Le matcher accepte la sous-chaîne (score 1) et Levenshtein à 25 % (score 2+d) : "Hip" matcherait "Hip joint", et un libellé ambigu pourrait être rattaché à une mauvaise zone sans erreur.

État des données : 26/26 zones nommées des SVG cheval sont en égalité stricte FR et EN avec le catalogue (vérifié par comparaison de chaînes). Le repli flou n'est pas exercé par les données actuelles ; il reste le seul filet si une chaîne dérive.

Impact : en base, le lien doit devenir une clé étrangère. Le matcher ne doit servir qu'une fois, à la migration, puis disparaître du chemin de lecture.

Paires FR proches sous le seuil réel (FACTUEL, détail dans 06-svg-findings-link.md §3) : "Boulet ant. (métacarpo-phalangien)" / "Boulet post. (métatarso-phalangien)" à distance 5 pour un seuil de 7, "Vertèbres sacrales" / "Vertèbres caudales" à distance 3 pour un seuil de 4. Inatteignables tant que les 26 libellés EN restent strictement égaux ; une seule divergence EN suffirait à rattacher un boulet ou une région vertébrale à la mauvaise zone sans erreur (DEDUIT).

C8. L'éditeur SVG actuel produit un déclencheur de détail que l'application refuse

FACTUEL : quand la case "ouvre une vue détaillée" est cochée, applyEdit retire data-anno-category de l'élément (SvgEditorRoute.tsx:1135-1141). Le parser de l'application exige cet attribut sur tout élément porteur de data-anno-id et lève SvgConventionError sinon (svgConvention.ts:24-31). Le déclencheur réel zone-mpby55kd de Horse.svg a conservé data-anno-category="articulations", donc il passe ; DEDUIT : il a été produit par une version antérieure de l'outil ou édité à la main (03-svg-editor.md §4).

Impact : tout nouveau SVG de détail déclaré avec l'éditeur actuel casse le chargement de la fiche dans l'application tant que la catégorie n'est pas remise à la main. À connaître avant toute migration des outils d'édition.

C4. Le bilan dépend de fichiers externes qu'il ne nomme pas

FACTUEL :

  • labels des zones résolus à l'export par re-téléchargement et re-parse de species.mainSvg et species.details (export.ts:38-69) ; en cas d'absence, le PDF affiche le boneId brut (observationPage.ts:407, pickLocaleLabel(..., z.boneId)).
  • images du PDF produites par re-téléchargement et recoloration du SVG (observationPage.ts:214-255).
  • noms de zone du PDF pour les constats lus dans le catalogue courant (observationPage.ts:441-446), repli sur zoneId brut.
  • Report ne contient que animal.speciesId (report.ts:25, animal.ts:5) ; ni chemin, ni hash, ni version du SVG ou du catalogue.

Impact : un bilan ré-importé après modification ou retrait d'un SVG ou d'un catalogue se dégrade silencieusement. Pour un SaaS où une fiche anatomique peut être archivée, le bilan doit embarquer ou référencer une version immuable de la fiche (voir 08-report-and-pdf.md).

C5. Aucune structure n'est versionnée en dehors du bilan

FACTUEL : le SVG ne porte aucun attribut de version ; le manifeste est du code TypeScript compilé (equine/index.ts) ; schema_version du catalogue est seulement "non vide" pour Zod (findings.ts:57) et n'est comparé à rien ; Report.version est un literal 2 (report.ts:18) et un bilan v1 est refusé à l'import (attachment.ts:47-55, BDR-011) sans migration.

Impact : impossible aujourd'hui de savoir quel état de fiche a servi à produire un bilan donné. La migration devra attribuer rétroactivement une version "v0 cheval" à tous les bilans existants, par hypothèse.

C6. Deux copies manuelles du catalogue

FACTUEL : src/domain/species/equine/pathologies.json (bundlé, pathologies.ts:5) et public/species/equine/pathologies.json (fetché par pathology-editor.html:790). md5 identique aujourd'hui, aucun script de synchronisation, aucun test de parité. L'éditeur exporte un fichier pathologies-equine-<timestamp>.json téléchargé (pathology-editor.html:1648-1665) que l'humain doit recopier aux deux endroits puis rebuilder.

Impact : source de vérité ambiguë ; la migration doit choisir un seul dépôt (la base) et retirer les deux fichiers du chemin de lecture.

C7. Hypothèses cheval et colonne vertébrale codées en dur

FACTUEL :

  • VertebralRegionSchema = z.enum(['C','T','L','S','Cd']) (observation.ts:7) et REGIONS identique dans VertebraPicker.tsx:9. Une espèce sans région caudale ou avec une région supplémentaire ne peut pas être exprimée.
  • regionFromLabel (spineZones.ts:13-24) déduit la région par racines de mots FR/EN codées en dur (cervic, thorac/dors, lombair/lumbar, sacral/sacre, caudal/coccyg). Aucune donnée SVG ne déclare la région ; une zone colonne libellée autrement n'ouvre pas le bon onglet et syncSpineZones la laisse passer sans vertèbres (spineZones.ts:108-116).
  • VertebralFormula impose les cinq clés (species/types.ts:4-10).
  • Le catalogue cheval suit une structure "3 catégories par zone" (PATHOLOGIES-FORMAT.md:106-116) que rien ne vérifie et que le code n'exploite pas, mais que l'UI suppose implicitement lisible.

Impact : la modélisation vertébrale en base doit être portée par la fiche (régions et comptes déclarés), pas par un enum global.

Important

I1. Données dupliquées dans les SVG

FACTUEL : chaque point est une paire hitbox + visible portant les mêmes 5 à 7 attributs data-anno-* ; l'éditeur maintient la paire à la main (applyEdit, SvgEditorRoute.tsx:1134-1210, boucle siblings). data-anno-category-name (18 occurrences) répète le libellé humain de la catégorie sur chaque élément ; seul l'éditeur le lit. Horse_head.svg est une copie intégrale de Horse.svg (703 lignes, diff de 10 lignes : viewBox et groupe osteo-overlays), donc le dessin de fond du cheval est stocké deux fois.

Impact : en base, un élément = une ligne, la paire hitbox/visible et la catégorie deviennent des dérivés de rendu. Le "SVG de détail" est aujourd'hui un fichier complet, pas une fenêtre sur le principal (voir 04-detail-svg-generation.md).

I2. Données implicites

Donnée Où elle est implicite Preuve
région vertébrale d'une zone déduite du libellé spineZones.ts:13-24
"zone du SVG principal" absence de detailSourceId observationPage.ts:223, spineZones.ts:46
catégorie anamnesis partagée id non préfixé, 3 variantes de contenu selon les zones données JSON, PATHOLOGIES-FORMAT.md:115-116
vertèbres ↔ catalogue aucune feuille du catalogue n'est liée à une vertèbre précise ; les vertèbres ne qualifient que la zone observation.ts:27
ZoneFindings.id = clé du record convention non vérifiée findings.ts:47-52
le déclencheur de détail n'a pas de nom zone-mpby55kd sans name-fr/en, catégorie articulations héritée du défaut Horse.svg, dernier polygone
data-anno-lateral absent = non apparié aucune valeur unpaired dans les données ; le code teste === 'bilateral' (EditorRoute.tsx:314)

Impact : chaque implicite doit devenir une colonne ou une contrainte explicite.

I3. Chemins absolus et dépendance à public/

FACTUEL : mainSvg: '/species/equine/Horse.svg' (equine/index.ts:8), fetch runtime (svgLoader.ts:2), nginx.conf:19-21 force no-cache sur /species/. L'éditeur SVG et l'éditeur de constats fetchent les mêmes chemins (SvgEditorRoute.tsx:446, pathology-editor.html:790-794).

Impact : le SaaS devra servir les SVG depuis un stockage par tenant ou par fiche ; tous les appelants de loadSvg (4 sites) et les deux éditeurs sont à rebrancher.

I4. Findings orphelins

FACTUEL : retirer une zone (EditorRoute.tsx:370-375) ou élaguer une région via syncSpineZones (spineZones.ts:118) ne supprime pas les Finding dont le zoneId correspondait à cette zone. BDR-019 le documente comme "known wart (accepted)". Le PDF les imprime quand même (buildFindingsSections ne filtre pas sur les zones).

Impact : des bilans existants peuvent contenir des constats sans zone ; une contrainte d'intégrité en base les rejetterait. À nettoyer ou tolérer explicitement à la migration.

I5. Doc de convention SVG désynchronisée du parser

FACTUEL, docs/ANATOMY-SVG-CONVENTION.md vs src/anatomy/svgConvention.ts :

Doc dit Code fait
4 attributs obligatoires dont name-fr/name-en (:9-16) seuls id et category sont vérifiés (:15-32) ; zone-mpby55kd n'a pas de nom
7 catégories fermées articulation, charniere, spine-zone, os, os-overlay, head, cadran-crane (:28-38,107) toute chaîne acceptée (types.ts:1-9) ; les SVG réels utilisent articulations, charni-res-vert-brales, zone-colonne, cadrans-du-cr-ne, os
classes hitbox / visible classifiées en hitboxEls/visibleEls (:71-72,99) aucune lecture de class ; tout va dans els
états linked / multi (:138-139) supprimés (9d8267b), BoneState = 'current' | 'default'

Même écart dans docs/ADDING-A-SPECIES.md:94 ("Parser throws on unknown values"). Les templates de l'éditeur SVG (CATEGORY_TEMPLATES, SvgEditorRoute.tsx:276-282) et les règles CSS .hide-* (svg-editor.css:523-528) suivent encore les anciens noms.

Impact : prendre le code, pas la doc, comme spécification de départ.

I6. Catalogue : écarts avec les règles annoncées

FACTUEL :

  • CLAUDE.md:272 "Each entry needs ≥1 source with citation" ; 0 sources sur 792 nœuds.
  • zone sphenoid : première catégorie id: "ssb-dysfunctions" (pathologies.json:341), même id que la première catégorie de ssb (:895). DEDUIT : copier-coller. Sans effet runtime car les ids ne sont uniques qu'entre frères, mais ambigu pour une clé composée (zone, catégorie) en base.
  • species.notes documenté (PATHOLOGIES-FORMAT.md:68) mais absent du schéma et des données.
  • description_en : 0 sur 792 ; l'UI anglaise affiche undefined → rien (FindingsTreePicker.tsx:71-72).
  • scaffold-species.mjs:123 écrit schema_version: '1.1' pour une nouvelle espèce.

I7. Calculs non persistés à recalculer côté serveur ou à stocker

FACTUEL : zonesWithTree (ObservationCard.tsx:126-145), boneStates (EditorRoute.tsx:186-195), zoneLabels (export.ts:38-69), palette de catégories de l'éditeur (detectCategories, SvgEditorRoute.tsx:635-664, couleur lue sur le premier élément non transparent). Le PDF rasterise à l'export.

Impact : si le rendu PDF passe côté serveur, il faudra un DOM (ou un rasteriseur) et l'accès à la fiche versionnée.

I8. Éditeur SVG : 1 858 lignes impératives dans un useEffect

FACTUEL : SvgEditorRoute.tsx:247-1858, initSvgEditor() manipule le DOM directement, réinitialisé à chaque changement de locale (:31-47). BDR-017 et BDR-022 l'assument. Aucun test. Pas de modèle de données en mémoire : l'état est le DOM SVG lui-même, l'export est une sérialisation du DOM (exportSVG, :1823-1849).

Impact : pour éditer une fiche stockée en base (et non un fichier), il faudra extraire un modèle (éléments, attributs, catégories) de ce code, ou le réécrire. Voir 11-future-merge.md.

I9. PDF v1 refusé et JSON attaché non chiffré

FACTUEL : attachment.ts:44-57 lève IncompatibleReportVersionError pour toute version !== 2 ; import.ts:33-39 convertit en ImportError('incompatible_version'). Le JSON attaché est en clair dans le PDF (attachment.ts:19-28), nom osteo-report.json, description Faunosteo state v2 (brand codée en dur, TOUR CLN-9).

Impact : les PDF déjà émis sont la seule source de données historiques ; un import de masse devra accepter v2 et prévoir v1 si des PDF v1 existent chez les praticiens (HYPOTHESE : aucun en circulation, CHANGELOG 0.1.0 dit "no install base").

Faible

F1. Sanitisation SVG

FACTUEL : SvgEditorRoute.tsx:511-520 et pathology-editor.html:1127-1136 retirent script, foreignObject, attributs on*, hrefs javascript: sur les SVG importés par l'utilisateur. loadSvg (application) ne sanitise pas les SVG du projet (svgLoader.ts), ce qui est acceptable tant qu'ils viennent du dépôt. En SaaS multi-praticiens, un SVG uploadé par un tenant sera servi à d'autres utilisateurs : la sanitisation devra être côté serveur et au chargement.

F2. scope_disclaimer affiché une fois par session

FACTUEL : EditorRoute.tsx:155-160, drapeau sessionStorage. Comportement conservable ; la source du texte (catalogue) devra être rattachée à la fiche ou au tenant.

F3. data-anno-lateral="unpaired" jamais utilisé

FACTUEL : 0 occurrence dans les SVG ; le type l'accepte (types.ts:37), l'éditeur écrit soit bilateral soit rien (SvgEditorRoute.tsx:1159-1163). Peut devenir un booléen.

F4. data-anno-category-name redondant

Déjà traité en I1 ; conservable comme libellé de catégorie si une table de catégories est créée.

F5. Migration data-bone-* et fixDuplicateIds

FACTUEL : SvgEditorRoute.tsx:591-633. Code de compatibilité avec d'anciens SVG ; aucun fichier du dépôt ne le déclenche. Conservable ou supprimable, à décider lors de l'import des SVG en base.

F6. Sévérités stockées en français

FACTUEL : SeveritySchema = z.enum(['légère','modérée','sévère']) (observation.ts:3), utilisées comme clés i18n (severity.${s}). Conservable, mais une colonne enum en base devra reprendre ces valeurs accentuées ou migrer.

F7. Dépendances de rendu PDF à des logos et URLs codés en dur

FACTUEL : export.ts:111-137 (4 logos, dont /Paws_in_harmony.svg rasterisé), header.ts:63, footer.ts:53,89,104,110 (URLs). Hors périmètre anatomique ; à paramétrer par tenant.

F8. Lecture des title SVG et de data-anno-category-name uniquement par l'éditeur

Déjà couvert. Sans impact sur le bilan.

Points non déterminés

  • Existence de PDF v1 chez des praticiens (HYPOTHESE : aucun).
  • Origine exacte des slugs de catégorie mal désaccentués (charni-res-vert-brales) : version antérieure de l'éditeur ou saisie directe, non traçable dans git (le premier commit 8ca36b5 contient déjà ces valeurs ? non vérifié ligne à ligne).
  • Nombre de SVG hors dépôt annotés avec l'ancienne convention data-bone-* (justifierait ou non la conservation de migrateOldAttributes).