Files
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

19 KiB

09. Modèle de données

Périmètre : toutes les structures de données en jeu dans une fiche anatomique et dans un bilan (types TypeScript, schémas Zod, attributs SVG, clés de stockage navigateur), avec pour chaque champ son caractère obligatoire ou optionnel et son origine (saisi, généré, calculé). Inclut le tableau "données statiques vs calculées" demandé en section 10 du brief.

Sources lues

  • src/anatomy/types.ts, src/anatomy/svgConvention.ts
  • src/domain/schema/findings.ts, observation.ts, report.ts, practitioner.ts, animal.ts
  • src/domain/species/types.ts, registry.ts, equine/index.ts, equine/vertebrae.ts
  • src/config/env.ts
  • src/lib/id.ts, src/app/routes/SvgEditorRoute.tsx, public/pathology-editor.html
  • src/state/reportStore.ts, localeStore.ts, practitionerCache.ts, src/app/routes/EditorRoute.tsx
  • src/pdf/export.ts, src/pdf/render/observationPage.ts, src/components/observation/ObservationCard.tsx
  • public/species/equine/Horse.svg, Horse_head.svg, pathologies.json

Légende des colonnes "Origine" : saisi (humain via éditeur ou formulaire), généré (code, sans intervention), calculé (dérivé à l'exécution, jamais écrit).

1. Couche SVG (anatomie)

1.1 Attributs data-anno-* sur les éléments SVG

FACTUEL, relevé par grep sur les deux SVG cheval.

Attribut Présences Lu par parseSvgBones Obligatoire selon le parser Écrit par l'éditeur SVG
data-anno-id 48 oui (svgConvention.ts:49) oui, non vide (:16-23) oui (SvgEditorRoute.tsx:1255,1277,1368)
data-anno-category 48 oui (:52) oui, non vide (:24-31) oui
data-anno-name-fr 47 oui (:50) non, '' par défaut oui si non vide (:1145)
data-anno-name-en 47 oui (:51) non oui si non vide (:1146)
data-anno-category-name 18 non non oui (:1150), libellé humain de la catégorie
data-anno-lateral 18 (toutes bilateral) oui (:56-59), cast sans validation non oui (:1160), valeurs bilateral ou absent
data-anno-special 5 (toutes vertebral-precision) oui (:55) non oui, hérité de la catégorie (:1154)
data-anno-opens-detail 1 (head) oui (:53-54) non oui (:1136), et supprime alors name/category

Autres faits sur les éléments annotés :

  • Chaque point est une paire de <circle> partageant le même data-anno-id : hitbox fill="transparent" pointer-events="all" (r=34 ou 30 dans Horse.svg, 27 dans Horse_head.svg) et visible pointer-events="none" (r=22 ou 18, resp. 15) qui porte aussi l'attribut id HTML égal au data-anno-id. Le parser regroupe les deux dans Bone.els (svgConvention.ts:61-74).
  • Chaque zone colonne est un seul <polygon> avec pointer-events="all".
  • Tous les éléments annotés sont enfants de <g id="osteo-overlays">, dernier enfant du <svg> (créé par SvgEditorRoute.tsx:1238-1243).
  • Chaque élément annoté contient un <title> texte FR / EN (ou 🔍 Zoom: head pour le déclencheur de détail), écrit par l'éditeur (:1172,1190). Jamais lu par l'application.
  • Coordonnées : cx, cy, r (cercles) et points (polygones), dans le repère du viewBox. Aucune transformation transform sur les overlays.

1.2 Bone (src/anatomy/types.ts:17-40)

Résultat du parse, jamais persisté.

Champ Type Origine Note
id string data-anno-id clé de Map<string, Bone> ; devient ObservationZone.boneId
fr string data-anno-name-fr '' si absent
en string data-anno-name-en '' si absent
category BoneCategory = string data-anno-category opaque, aucune branche de code dessus (types.ts:1-9)
opensDetail? string data-anno-opens-detail doit être une clé de SpeciesManifest.details, vérifié seulement au clic (EditorRoute.tsx:295)
special? string data-anno-special seule valeur consommée : vertebral-precision
lateral? 'bilateral' | 'unpaired' data-anno-lateral cast TypeScript, aucune validation runtime
els Element[] calculé tous les éléments DOM du même id

BoneState = 'current' | 'default' (types.ts:43), calculé par EditorRoute.tsx:186-195 à partir des zones de l'observation active.

SvgConventionError(message, boneId, missingAttribute) (types.ts:46-55), levée pour data-anno-id vide ou data-anno-category absent.

1.3 SpeciesManifest (src/domain/species/types.ts:16-32)

Code TypeScript compilé, un objet par espèce, découvert par import.meta.glob (registry.ts:16-19).

Champ Type Obligatoire Valeur cheval (equine/index.ts)
id string oui 'equine' ; doit égaler Animal.speciesId et, par convention non vérifiée, pathologies.json.species.id
labelFr, labelEn string oui 'Cheval', 'Horse'
mainSvg string oui '/species/equine/Horse.svg' (chemin HTTP absolu)
details Record<string, string> oui (peut être {}) { head: '/species/equine/Horse_head.svg' }
vertebralFormula VertebralFormula oui { C: 7, T: 18, L: 6, S: 5, Cd: 18 }
findings () => Promise<{ default: SpeciesFindings }> oui () => import('./pathologies')

VertebralFormula (types.ts:4-10) : cinq entiers C T L S Cd, régions fixes.

2. Couche catalogue (constats)

Schémas Zod dans src/domain/schema/findings.ts. Noms de champs en snake_case (BDR-009).

2.1 SpeciesFindings (findings.ts:56-66)

Champ Type Obligatoire Valeur réelle
schema_version string non vide oui "2.0" ; Zod ne vérifie pas la valeur (:57)
scope_disclaimer string non vide oui texte légal, affiché une fois par session
species.id string oui "equine"
species.name_fr, species.name_en string oui "Cheval", "Horse"
species.notes absent du schéma n/a documenté dans PATHOLOGIES-FORMAT.md:53,68 comme optionnel mais strippé par Zod ; absent des données
zones Record<string, ZoneFindings> oui 26 entrées, ordre d'insertion cranio-caudal

2.2 ZoneFindings (findings.ts:47-52)

Champ Type Obligatoire Note
id string oui dans les données, toujours égal à la clé du record (convention, non vérifiée par Zod). Devient Finding.zoneId
name_fr, name_en string oui seul lien avec le SVG, via matchZoneFindings
categories FindingNode[] oui 3 par zone dans les données

2.3 FindingNode (findings.ts:23-45, récursif via z.lazy)

Champ Type Obligatoire Présence dans les données
id string oui unique entre frères seulement (amplitude-asymmetry x11, anamnesis x26)
name_fr, name_en string oui 792/792
description_fr string non 62
description_en string non 0
requires_vet_referral boolean non 41 feuilles à true
sources SourceRef[] non 0
children FindingNode[] non absent ou vide = feuille (FindingsTreePicker.tsx:25-27)

SourceRef (findings.ts:15-19) : type enum manual|journal|database|web, citation non vide, url? validé par z.string().url(). Aucune instance dans le catalogue cheval.

Profondeur réelle : feuilles à profondeur 2 (catégorie > feuille) : 228 ; à profondeur 3 (catégorie > sous-catégorie > feuille) : 384. Aucune feuille plus profonde.

3. Couche bilan (report)

Schémas Zod dans src/domain/schema/. CamelCase.

3.1 Report (report.ts:13-31)

Champ Type Obligatoire Origine
version z.literal(2) oui généré (reportStore.ts:63)
id string oui généré crypto.randomUUID() (lib/id.ts)
createdAt string ISO oui généré nowIso()
date string ISO date oui saisi, défaut aujourd'hui
practitioner Practitioner oui saisi, préfill cache
animal Animal oui saisi ; speciesId défaut 'equine' (NewReportRoute.tsx:20)
owner Owner oui saisi
observations Observation[] oui saisi ; une observation vide créée à l'init (reportStore.ts:66-69)
conclusion, recommendations string oui, peut être '' saisi
nextAppointment? {kind:'date',date} ou {kind:'period',text} non saisi

Practitioner (practitioner.ts) : name requis, cabinet?, contact?, siret?. Animal (animal.ts) : speciesId requis, name requis, breed?, age? (chaîne libre). Owner : name requis.

3.2 Observation (observation.ts:51-59)

Champ Type Obligatoire Origine
id string oui généré UUID (reportStore.ts:31)
zones ObservationZone[] oui clics SVG + pickers
findings Finding[] oui FindingsTreePicker
freeTextFindings string[] oui saisi
severity? 'légère' | 'modérée' | 'sévère' non saisi ; valeurs françaises stockées telles quelles
comment string oui saisi

3.3 ObservationZone (observation.ts:21-30)

Champ Type Obligatoire Origine Note
boneId string oui data-anno-id cliqué identifiant opaque SVG (point-mpbwtst0)
detailSourceId? string non clé details du manifeste (head) absent pour une zone du SVG principal ; undefined sert de discriminant (observationPage.ts:223)
vertebrae? Vertebra[] non VertebraPicker uniquement sur les zones vertebral-precision
side? 'left' | 'right' non LateralityPicker une entrée par côté ; deux entrées pour un même boneId possibles

Vertebra : region enum C|T|L|S|Cd, index entier positif. Aucune borne haute vérifiée par Zod ; la borne vient de la formule à l'affichage.

3.4 Finding (observation.ts:40-47)

Champ Type Obligatoire Origine
zoneId string oui ZoneFindings.id du catalogue (pas le boneId)
path string[] min 1 oui ids de nœuds depuis categories jusqu'à la feuille
labelFrSnapshot, labelEnSnapshot string oui copie de name_fr/name_en de la feuille au clic (FindingsTreePicker.tsx:147-152)
requiresVetReferral? boolean non copie de requires_vet_referral
side? 'left' | 'right' non côté du picker ouvert

FACTUEL : rien dans Finding ne référence le boneId SVG, et rien dans ObservationZone ne référence le zoneId catalogue. La correspondance est reconstruite à chaque rendu par ObservationCard.tsx:126-145 via le matcher.

4. Configuration runtime

AppConfig (src/config/env.ts:10-15) : siteName, brandName, footerName, tagline, tous string, résolus window.__APP_CONFIG__ > VITE_APP_* > défauts. Sans rapport avec l'anatomie.

5. Génération des identifiants

Identifiant Générateur Forme Unicité Stabilité
data-anno-id d'un point SvgEditorRoute.tsx:1245 : 'point-' + Date.now().toString(36) point-mpbwtst0 par horodatage ms ; deux créations dans la même ms produiraient une collision (HYPOTHESE, non observé) stable tant que le fichier SVG est conservé ; sans signification
data-anno-id d'un polygone SvgEditorRoute.tsx:1353 : 'zone-' + Date.now().toString(36), ou id mémorisé lors d'un "redessiner" zone-mpbx5hx2 idem idem
id HTML de l'élément visible copie du data-anno-id (:1276,1367) identique fixDuplicateIds (:610-633) renomme en id-cat si un même id porte deux catégories
slug de catégorie SVG SvgEditorRoute.tsx:1574-1579 : minuscules, NFD, accents retirés, [^a-z0-9]+ → - charni-res-vert-brales, cadrans-du-cr-ne (HYPOTHESE : issus de "Charnières vertébrales" et "Cadrans du crâne" dont les lettres accentuées ont été remplacées par - au lieu d'être désaccentuées ; le code actuel :1574-1579 enchaîne toLowerCase, normalize('NFD'), suppression des diacritiques, ce qui devrait produire charnieres-vertebrales. Soit les slugs datent d'une version antérieure de l'éditeur, soit la classe de caractères [̀-ͯ] du fichier source ne couvre pas les diacritiques attendus. Non tranché sans exécuter l'éditeur) par nom
ZoneFindings.id / clé zones écrit à la main par l'auteur du catalogue, ou generateId(nameEn, nameFr, existingIds) (pathology-editor.html:912-922) : slug de name_en sinon name_fr, suffixe -2, -3 si collision hip, c0-c1 globale parmi les zones stable
FindingNode.id main, ou generateId avec existingIds = ids des frères (:1600-1602) restriction-flexion entre frères seulement stable
Report.id, Observation.id generateId() (src/lib/id.ts:5-13) = crypto.randomUUID(), repli horodatage + aléatoire UUID v4 globale stable dans le JSON attaché
clé details du manifeste saisie dans l'éditeur SVG (data-anno-opens-detail) et recopiée à la main dans index.ts head par espèce stable

6. Stockage navigateur

Clé Stockage Contenu Écrit par Lu par
osteo:draft sessionStorage Report JSON complet reportStore.ts:159-166 à chaque changement readPersistedDraft() à l'init (:42-56), validé par Zod
osteo:lastPractitioner localStorage Practitioner JSON practitionerCache.ts:21 NewReportRoute.tsx:25
osteo:locale localStorage 'fr' ou 'en' localeStore.ts:45, pathology-editor.html:767 les deux applications (partage de locale)
osteo:disclaimer-shown sessionStorage '1' EditorRoute.tsx:115 EditorRoute.tsx:158

Aucune donnée anatomique (SVG, catalogue) n'est stockée côté navigateur en dehors du cache HTTP.

7. Données statiques vs calculées (section 10 du brief)

Donnée Source Persistée ? Calculée ? Exemple
Zone (polygone) Horse.svg <polygon data-anno-id="zone-…"> oui, dans le SVG non zone-mpbx5hx2 cervicales
Point (cercle) Horse.svg paire <circle> oui, dans le SVG non point-mpbwtst0 hanche
ID SVG (data-anno-id) éditeur SVG, horodatage base 36 oui, SVG + ObservationZone.boneId dans le bilan non point-mpbwtst0
ID catalogue (zones.<key>, ZoneFindings.id) auteur du JSON oui, JSON + Finding.zoneId non hip
Label FR/EN d'une zone data-anno-name-fr/en oui, SVG seulement ; jamais copié dans le bilan résolu à l'affichage (boneLabel) et à l'export (buildZoneLabels) Hanche (coxo-fémorale) / Hip joint
Label FR/EN d'une feuille name_fr/name_en du JSON oui, JSON + snapshot dans Finding non Restriction en flexion
Coordonnées cx cy r / points oui, SVG non ; jamais copiées dans le bilan cx="1516" cy="695"
Rayon, couleur, opacité, trait attributs r fill fill-opacity stroke oui, SVG couleur réappliquée par catégorie au chargement dans l'éditeur SVG (applyAllCategoryColors, :666-677) ; remplacée par #b85a3f à l'export PDF (observationPage.ts:237-238) fill="#ff9500" fill-opacity="0.65"
Titre <title> éditeur SVG oui, SVG non ; jamais lu Hanche (coxo-fémorale) / Hip joint
Catégorie SVG data-anno-category (+ data-anno-category-name) oui, SVG la palette (couleur, nom, special, visibilité) est recalculée à chaque chargement dans l'éditeur par detectCategories (:635-664) ; non persistée ailleurs articulations
Latéralité d'une zone data-anno-lateral oui, SVG non bilateral
Côté choisi LateralityPicker oui, ObservationZone.side, Finding.side non left
Déclencheur de détail data-anno-opens-detail oui, SVG non head
Chemin du SVG de détail SpeciesManifest.details oui, code TS non /species/equine/Horse_head.svg
Origine détail d'une zone du bilan clé details oui, ObservationZone.detailSourceId non head
Région vertébrale d'une zone colonne aucune donnée explicite non oui, regionFromLabel(bone.fr ?? bone.en) (spineZones.ts:13-24) Vertèbres cervicales → C
Drapeau "ouvre le picker vertèbres" data-anno-special="vertebral-precision" oui, SVG non
Vertèbres choisies VertebraPicker oui, ObservationZone.vertebrae non [{region:'T',index:12}]
Formule vertébrale equine/vertebrae.ts oui, code TS non T: 18
Pathologie / feuille sélectionnée FindingsTreePicker oui, Finding{zoneId,path,snapshots} non ['hip-dysfunctions','articular','restriction-flexion']
Catégorie de constats ZoneFindings.categories[] oui, JSON non hip-dysfunctions
requires_vet_referral JSON oui, JSON + copie Finding.requiresVetReferral non true
Ordre d'affichage des zones du catalogue ordre d'insertion des clés JSON oui, implicite non ; le picker ne trie pas parietal en premier
Ordre des zones d'une observation ordre des clics oui, ordre du tableau zones syncSpineZones peut réordonner (ajout en fin)
Ordre des observations boutons haut/bas oui, ordre du tableau non
Traductions UI src/i18n/fr.ts, en.ts oui, code non vertebra.region.C
Traductions du catalogue name_fr/name_en par nœud oui, JSON non
Lien zone SVG ↔ zone catalogue aucune donnée non oui, matchZoneFindings({fr,en}, zones) à chaque rendu (ObservationCard.tsx:134) Hip joint → hip
zonesWithTree (pickers à afficher) dérivé non oui, useMemo (ObservationCard.tsx:126-145)
boneStates (surlignage) dérivé non oui, EditorRoute.tsx:186-195 Map{'point-mpbwtst0' → 'current'}
zoneLabels PDF dérivé non oui, re-fetch + re-parse de tous les SVG à l'export (export.ts:38-69)
Image des zones dans le PDF dérivé oui, PNG embarqué dans le PDF oui, rasterisation à l'export (observationPage.ts:214-255)
Version du bilan code oui, Report.version = 2 non 2
Version du catalogue JSON oui, schema_version non ; jamais comparée à quoi que ce soit "2.0"
Version du SVG aucune non non
Brouillon de session store oui, sessionStorage osteo:draft miroir de chaque set
Cache praticien formulaire oui, localStorage osteo:lastPractitioner non
Locale switcher ou navigateur oui, localStorage osteo:locale détection navigator.languages au premier lancement fr
Disclaimer vu clic "Compris" oui, sessionStorage osteo:disclaimer-shown non 1

Points non déterminés

  • HYPOTHESE : la collision d'data-anno-id par Date.now() est théorique ; aucun doublon n'existe dans les SVG commités.
  • La règle "ZoneFindings.id égale la clé du record" est respectée dans les 26 zones mais aucun code ne l'impose ; pathology-editor.html:1315-1316 crée les deux avec la même valeur.
  • Le slug charni-res-vert-brales est expliqué par le code de slugification de l'éditeur SVG (DEDUIT) ; la saisie d'origine ("Charnières vertébrales") n'est pas tracée dans le dépôt.