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.
190 lines
17 KiB
Markdown
190 lines
17 KiB
Markdown
# 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'|'L'|'S'|'Cd', index ≥ 1 }]` | `VertebraPicker` + `syncSpineZones` |
|
|
| `side?` | `'left' | 'right'` | `LateralityPicker` |
|
|
|
|
`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 — <ZONE>" 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 — <nom>"), 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).
|