Files
faunosteo/docs/faunosteo-audit/01-repository-map.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

19 KiB

01. Carte du repository

Périmètre : arborescence réelle du dépôt (branche develop, tête 83e40af), rôle de chaque fichier pertinent pour la fiche anatomique, graphe des imports, points d'entrée, build et déploiement, et la liste des fichiers nécessaires à la reconstruction d'une fiche anatomique (section 9 du brief).

Sources lues

  • git ls-files (inventaire complet, 177 fichiers hors .claude/)
  • index.html, src/main.tsx, src/app/App.tsx, src/app/routes/*.tsx
  • vite.config.ts, vitest.config.ts, package.json, Dockerfile, docker/nginx.conf, docker/entrypoint.sh
  • src/anatomy/*, src/lib/*, src/domain/**, src/state/*, src/components/**, src/pdf/**, src/i18n/*
  • public/species/equine/*, public/pathology-editor.html, public/assets/, public/brand/, logos/
  • scripts/scaffold-species.mjs, docs/*.md, docs/superpowers/**
  • .claude/audits/TOUR.md, .claude/audits/BUGS-FOUND.md (lus, non copiés)

1. Arborescence commentée

Seuls les fichiers utiles à la compréhension des éditeurs et des données sont commentés. Les lignes sans commentaire sont présentes dans le dépôt mais hors périmètre.

faunosteo/
├─ index.html                     entrée SPA, charge /env.js puis src/main.tsx
├─ package.json                   scripts dev/build/test/lint, scaffold:species
├─ vite.config.ts                 alias @ → src/, plugins react-swc + tailwind
├─ vitest.config.ts               happy-dom, include tests/**/*.test.ts(x)
├─ Dockerfile                     multi-stage node:20-alpine → nginx:1.31-alpine, USER nginx
├─ docker-compose.yml
├─ docker/entrypoint.sh           écrit env.js (window.__APP_CONFIG__) au démarrage
├─ docker/nginx.conf              SPA fallback, /species/ en Cache-Control: no-cache
├─ README.md, CHANGELOG.md, DEPLOY.md, CLAUDE.md, LICENSE
├─ .githooks/                     hooks gitflow (hors périmètre)
├─ logos/                         sources SVG/PNG de la marque + generate-sizes.sh
├─ scripts/scaffold-species.mjs   génère le squelette d'une espèce (index.ts, vertebrae.ts, pathologies.ts/json)
├─ docs/
│  ├─ ANATOMY-SVG-CONVENTION.md   contrat data-anno-* (partiellement obsolète, voir §6)
│  ├─ ADDING-A-SPECIES.md         recette d'ajout d'espèce
│  ├─ PATHOLOGIES-FORMAT.md       contrat du catalogue JSON v2.0
│  ├─ PDF-FORMAT.md               placeholder de 12 lignes
│  └─ superpowers/{specs,plans}/  specs et plans de conception datés (historique)
├─ public/
│  ├─ env.js                      config runtime par défaut (dev)
│  ├─ favicon.svg, logo-horizontal.svg, apple-touch-icon.png, Paws_in_harmony.svg
│  ├─ assets/                     2 PNG logos utilisés par le PDF
│  ├─ brand/zenquality-logo-fr.png
│  ├─ pathology-editor.html       éditeur de constats autonome (1700 lignes, zéro import src/)
│  └─ species/equine/
│     ├─ Horse.svg                SVG principal (viewBox 0 0 2073.4 1629.4)
│     ├─ Horse_head.svg           SVG de détail "head" (viewBox 60 100 500 380)
│     └─ pathologies.json         copie du catalogue, fetchée par pathology-editor.html
├─ src/
│  ├─ main.tsx                    ReactDOM root
│  ├─ app/App.tsx                 BrowserRouter + routes
│  ├─ app/routes/
│  │  ├─ HomeRoute.tsx            nouveau bilan / import PDF
│  │  ├─ NewReportRoute.tsx       formulaire praticien/animal/propriétaire
│  │  ├─ EditorRoute.tsx          éditeur de bilan (canvas + observations + export)
│  │  ├─ SvgEditorRoute.tsx       éditeur SVG anatomique (1858 lignes, vanilla DOM dans useEffect)
│  │  ├─ EditorsRoute.tsx         page de liens vers les deux éditeurs
│  │  └─ NotFoundRoute.tsx
│  ├─ app/providers/ConfigProvider.tsx
│  ├─ config/env.ts               AppConfig (siteName, brandName, footerName, tagline)
│  ├─ anatomy/
│  │  ├─ types.ts                 Bone, BoneCategory, BoneState, SvgConventionError
│  │  ├─ svgConvention.ts         parseSvgBones(), getBoneIdFromEvent(), getAnnotatedElement()
│  │  ├─ svgLoader.ts             loadSvg(publicPath) via fetch + DOMParser
│  │  └─ labels.ts                boneLabel(bone, locale, fallback)
│  ├─ domain/schema/
│  │  ├─ findings.ts              SourceRef, FindingNode (récursif), ZoneFindings, SpeciesFindings
│  │  ├─ observation.ts           Severity, VertebralRegion, Vertebra, LateralSide, ObservationZone, Finding, Observation
│  │  ├─ report.ts                Report (version literal 2), NextAppointment
│  │  ├─ practitioner.ts, animal.ts
│  ├─ domain/species/
│  │  ├─ types.ts                 VertebralFormula, SpeciesManifest, FindingsLoader
│  │  ├─ registry.ts              import.meta.glob('./*/index.ts'), getSpecies(), getAllSpecies(), speciesLabel()
│  │  └─ equine/
│  │     ├─ index.ts              manifeste : mainSvg, details.head, vertebralFormula, findings loader
│  │     ├─ vertebrae.ts          C7 T18 L6 S5 Cd18
│  │     ├─ pathologies.ts        SpeciesFindingsSchema.parse(json) au chargement
│  │     └─ pathologies.json      catalogue source (identique octet pour octet à public/species/equine/pathologies.json)
│  ├─ lib/
│  │  ├─ zoneMatch.ts             normalizeLabel, levenshtein, scorePair, matchZoneFindings
│  │  ├─ spineZones.ts            regionFromLabel, findSpineZoneId, collectSpineVertebrae, syncSpineZones
│  │  ├─ id.ts                    generateId() = crypto.randomUUID()
│  │  ├─ dates.ts, assert.ts
│  ├─ state/
│  │  ├─ reportStore.ts           Zustand, miroir sessionStorage osteo:draft
│  │  ├─ localeStore.ts           osteo:locale
│  │  └─ practitionerCache.ts     osteo:lastPractitioner
│  ├─ components/
│  │  ├─ canvas/AnatomyCanvas.tsx SVG inline, clic délégué, data-state, tooltip
│  │  ├─ canvas/DetailModal.tsx   Dialog + AnatomyCanvas du SVG de détail
│  │  ├─ observation/             ObservationList, ObservationCard, FindingsTreePicker, VertebraPicker, LateralityPicker, SeveritySelector, FreeTextFindingInput
│  │  ├─ report/                  ReportHeader, PractitionerForm, AnimalForm, ConclusionPanel, NextAppointmentPicker
│  │  ├─ brand/                   AppHeader, Brand, Footer, LanguageSwitcher
│  │  └─ ui/                      primitives
│  ├─ pdf/
│  │  ├─ export.ts                exportReportToPdf(), buildZoneLabels()
│  │  ├─ import.ts                importReportFromPdf(), ImportError
│  │  ├─ attachment.ts            attachReportJson(), extractReportJson(), inflateFlate()
│  │  ├─ fonts.ts                 StandardFonts Helvetica / TimesRoman
│  │  └─ render/                  header, footer, observationPage, conclusionPage, svgToPng, text, logo, linkAnnotation, constants
│  ├─ i18n/                       fr.ts, en.ts (dicts plats), useT, pickLocaleLabel
│  └─ styles/                     index.css, tokens.css, svg-editor.css
├─ tests/unit/*.test.ts(x)        30 fichiers, 180 cas `it(` (voir 13-tests.md)
└─ .claude/                       mémoire projet (decisions, learnings, blockers, journal, evals), TODO, audits. Existe, non copiée.

2. Points d'entrée

Entrée Fichier Rôle
/ src/app/routes/HomeRoute.tsx nouveau bilan ou import PDF
/new src/app/routes/NewReportRoute.tsx saisie identité, initReport()
/editor src/app/routes/EditorRoute.tsx éditeur de bilan, redirige vers / si aucun report (EditorRoute.tsx:120-122)
/svg-editor src/app/routes/SvgEditorRoute.tsx éditeur SVG, footer masqué (App.tsx:12)
/editors src/app/routes/EditorsRoute.tsx liens vers /svg-editor et /pathology-editor.html
* NotFoundRoute.tsx 404 SPA
/pathology-editor.html public/pathology-editor.html fichier statique servi tel quel, hors React (FACTUEL : EditorsRoute.tsx:32 utilise un <a href>, pas un <Link>)

FACTUEL : App.tsx:16-22 déclare exactement six routes. Le routage est BrowserRouter ; en production le fallback try_files $uri $uri/ /index.html de docker/nginx.conf:25 sert index.html pour toute route inconnue, et le fichier statique pathology-editor.html est servi avant le fallback parce qu'il existe sur disque (LRN-029).

3. Graphe des imports entre modules clés

Direction : A → B signifie "A importe B". Relevé par grep import sur src/.

app/App.tsx → routes/*, providers/ConfigProvider, components/brand/Footer

routes/EditorRoute.tsx
  → anatomy/svgLoader (loadSvg), anatomy/svgConvention (parseSvgBones), anatomy/labels (boneLabel), anatomy/types
  → domain/species/registry (getSpecies)
  → domain/schema/{observation,report,findings,practitioner,animal} (types)
  → lib/spineZones (regionFromLabel, collectSpineVertebrae, syncSpineZones)
  → state/reportStore, state/localeStore, state/practitionerCache
  → components/canvas/{AnatomyCanvas,DetailModal}
  → components/observation/{ObservationList,VertebraPicker,LateralityPicker}
  → components/report/*, components/ui/{Button,Dialog}
  → pdf/export (exportReportToPdf)
  → i18n/useT

routes/SvgEditorRoute.tsx
  → domain/species/registry (getAllSpecies, speciesLabel)
  → state/localeStore, i18n/index (getDict), i18n/useT
  → components/brand/AppHeader, styles/svg-editor.css
  (n'importe PAS anatomy/svgConvention : il a sa propre lecture des attributs data-anno-*)

routes/HomeRoute.tsx → pdf/import, state/reportStore
routes/NewReportRoute.tsx → state/reportStore, state/practitionerCache, components/report/*

components/observation/ObservationCard.tsx
  → lib/zoneMatch (matchZoneFindings)          ← seul consommateur runtime du matcher
  → anatomy/labels (boneLabel), anatomy/types
  → domain/schema/{observation,findings} (types)
  → FindingsTreePicker, FreeTextFindingInput, SeveritySelector

components/observation/FindingsTreePicker.tsx → domain/schema/{findings,observation} (types), state/localeStore
components/observation/VertebraPicker.tsx    → domain/schema/observation, domain/species/types
components/canvas/AnatomyCanvas.tsx           → anatomy/svgLoader, anatomy/svgConvention, state/localeStore, i18n/pickLocaleLabel
components/canvas/DetailModal.tsx             → AnatomyCanvas, components/ui/Dialog

lib/zoneMatch.ts   → domain/schema/findings (type ZoneFindings)
lib/spineZones.ts  → domain/schema/observation (types), anatomy/types
anatomy/labels.ts  → i18n/pickLocaleLabel, anatomy/types

domain/species/registry.ts → domain/species/types (+ import.meta.glob des manifestes)
domain/species/equine/index.ts → domain/species/types, ./vertebrae ; findings: () => import('./pathologies')
domain/species/equine/pathologies.ts → domain/schema/findings, ./pathologies.json

pdf/export.ts → anatomy/{svgLoader,svgConvention}, domain/species/registry, i18n, render/*, attachment
pdf/render/observationPage.ts → anatomy/{svgLoader,svgConvention}, domain/species/registry, i18n/pickLocaleLabel, render/{svgToPng,text,header,constants}
pdf/import.ts → attachment ; pdf/attachment.ts → domain/schema/report (ReportSchema)

state/reportStore.ts → domain/schema/report (ReportSchema), lib/id, lib/dates

Observations (DEDUIT) :

  • lib/zoneMatch.ts n'a qu'un seul appelant dans l'application : ObservationCard.tsx:134. Le PDF n'utilise pas le matcher : il lit Finding.zoneId directement (observationPage.ts:441).
  • anatomy/svgConvention.ts est appelé à quatre endroits : EditorRoute.tsx:135,146,167, AnatomyCanvas.tsx (clic/tooltip), pdf/export.ts:53, pdf/render/observationPage.ts:220. Le SVG est donc re-téléchargé et re-parsé à chaque export PDF.
  • public/pathology-editor.html n'importe rien de src/ (BDR-020) ; il réimplémente le matcher (pathology-editor.html:850-908, commentaire "ported from src/lib/zoneMatch.ts") et son propre generateId (:912).

4. Build et déploiement

Étape Fait (FACTUEL)
Build pnpm build = tsc --noEmit && vite build (package.json). Vite n'a qu'une entrée, index.html. Tout public/ est copié tel quel dans dist/.
Catalogue src/domain/species/equine/pathologies.json est importé statiquement par pathologies.ts:5 et inclus dans le bundle JS. public/species/equine/pathologies.json est une copie servie en HTTP, utilisée uniquement par pathology-editor.html:790. md5 identique (f3b11822…).
SVG Jamais bundlés : fetchés à l'exécution par loadSvg('/species/equine/Horse.svg') depuis public/.
nginx location /species/ { add_header Cache-Control "no-cache"; } (docker/nginx.conf:19-21) : les SVG et le JSON public sont revalidés à chaque requête. /assets/ immuable un an.
Runtime config entrypoint.sh écrit env.js ; src/config/env.ts lit window.__APP_CONFIG__ puis VITE_APP_* puis défauts. Ne concerne que l'identité de marque.
Conteneur USER nginx, port 8080, aucun backend, aucune base.

DEDUIT : une mise à jour du catalogue exige un rebuild du bundle pour l'application, mais seulement un remplacement de fichier pour l'éditeur de constats. Les deux copies peuvent diverger sans qu'aucun test ne le détecte (voir 10-current-limitations.md).

5. Fichiers nécessaires pour reconstruire une fiche anatomique complète (section 9 du brief)

Le code n'a pas de notion nommée "fiche anatomique" (voir 02-anatomical-sheet.md). La liste ci-dessous est DEDUITE des imports et des fetchs réels.

Indispensables

Fichier Pourquoi
public/species/equine/Horse.svg SVG principal, seule source des zones, points, labels FR/EN, catégories, latéralité, drapeau vertebral-precision, lien vers le détail
public/species/equine/Horse_head.svg SVG de détail head, seule source des 9 zones crâniennes
src/domain/species/equine/pathologies.json catalogue des constats (26 zones), bundlé
src/domain/species/equine/index.ts manifeste : relie mainSvg, details.head, formule vertébrale, loader du catalogue. Sans lui l'espèce n'existe pas (registry.ts:16-19)
src/domain/species/equine/vertebrae.ts formule C/T/L/S/Cd, consommée par VertebraPicker
src/domain/species/equine/pathologies.ts parse Zod du JSON au chargement
src/domain/species/types.ts, src/domain/species/registry.ts contrat du manifeste et découverte automatique
src/domain/schema/findings.ts schéma du catalogue
src/domain/schema/observation.ts, report.ts, practitioner.ts, animal.ts schéma du bilan qui référence les zones
src/anatomy/types.ts, svgConvention.ts, svgLoader.ts lecture du SVG en Map<string, Bone>
src/lib/zoneMatch.ts le seul pont SVG → catalogue
src/lib/spineZones.ts déduction de la région vertébrale depuis le libellé

Optionnels (la fiche fonctionne sans, avec dégradation)

Fichier Rôle
public/species/equine/pathologies.json copie HTTP pour l'éditeur de constats uniquement
src/anatomy/labels.ts, src/i18n/pickLocaleLabel.ts repli FR/EN des labels
src/i18n/fr.ts, en.ts libellés statiques de l'UI et du PDF, pas les noms de zones
docs/ANATOMY-SVG-CONVENTION.md, docs/PATHOLOGIES-FORMAT.md, docs/ADDING-A-SPECIES.md contrats écrits, partiellement désynchronisés du code
scripts/scaffold-species.mjs génère un squelette d'espèce (écrit schema_version: '1.1', scaffold-species.mjs:123, alors que le catalogue cheval est en "2.0")

Purement UI

Fichier Rôle
src/app/routes/SvgEditorRoute.tsx + src/styles/svg-editor.css outil d'annotation ; produit le SVG, ne fait pas partie de la fiche
public/pathology-editor.html outil d'édition du JSON ; produit le catalogue
src/app/routes/EditorRoute.tsx, components/canvas/*, components/observation/*, components/report/*, components/ui/*, components/brand/* consommation de la fiche dans le bilan
src/pdf/** rendu et attachement ; re-lit la fiche à l'export
src/state/*, src/config/env.ts, src/app/providers/ConfigProvider.tsx état et identité
public/assets/*.png, public/brand/*.png, public/Paws_in_harmony.svg, public/logo-horizontal.svg, public/favicon.svg marque

Historiques ou inutilisés

Élément Constat
docs/PDF-FORMAT.md placeholder de 12 lignes, jamais rédigé (FACTUEL)
docs/superpowers/specs/*, docs/superpowers/plans/* documents de conception datés mai 2026 ; utiles pour l'intention, pas pour l'état courant
Attribut data-anno-category-name (18 occurrences dans Horse.svg) écrit et relu uniquement par l'éditeur SVG (SvgEditorRoute.tsx:640,1150) ; ignoré par parseSvgBones (FACTUEL : non lu dans svgConvention.ts:44-89)
BoneState linked / multi supprimés par 9d8267b ; types.ts:43 ne garde que 'current' | 'default', index.css:12 n'a qu'une règle data-state='current'. Le doc ANATOMY-SVG-CONVENTION.md:138-139 les décrit encore (obsolète)
22 PNG logos inutilisés (TOUR CLN-7) supprimés par 9d8267b (23 fichiers public/assets touchés). public/assets/ ne contient plus que les 2 PNG lus par pdf/render/logo.ts (vérifié ls)
logos/ sources de marque + script de génération, non servies
Règles CSS .hide-articulation, .hide-charniere, .hide-cadran-crane, .hide-os-overlay, .hide-spine-zone, .hide-custom (svg-editor.css:523-528) ciblent les noms de catégories des templates (CATEGORY_TEMPLATES, SvgEditorRoute.tsx:276-282). Les catégories réelles des SVG cheval sont articulations, charni-res-vert-brales, cadrans-du-cr-ne, zone-colonne, os. DEDUIT : la case "visibilité" (SvgEditorRoute.tsx:1476) ajoute une classe hide-articulations qu'aucune règle CSS ne cible, donc elle est sans effet sur les SVG du projet
Migration data-bone-* → data-anno-* (SvgEditorRoute.tsx:591-608) compatibilité avec l'ancienne convention (commit 1109e33) ; aucun SVG du dépôt ne porte encore data-bone-*
scaffold-species.mjs:158 bannière "Zoosteo", ancien nom du projet

Points non déterminés

  • HYPOTHESE : l'absence de data-bone-* dans les SVG commités ne prouve pas qu'aucun SVG externe à migrer n'existe chez le praticien ; la migration est conservée par prudence ou par oubli, le code ne le dit pas.
  • La raison de la double copie de pathologies.json est documentée dans la spec de l'éditeur (docs/superpowers/specs/2026-05-22-pathology-editor-design.md:56, "copied or symlinked"). Aucun script ne synchronise les deux copies ; la synchronisation est manuelle (DEDUIT de l'absence de script dans package.json et scripts/).