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

196 lines
17 KiB
Markdown

# 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`).