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

17 KiB

08. Bilan, PDF et réimport

Périmètre : partie A, ce que le bilan (Report) enregistre et ce qu'il ne garde pas ; partie B, le cycle bilan → PDF → JSON embarqué → import → restauration, avec ce qui dépend encore de fichiers externes. Le lien zone ↔ catalogue est dans 06-svg-findings-link.md, les cas particuliers du clic dans 07-special-cases.md.

Sources lues

  • src/domain/schema/report.ts, observation.ts, animal.ts, practitioner.ts
  • src/state/reportStore.ts, src/state/practitionerCache.ts
  • src/app/routes/NewReportRoute.tsx, EditorRoute.tsx, HomeRoute.tsx
  • src/components/observation/ObservationCard.tsx, FindingsTreePicker.tsx
  • src/anatomy/labels.ts, src/i18n/pickLocaleLabel.ts
  • src/pdf/export.ts, import.ts, attachment.ts, fonts.ts
  • src/pdf/render/observationPage.ts, conclusionPage.ts, header.ts, footer.ts, logo.ts, linkAnnotation.ts, svgToPng.ts, text.ts, constants.ts
  • tests/unit/pdf.*.test.ts, state.*.test.ts, schema.*.test.ts
  • docs/PDF-FORMAT.md, docs/PATHOLOGIES-FORMAT.md:328-351
  • .claude/memory/decisions.md BDR-003, BDR-010, BDR-011, BDR-014, BDR-015 ; learnings.md LRN-006, LRN-021

Partie A : le bilan

A.1 Schémas (FACTUEL)

Report (src/domain/schema/report.ts:13-31) :

Champ Type Obligatoire Origine
version littéral 2 oui initReport (reportStore.ts:63)
id string oui generateId() (uuid, lib/id.ts)
createdAt string ISO oui nowIso()
date string ISO date oui formulaire /new
practitioner { name, cabinet?, contact?, siret? } oui formulaire, cache osteo:lastPractitioner
animal { speciesId, name, breed?, age? } oui formulaire, speciesId par défaut 'equine' (NewReportRoute.tsx:20)
owner { name } oui formulaire
observations Observation[] oui éditeur
conclusion, recommendations string oui (vide accepté) ConclusionPanel
nextAppointment { kind:'date', date } ou { kind:'period', text } non NextAppointmentPicker

Observation (observation.ts:51-59) : id (uuid), zones: ObservationZone[], findings: Finding[], freeTextFindings: string[], severity? (enum FR 'légère' | 'modérée' | 'sévère', observation.ts:3), comment: string.

ObservationZone (observation.ts:21-30) :

Champ Contenu Posé par
boneId data-anno-id du SVG onZoneClick
detailSourceId? id du détail ('head') si clic dans la modale DetailModal → onZoneClick(id, detailId)
vertebrae? `[{ region: 'C' 'T'
side? `'left' 'right'`

Finding (observation.ts:40-47) :

Champ Contenu Posé par
zoneId clé du catalogue (hip) FindingsTreePicker.toggleLeaf (:147-155)
path ids des nœuds depuis categories, ≥ 1 idem
labelFrSnapshot, labelEnSnapshot copie de name_fr / name_en de la feuille idem (BDR-010)
requiresVetReferral? true si la feuille le porte idem
side? côté du picker idem

A.2 Ce qui est enregistré, ce qui ne l'est pas

Donnée Enregistrée dans le bilan Résolue à l'affichage depuis Preuve
Identifiant de zone SVG oui, ObservationZone.boneId observation.ts:23
Libellé de zone (FR/EN) non SVG courant : boneLabel(bones.get(z.boneId), locale, z.boneId) dans la carte (ObservationCard.tsx:52), buildZoneLabels à l'export (pdf/export.ts:38-69), repli sur le boneId brut anatomy/labels.ts:17-18
Catégorie SVG non jamais réutilisée après le clic aucune trace dans le schéma
special, lateral du SVG non SVG courant (badge "Vertèbres…" affiché si bone.special === 'vertebral-precision', ObservationCard.tsx:253-254)
Constat (feuille) oui : zoneId + path + snapshots FR/EN + vet observation.ts:40-47
Nom de la zone catalogue non catalogue courant : findingsTree.zones[zoneId].name_*, sinon zoneId brut observationPage.ts:441-446
Latéralité oui, side sur la zone et sur chaque constat observation.ts:29,46
Vertèbres oui, vertebrae sur la zone observation.ts:27
Version du bilan oui, version: 2 report.ts:18
Version du catalogue (schema_version) non absent du schéma
Identifiant / version des SVG non ; seul animal.speciesId relie au manifeste manifeste courant getSpecies(speciesId) EditorRoute.tsx:128-131
Chemins des SVG non manifeste courant species/equine/index.ts:8-11
Formule vertébrale non manifeste courant VertebraPicker formula={species.vertebralFormula}
Locale non (BDR-014) store osteo:locale pdf/export.ts:94
Correspondance boneId ↔ zoneId non recalculée par libellé (voir 06-svg-findings-link.md §6)

A.3 Store et brouillon

FACTUEL, src/state/reportStore.ts :

  • Actions : initReport, hydrateReport, addObservation, removeObservation, moveObservationUp/Down, updateObservation, setActiveObservation, setPractitioner, setAnimal, setOwner, setConclusion, setRecommendations, setNextAppointment, reset (l.12-26).
  • initReport fixe version: 2, id, createdAt, et crée une première observation vide si la liste est vide (l.59-72).
  • hydrateReport(report) remplace l'état sans revalider (l.74) ; la validation a eu lieu dans parseAttachment (B.2).
  • Miroir : useReportStore.subscribe écrit JSON.stringify(report) dans sessionStorage['osteo:draft'] à chaque changement, ou supprime la clé si report est null (l.159-167).
  • Restauration : report: readPersistedDraft() à la création du store (l.56), avec ReportSchema.safeParse (l.47) ; un brouillon invalide est ignoré. Le brouillon est par onglet (sessionStorage).
  • updateObservation remplace l'observation entière ; toute la logique de zones vit dans EditorRoute (onZoneClick, l.290-320 : détail → repli d'observation active → colonne → bilatéral → bascule simple). Détail des branches dans 07-special-cases.md.

A.4 Ce qui garde le PDF lisible après modification du catalogue

DEDUIT du code ci-dessus :

Modification Effet sur un bilan existant
Renommer une feuille du catalogue aucun sur le texte : les snapshots FR/EN sont imprimés (observationPage.ts:453)
Supprimer une feuille le constat reste imprimé grâce au snapshot ; dans l'éditeur, la case n'existe plus, le constat reste dans findings mais ne peut plus être décoché depuis le picker (DEDUIT : isLeafSelected ne liste que les feuilles présentes)
Renommer une zone catalogue (name_fr/name_en) le PDF imprime le nouveau nom (lu dans le catalogue courant) ; si le SVG n'est pas renommé en même temps, le matching casse et le picker disparaît
Renommer la clé d'une zone (zoneId) le PDF imprime la clé brute (observationPage.ts:446) et l'éditeur ne retrouve plus le picker associé aux constats existants
Changer un data-anno-id dans le SVG badge et PDF affichent l'id brut (point-mpbwtst0) ; surbrillance perdue ; picker perdu
Changer un libellé SVG surbrillance et badge suivent le nouveau libellé ; picker perdu si le catalogue ne suit pas
Supprimer un fichier SVG de détail buildZoneLabels ignore l'échec (export.ts:62-64) ; les zones de ce détail retombent sur l'id brut ; buildObservationImages saute la vue (observationPage.ts:378)

Le champ path n'est jamais relu pour afficher (FACTUEL : seules labelFrSnapshot / labelEnSnapshot sont imprimées ; docs/PATHOLOGIES-FORMAT.md:345-346 le confirme). Il sert au picker pour cocher/décocher (samePath, pathStartsWith).

Indispensable aujourd'hui pour un PDF lisible : les snapshots de feuille (texte des constats) et, pour les en-têtes "CONSTATS — " et "ZONES", la présence du catalogue courant et des SVG courants avec les mêmes zoneId, data-anno-id et libellés.

Partie B : PDF et réimport

B.1 Export (exportReportToPdf, src/pdf/export.ts:90-169)

FACTUEL, dans l'ordre :

  1. Métadonnées : titre dict['pdf.title.suffix.bilan'] + animal.name ("Bilan ostéo — "), auteur practitioner.name, sujet pdf.subject, dates (l.97-101).
  2. Polices : StandardFonts.Helvetica, HelveticaBold, TimesRoman (fonts.ts:9-16), encodage WinAnsi. Conséquence : tout glyphe hors Latin-1 plante ; le marqueur vétérinaire est (!) et non ⚠ (observationPage.ts:454, LRN-021, test pdf.roundtrip.test.ts:65-78).
  3. buildZoneLabels(report) (l.38-69) : re-fetch et re-parse de species.mainSvg et de chaque species.details[*] via loadSvg + parseSvgBones, construit Map<data-anno-id, { fr, en }>. Chaque source est protégée par son propre try/catch (LRN-015).
  4. loadSpeciesFindings(speciesId) (l.76-88) : recharge le catalogue pour nommer les zones des constats.
  5. Logos : trois PNG fetchés depuis /assets/faunosteo_logo_horizontal-512.png, /assets/faunosteo-horizontal-com-512.png, /brand/zenquality-logo-fr.png (logo.ts:1-3) et /Paws_in_harmony.svg rasterisé par rasterizeSvg (l.130-134). Chaque échec est seulement loggé.
  6. Une page A4 par observation (addObservationPage, observationPage.ts:617-651) :
    • buildObservationImages (l.361-395) : vue générale si au moins une zone sans detailSourceId (l.367), puis une vue par detailSourceId distinct présent dans le manifeste (l.376-384). Libellés VUE GÉNÉRALE et VUE DÉTAIL — HEAD (fr.ts:169-170).
    • colorizedSvgString (l.214-255) : re-fetch du SVG, parseSvgBones, zones sélectionnées remplies en #b85a3f opacité 0.85 (l.237-238), filtre halo gaussien ajouté sur la vue générale seulement (l.230-231), tous les autres overlays annotés masqués display: none (l.243), puis suppression de tous les attributs data-anno-* avant sérialisation (l.248-252, LRN-006). Le dessin anatomique de fond est conservé.
    • rasterizeSvg (svgToPng.ts:117-121) : largeur fixe 1200 px, hauteur selon le ratio du viewBox (repli 0 0 1000 600), rendu par Image + canvas, fond blanc, PNG.
    • Grille d'images 1 ou 2 colonnes, puis sections texte : ZONES (libellés + (C3, C4) + (Gauche), describeObservationZones l.398-417), un bloc CONSTATS — <ZONE> par couple zoneId:side (buildFindingsSections l.420-463), CONSTATS LIBRES, SÉVÉRITÉ, COMMENTAIRE si présents (l.466-493).
  7. Page de conclusion (conclusionPage.ts:25-101) : conclusion, recommandations, prochain rendez-vous (date formatée ou texte).
  8. En-tête sur chaque page (header.ts) : praticien (nom, cabinet, contact, SIRET), logo cliquable vers https://faunosteo.com (l.63), animal (nom, race, âge), propriétaire, date.
  9. Pied de page sur chaque page (footer.ts) : logo Faunosteo + lien https://faunosteo.com (l.53), "Propulsé par" + logo ZenQuality ou texte de repli zenquality.fr + lien https://zenquality.fr (l.61, l.89, l.104), "En partenariat avec" + logo Paws in Harmony ou texte de repli @paws.iin.harmony + lien Instagram (l.110-160), numéro de page. Les URL complètes sont des annotations de lien (addLinkAnnotation, linkAnnotation.ts), pas du texte imprimé ; le seul texte proche d'une URL est le repli zenquality.fr quand le logo manque. La règle CLAUDE.md:266 ("No raw URLs in PDF output") est respectée au sens du texte visible, DEDUIT.
  10. attachReportJson(pdfDoc, report) (attachment.ts:19-28) : pdfDoc.attach(bytes, 'osteo-report.json', { mimeType: 'application/json', description: 'Faunosteo state v2', afRelationship: AFRelationship.Data }). Le contenu est JSON.stringify(report, null, 2), le Report tel quel, sans champ ajouté.
  11. pdfDoc.save(). Côté UI, téléchargement sous bilan-<animal.name>-<date>.pdf (EditorRoute.tsx:331).

B.2 Import (importReportFromPdf, src/pdf/import.ts:25-40)

FACTUEL :

  1. PDFDocument.load(bytes, { ignoreEncryption: true }) ; échec → ImportError('invalid_pdf').
  2. extractReportJson (attachment.ts:30-42) : si getAttachments existe, prend la pièce dont le nom commence par osteo-report et finit par .json, sinon la première (l.35). Sinon, repli traverseForJsonAttachment (l.107-132) : parcours des objets indirects, retient le premier flux EmbeddedFile ou de sous-type application/json (application#2Fjson), gonfle le FlateDecode via DecompressionStream avec un plafond de 16 Mio (l.68, l.82).
  3. parseAttachment (l.44-57) : version numérique différente de 2 → IncompatibleReportVersionError(foundVersion) → ImportError('incompatible_version', n) (BDR-011, BDR-015) ; sinon ReportSchema.parse strict. Toute autre erreur → ImportError('no_attachment').
  4. HomeRoute.tsx:25-27 : hydrateReport(report) puis navigate('/editor'). Messages utilisateur résolus par i18n (home.import.error_*).

Règle de garde : CLAUDE.md:322 demande de poser la question avant tout changement de importReportFromPdf ou extractReportJson.

B.3 Réponses aux questions du brief

Données embarquées dans le PDF : le Report complet, et rien d'autre. FACTUEL : ni SVG, ni catalogue, ni libellés de zones, ni locale (BDR-014), ni schema_version du catalogue, ni images (les PNG rendus sont dans les pages, pas dans la pièce jointe), ni identifiant de version de l'application.

Données qui viennent encore de la configuration courante à la réouverture (FACTUEL, EditorRoute.tsx:128-153 et pdf/export.ts) :

Besoin Source courante Clé de jointure
Manifeste espèce getSpecies(report.animal.speciesId) speciesId
SVG principal et détails (affichage, surbrillance, libellés, raster PDF) species.mainSvg, species.details boneId ↔ data-anno-id, detailSourceId ↔ clé de details
Catalogue (pickers, nom de zone dans le PDF) species.findings() Finding.zoneId ↔ clé de zones ; libellés SVG ↔ name_fr/name_en pour les pickers
Formule vertébrale species.vertebralFormula aucune (réapplication aveugle)
Dictionnaire i18n, locale getDict(locale), store aucune
Logos /assets, /brand, /Paws_in_harmony.svg aucune

Ce qui permet à un ancien PDF de fonctionner aujourd'hui (DEDUIT) : version === 2, un JSON conforme à ReportSchema, un speciesId encore enregistré, des data-anno-id encore présents dans les SVG servis, des libellés SVG encore égaux aux name_* du catalogue, et des zoneId encore présents dans zones. Si une seule de ces conditions tombe, l'import réussit quand même (Zod ne vérifie que la forme) mais l'affichage dégrade : id bruts, pickers absents, constats non éditables, images sans surbrillance.

Ce qui dépend de fichiers externes au PDF : tout ce qui est listé dans le tableau ci-dessus, servi depuis public/ à des chemins codés dans le manifeste et dans logo.ts.

Ce qui manque dans la pièce jointe pour qu'un bilan reste autonome si sa fiche anatomique est supprimée ou archivée (liste factuelle, sans conception) :

  • les libellés FR/EN de chaque zone sélectionnée (boneId seul est opaque) ;
  • le nom FR/EN de chaque zone catalogue référencée par Finding.zoneId ;
  • un identifiant et une version de la fiche anatomique (SVG principal, détails) et du catalogue (schema_version ou équivalent) ;
  • la géométrie ou une image des vues anatomiques avec les zones mises en évidence (aujourd'hui recalculées depuis les SVG à chaque export) ;
  • la formule vertébrale utilisée (les index stockés n'ont de sens que par rapport à elle) ;
  • la catégorie et les hints SVG (special, lateral) si le futur produit veut les réafficher sans le SVG ;
  • les chemins ou le contenu des fichiers SVG ;
  • la correspondance explicite boneId ↔ zoneId (voir 06-svg-findings-link.md §6).

B.4 Couverture de test

FACTUEL :

Test Ce qu'il couvre Limite
pdf.roundtrip.test.ts export FR/EN puis import, rejet d'un PDF étranger, rejet v1 avec foundVersion, encodage WinAnsi du marqueur (!) observations: [] partout (l.18, l.91) : aucune zone, aucun constat, aucune image dans la boucle ; rasterizeSvg est mocké (l.8)
pdf.attachment.test.ts attachReportJson + extractReportJson sur un PDFDocument nu, absence de pièce jointe idem, observations: []
pdf.attachment.inflate.test.ts plafond de décompression 16 Mio
pdf.zoneLabels.test.ts buildZoneLabels sur les vrais SVG, échec d'un détail, espèce inconnue ne teste pas l'export complet
pdf.svgToPng.test.ts rasterizeSvg et repli toDataURL
state.draftMirror.test.ts, state.reportStore.restore.test.ts miroir et restauration osteo:draft

Aucun test n'exporte puis réimporte un bilan avec zones, vertèbres, côtés, détails et constats. Aucun test ne vérifie le rendu texte des sections ZONES / CONSTATS (voir 13-tests.md).

Points non déterminés

  • HYPOTHESE : le repli ?? list[0] dans extractReportJson (attachment.ts:35) peut lire une pièce jointe étrangère si un PDF tiers en contient une ; ReportSchema.parse la rejettera, mais avec le message no_attachment plutôt qu'un message dédié. Non testé.
  • Non vérifié : le comportement de getAttachments selon la version de pdf-lib installée (1.17.1) ; le code est écrit pour fonctionner avec ou sans cette API.
  • HYPOTHESE : la description 'Faunosteo state v2' est lue par aucun code ; elle n'est pas un discriminant de version (seul version dans le JSON l'est).