# 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 `` 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 `` avec `pointer-events="all"`. - Tous les éléments annotés sont enfants de ``, dernier enfant du `` (créé par `SvgEditorRoute.tsx:1238-1243`). - Chaque élément annoté contient un `` 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` ; 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` | 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` | 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` `` | oui, dans le SVG | non | `zone-mpbx5hx2` cervicales | | Point (cercle) | `Horse.svg` paire `` | 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.`, `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 `` | é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.