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.
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.tssrc/state/reportStore.ts,src/state/practitionerCache.tssrc/app/routes/NewReportRoute.tsx,EditorRoute.tsx,HomeRoute.tsxsrc/components/observation/ObservationCard.tsx,FindingsTreePicker.tsxsrc/anatomy/labels.ts,src/i18n/pickLocaleLabel.tssrc/pdf/export.ts,import.ts,attachment.ts,fonts.tssrc/pdf/render/observationPage.ts,conclusionPage.ts,header.ts,footer.ts,logo.ts,linkAnnotation.ts,svgToPng.ts,text.ts,constants.tstests/unit/pdf.*.test.ts,state.*.test.ts,schema.*.test.tsdocs/PDF-FORMAT.md,docs/PATHOLOGIES-FORMAT.md:328-351.claude/memory/decisions.mdBDR-003, BDR-010, BDR-011, BDR-014, BDR-015 ;learnings.mdLRN-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). initReportfixeversion: 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 dansparseAttachment(B.2).- Miroir :
useReportStore.subscribeécritJSON.stringify(report)danssessionStorage['osteo:draft']à chaque changement, ou supprime la clé sireportestnull(l.159-167). - Restauration :
report: readPersistedDraft()à la création du store (l.56), avecReportSchema.safeParse(l.47) ; un brouillon invalide est ignoré. Le brouillon est par onglet (sessionStorage). updateObservationremplace l'observation entière ; toute la logique de zones vit dansEditorRoute(onZoneClick, l.290-320 : détail → repli d'observation active → colonne → bilatéral → bascule simple). Détail des branches dans07-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 :
- Métadonnées : titre
dict['pdf.title.suffix.bilan'] + animal.name("Bilan ostéo — "), auteurpractitioner.name, sujetpdf.subject, dates (l.97-101). - 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, testpdf.roundtrip.test.ts:65-78). buildZoneLabels(report)(l.38-69) : re-fetch et re-parse despecies.mainSvget de chaquespecies.details[*]vialoadSvg+parseSvgBones, construitMap<data-anno-id, { fr, en }>. Chaque source est protégée par son propretry/catch(LRN-015).loadSpeciesFindings(speciesId)(l.76-88) : recharge le catalogue pour nommer les zones des constats.- 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.svgrasterisé parrasterizeSvg(l.130-134). Chaque échec est seulement loggé. - Une page A4 par observation (
addObservationPage,observationPage.ts:617-651) :buildObservationImages(l.361-395) : vue générale si au moins une zone sansdetailSourceId(l.367), puis une vue pardetailSourceIddistinct présent dans le manifeste (l.376-384). LibellésVUE GÉNÉRALEetVUE DÉTAIL — HEAD(fr.ts:169-170).colorizedSvgString(l.214-255) : re-fetch du SVG,parseSvgBones, zones sélectionnées remplies en#b85a3fopacité 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ésdisplay: none(l.243), puis suppression de tous les attributsdata-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 duviewBox(repli0 0 1000 600), rendu parImage+canvas, fond blanc, PNG.- Grille d'images 1 ou 2 colonnes, puis sections texte :
ZONES(libellés +(C3, C4)+(Gauche),describeObservationZonesl.398-417), un blocCONSTATS — <ZONE>par couplezoneId:side(buildFindingsSectionsl.420-463),CONSTATS LIBRES,SÉVÉRITÉ,COMMENTAIREsi présents (l.466-493).
- Page de conclusion (
conclusionPage.ts:25-101) : conclusion, recommandations, prochain rendez-vous (date formatée ou texte). - En-tête sur chaque page (
header.ts) : praticien (nom, cabinet, contact, SIRET), logo cliquable vershttps://faunosteo.com(l.63), animal (nom, race, âge), propriétaire, date. - Pied de page sur chaque page (
footer.ts) : logo Faunosteo + lienhttps://faunosteo.com(l.53), "Propulsé par" + logo ZenQuality ou texte de replizenquality.fr+ lienhttps://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 replizenquality.frquand le logo manque. La règleCLAUDE.md:266("No raw URLs in PDF output") est respectée au sens du texte visible, DEDUIT. 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 estJSON.stringify(report, null, 2), leReporttel quel, sans champ ajouté.pdfDoc.save(). Côté UI, téléchargement sousbilan-<animal.name>-<date>.pdf(EditorRoute.tsx:331).
B.2 Import (importReportFromPdf, src/pdf/import.ts:25-40)
FACTUEL :
PDFDocument.load(bytes, { ignoreEncryption: true }); échec →ImportError('invalid_pdf').extractReportJson(attachment.ts:30-42) : sigetAttachmentsexiste, prend la pièce dont le nom commence parosteo-reportet finit par.json, sinon la première (l.35). Sinon, replitraverseForJsonAttachment(l.107-132) : parcours des objets indirects, retient le premier fluxEmbeddedFileou de sous-typeapplication/json(application#2Fjson), gonfle leFlateDecodeviaDecompressionStreamavec un plafond de 16 Mio (l.68, l.82).parseAttachment(l.44-57) :versionnumérique différente de 2 →IncompatibleReportVersionError(foundVersion)→ImportError('incompatible_version', n)(BDR-011, BDR-015) ; sinonReportSchema.parsestrict. Toute autre erreur →ImportError('no_attachment').HomeRoute.tsx:25-27:hydrateReport(report)puisnavigate('/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 (
boneIdseul 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_versionou é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
indexstocké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(voir06-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]dansextractReportJson(attachment.ts:35) peut lire une pièce jointe étrangère si un PDF tiers en contient une ;ReportSchema.parsela rejettera, mais avec le messageno_attachmentplutôt qu'un message dédié. Non testé. - Non vérifié : le comportement de
getAttachmentsselon 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 (seulversiondans le JSON l'est).