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.
This commit is contained in:
bastien committed 2026-10-06 23:51:35 +02:00
1 parent 83e40af99b
commit e471d41c6b
70 files changed
+22075

No files matched your search

@@ -0,0 +1,127 @@
# 04. SVG de détail (zoom) : comment la tête du cheval a été construite
Périmètre : mécanisme réel qui relie `Horse.svg` à `Horse_head.svg`, de la production du fichier jusqu'au PDF, et ce qui manque pour généraliser "sélectionner une zone → générer un SVG zoomable".
## Sources lues
- `public/species/equine/Horse.svg`, `public/species/equine/Horse_head.svg` (diff complet)
- `src/domain/species/equine/index.ts`, `src/domain/species/types.ts`
- `src/app/routes/SvgEditorRoute.tsx` (bloc "opens detail")
- `src/app/routes/EditorRoute.tsx`, `src/components/canvas/DetailModal.tsx`, `src/components/canvas/AnatomyCanvas.tsx`
- `src/anatomy/svgConvention.ts`
- `src/domain/schema/observation.ts`
- `src/pdf/export.ts`, `src/pdf/render/observationPage.ts`, `src/pdf/render/svgToPng.ts`
- `public/pathology-editor.html`
- `scripts/scaffold-species.mjs`
- `docs/ANATOMY-SVG-CONVENTION.md`
- historique git des deux SVG
## 1. Constat central
FACTUEL. Aucun code du dépôt ne génère un SVG de détail. Un `grep viewBox` sur `src/`, `scripts/` et `public/pathology-editor.html` ne renvoie que trois usages : la valeur par défaut posée au chargement quand l'attribut manque (`SvgEditorRoute.tsx:543-549`, `pathology-editor.html:1139-1143`) et la lecture du ratio pour dimensionner le PNG de rasterisation (`svgToPng.ts:29-41`). Aucune fonction ne lit un polygone pour en dériver un cadrage, ne découpe un SVG, ne recalcule des coordonnées, ni n'écrit un fichier.
FACTUEL. Ce que fait l'éditeur SVG : poser `data-anno-opens-detail="<id>"` sur un polygone existant et retirer ses attributs de nommage/catégorie (`SvgEditorRoute.tsx:1131-1141`). Voir `03-svg-editor.md`, section 6.3.
FACTUEL. Le lien entre cet id et un fichier est déclaré à la main dans le manifeste d'espèce :
```ts
// src/domain/species/equine/index.ts:8-11
mainSvg: '/species/equine/Horse.svg',
details: {
head: '/species/equine/Horse_head.svg',
},
```
Le type `SpeciesManifest.details` est un `Record<string, string>` dont les clés doivent correspondre aux valeurs de `data-anno-opens-detail` (`src/domain/species/types.ts:22-28`). Le script `scripts/scaffold-species.mjs:138-155` demande ces clés et chemins à l'opérateur ; il ne crée pas le fichier SVG.
## 2. Anatomie du fichier `Horse_head.svg`
FACTUEL (diff `Horse.svg` ↔ `Horse_head.svg`, 10 lignes de diff sur 704 lignes chacun) :
| Élément | `Horse.svg` | `Horse_head.svg` |
|---|---|---|
| `viewBox` racine | `0 0 2073.4 1629.4` | `60 100 500 380` |
| Lignes 3 à 703 (dessin complet du cheval : gradients, filtres, `<g>` et `<path>`) | identiques | identiques |
| Ligne 704, groupe `<g id="osteo-overlays">` | 12 points + 5 polygones colonne + 1 polygone déclencheur | 9 points |
Conséquences factuelles :
- Le fichier de détail contient l'intégralité du dessin du corps. Seul le `viewBox` recadre l'affichage sur la tête. Le poids du fichier est dupliqué.
- Les coordonnées des points de la tête sont exprimées dans le repère du SVG principal. Exemple : `point-mpbykomv` (Pariétal) à `cx="348" cy="161"`, compris dans la fenêtre `x ∈ [60, 560]`, `y ∈ [100, 480]`. Aucune translation, aucune mise à l'échelle.
- Les rayons des points de la tête (`r=27` / `r=15`) sont plus petits que ceux du corps (`r=34` / `r=22`), ce qui est cohérent avec un dessin à une échelle d'affichage plus grande. Ce choix est manuel.
FACTUEL. Le polygone déclencheur `zone-mpby55kd` dans `Horse.svg` a 15 sommets, boîte englobante `x ∈ [164, 454]`, `y ∈ [150, 468]`. Cette boîte est incluse dans la fenêtre `60 100 500 380` du détail mais n'en est pas égale, et aucun code ne compare les deux.
DEDUIT. Le fichier a été produit à la main : copie de `Horse.svg`, édition du `viewBox`, puis ajout des 9 points probablement via l'éditeur SVG (les points portent les mêmes attributs, le même groupe `osteo-overlays`, les mêmes `<title>` "FR / EN" que ceux que produit `addCircleAt` + `applyEdit`). L'historique git ne contient pas de script ni de commit intermédiaire : `Horse_head.svg` entre au commit de scaffold `8ca36b5` puis est modifié par les renommages d'attributs et l'adoption du catalogue v2.0.
## 3. Réponses aux dix questions du brief
1. Comment la zone sélectionnée est choisie : il n'y a pas de sélection logicielle. L'auteur du SVG dessine un polygone en mode `polygon`, le sélectionne et coche "Cette zone ouvre une vue détaillée" en saisissant un id (`SvgEditorRoute.tsx:136-152`).
2. Comment le contour est récupéré : il ne l'est pas. Les `points` du polygone ne sont lus par aucun code en dehors du drag et des poignées de l'éditeur.
3. Comment le nouveau SVG de détail est créé : manuellement, hors de l'application (section 2).
4. Transformations : aucune.
5. Recalcul des coordonnées : aucun, même repère.
6. Calcul du `viewBox` : manuel. Valeur `60 100 500 380`, non reliée au polygone.
7. Comment le parent sait qu'un détail existe : deux déclarations indépendantes. (a) L'attribut `data-anno-opens-detail="head"` sur l'élément du SVG parent, lu par `parseSvgBones` dans `Bone.opensDetail` (`svgConvention.ts:53-54`). (b) La clé `head` dans `species.details`. Le clic n'ouvre le détail que si les deux existent : `if (bone.opensDetail && species?.details[bone.opensDetail])` (`EditorRoute.tsx:295`). Un attribut sans clé de manifeste est silencieusement ignoré et le clic tombe dans le flux "zone normale" (DEDUIT du `if` suivant, `EditorRoute.tsx:300-319` : le déclencheur n'a pas de `special` ni de `lateral`, il serait donc ajouté comme zone via `toggleZone`).
8. Chargement dans l'application :
- au montage de l'éditeur de bilan, tous les fichiers de `species.details` sont préchargés et parsés dans `detailBones`, chaque fetch étant indépendant (`EditorRoute.tsx:138-152`) ;
- au clic sur le déclencheur, `handleDetailOpen` pose l'état `detail = { id, src, title }` (`EditorRoute.tsx:202-208`), titre = libellé du bone ou id ;
- un effet reparse le détail ouvert et le fusionne dans `detailBones` sans écraser les ids déjà connus (`EditorRoute.tsx:162-173`, `mergeBones` `EditorRoute.tsx:36-42`) ;
- `DetailModal` rend un `AnatomyCanvas` avec `src=detailSrc` dans un `Dialog` `xl`, et remonte chaque clic sous la forme `(boneId, detailId)` (`DetailModal.tsx:27-33`) ;
- `onZoneClick(boneId, detailSourceId)` résout le bone par `bones.get(boneId) ?? detailBones.get(boneId)` (`EditorRoute.tsx:292`) et crée une `ObservationZone` portant `detailSourceId` (`EditorRoute.tsx:234-237`, `EditorRoute.tsx:279-282`, `EditorRoute.tsx:537-543`).
9. Données permettant de retrouver le détail : `ObservationZone.detailSourceId` (`observation.ts:24-25`), valeur = clé de `details` (`head`). Le chemin du fichier n'est jamais persisté ; il est re-résolu via le manifeste de l'espèce du rapport à chaque rendu et à chaque export.
10. Limites : section 5.
## 4. Propagation jusqu'au PDF
FACTUEL `observationPage.ts:361-395` (`buildObservationImages`) :
- une image "VUE GÉNÉRALE" (`pdf.view.general`) est rendue si au moins une zone n'a pas de `detailSourceId` ;
- une image par `detailSourceId` distinct présent dans l'observation, libellée `pdf.view.detail_prefix` + id en majuscules (`observationPage.ts:380`), soit "VUE DÉTAIL — HEAD" ;
- un `detailSourceId` absent du manifeste est ignoré sans erreur (`observationPage.ts:377-378`).
FACTUEL `observationPage.ts:214-255` (`colorizedSvgString`) : recharge le fichier SVG, ne conserve en couleur que les zones dont `detailSourceId` est égal à celui de la vue, masque les autres (`display="none"`), applique un halo flou seulement sur la vue générale, retire tous les attributs `data-anno-*` avant sérialisation.
FACTUEL `export.ts:38-69` (`buildZoneLabels`) : les libellés imprimés proviennent du re-parse de `mainSvg` et de chaque `details` au moment de l'export, par id. Un détail introuvable produit un avertissement console et le PDF imprime l'id brut (`observationPage.ts:406-407`).
## 5. Limites actuelles
| Limite | Preuve |
|---|---|
| Un seul niveau de détail en pratique | DEDUIT. Si un SVG de détail portait `data-anno-opens-detail`, le parser le lirait et `onZoneClick` l'honorerait depuis le modal (le bone vient de `detailBones`, `EditorRoute.tsx:292-298`) : `setDetail` remplacerait le détail courant dans le même modal. Mais `buildObservationImages` ne rend qu'une image par `detailSourceId` sans hiérarchie, et le `detailSourceId` d'une zone cliquée dans ce second détail serait la clé du second détail, sans trace du chemin. Rien ne l'interdit, rien ne le gère. |
| Le déclencheur n'est jamais persisté | FACTUEL `EditorRoute.tsx:295-298` : `handleDetailOpen` puis `return` avant tout ajout de zone. `docs/ANATOMY-SVG-CONVENTION.md:155` le documente. Il n'a pas de nom, donc aucun match catalogue (`06-svg-findings-link.md`). |
| Espace d'ids partagé entre principal et détails | FACTUEL `EditorRoute.tsx:175-181` et `mergeBones` : premier arrivé conservé, collision silencieuse. Les ids sont des horodatages base 36 générés sans registre (`03-svg-editor.md` E). |
| Le tooltip masque les déclencheurs | FACTUEL `AnatomyCanvas.tsx:93` : `!el.hasAttribute('data-anno-opens-detail')`. Le polygone de la tête n'affiche aucun libellé au survol (il n'en a pas). |
| Fichier dupliqué | FACTUEL section 2 : 703 lignes identiques. |
| Aucune métadonnée de cadrage persistée | FACTUEL : ni le polygone ni le manifeste ne stockent la fenêtre `60 100 500 380` ; seule la racine du fichier de détail la porte. |
| Liste d'espèces codée en dur dans l'éditeur de pathologies | FACTUEL `pathology-editor.html:786-796` : `SPECIES_CONFIG` répète `Horse.svg`, `Horse_head.svg` et `pathologies.json` indépendamment du manifeste TypeScript. Un nouveau détail doit être ajouté à deux endroits. |
| Chemins absolus `/species/...` | FACTUEL manifeste + `loadSvg(publicPath)` (`svgLoader.ts:1-2`). Les fichiers doivent être servis à la racine web. |
| Le détail ne sait pas d'où il vient | FACTUEL : `Horse_head.svg` ne contient aucune référence à `Horse.svg` ni à `zone-mpby55kd`. |
| Préchargement sans mise en cache | FACTUEL : `EditorRoute` précharge au montage, `DetailModal` recharge à chaque ouverture (`AnatomyCanvas` effet `[src]`), `buildZoneLabels` et `colorizedSvgString` rechargent à l'export. Quatre fetch du même fichier au minimum. |
## 6. Généralisation « sélectionner une zone → générer automatiquement un SVG zoomable »
Ce qui existe déjà et pourrait servir de matière (FACTUEL) :
- un polygone de zone avec ses `points` dans le repère du SVG (`finalizePolygon`, `SvgEditorRoute.tsx:1357-1360`) ;
- la conversion écran → repère SVG (`getSVGPoint`, `SvgEditorRoute.tsx:927-932`) ;
- un `viewBox` racine toujours présent après chargement (`SvgEditorRoute.tsx:543-549`) ;
- l'identité structurelle parent/détail : même dessin, même repère, seul le `viewBox` diffère, ce qui rend le "zoom par viewBox" trivial à produire par copie ;
- le contrat de liaison déjà en place côté application : attribut `data-anno-opens-detail` + entrée `details` + `detailSourceId` sur la zone d'observation, qui fonctionne pour n'importe quel nombre de détails tant que chaque id est unique ;
- la sérialisation et le téléchargement d'un SVG (`exportSVG`).
Ce qui manque (FACTUEL, absent du code) :
- calcul d'une boîte englobante à partir des `points` d'un polygone, avec marge ;
- écriture d'un second fichier avec ce `viewBox`, ou d'un `viewBox` par détail stocké dans un format de données ;
- enregistrement du mapping id → fichier ailleurs que dans un fichier TypeScript édité à la main ;
- un espace d'ids distinct ou préfixé par détail ;
- une gestion de la profondeur (détail de détail) dans les zones d'observation et dans le PDF ;
- un mécanisme d'écriture (l'éditeur ne peut que télécharger).
Aucune solution n'est proposée ici ; voir `11-future-merge.md` pour la liste des points de couplage.
## Points non déterminés
- Outil exact utilisé pour produire `Horse_head.svg` (éditeur SVG du projet, éditeur de texte, Inkscape). HYPOTHESE : éditeur SVG du projet pour les points, édition manuelle pour le `viewBox`.
- Comportement réel d'un détail imbriqué : DEDUIT de la lecture, jamais testé (aucun test ni fixture n'en contient).