Files
faunosteo/docs/development/STEP5_MIGRATION_ANALYSIS.md
T

24 KiB
Raw Blame History

Step 5 analysis: the application on the canonical sheet

Status: proposal, awaiting validation (2026-10-10). Nothing implemented. Inputs: IMPLEMENTATION_PLAN.md Step 5, MIGRATION_STRATEGY.md §2 to §4, FRONTEND_ARCHITECTURE.md §3, TEST_STRATEGY.md §2, ANATOMICAL_SHEET_MODEL.md §2 and §6, CHARACTERIZATION_REPORT.md, memory decisions BDR-010/011/013/014/ 015/019/031/034/036/037, and four read-only code analyses (core and store, rendering and interactions, PDF, tests) run on the current apps/app.

Orientations given by the user for this step: keep the historical look and interactions of the markers but draw them from the document; use the curated equine draft as the reference content; show the review statuses in review interfaces only, never as badges on the drawings; render the head view as a crop of the main drawing while keeping independent views possible; check the framing before and after.

1. Facts that drive the design

  1. A Report v2 identifies a zone by boneId = the legacy data-anno-id (point-mpbwtst0), plus detailSourceId (head) for the head view. All 27 legacy ids differ from the canonical annotation ids (hip); the map is legacy-import/legacy-id-map.json. Findings are keyed by catalog zone key + node path, and that key already equals the canonical id (26/26).
  2. Of the 612 legacy finding leaf paths, 170 do not exist in the curated draft: 136 moved because every <zone>-observations category became <zone>-consultation-reasons (CHG-004), 34 leaf ids were renamed or removed (CHG-005, 011, 012, 016, 017). These renames live in curation/changes.json, not in the legacy id map.
  3. The app never draws markers today. They are elements of the SVG files (<g id="osteo-overlays">): each point is a transparent hitbox circle (r 34 joints, 30 junctions, 27 head) plus a visible twin (r 22 / 18 / 15, fill-opacity 0.65 main, 0.5 head, black 1.5 stroke) coloured by category; the five spine zones are magenta polygons (#e100ff, opacity 0.3); the head trigger is a dashed orange polygon at opacity 0.06 with no name. The document kept only the hitbox geometry and categories[].color is null.
  4. The only state drawn is data-state="current" on the zones of the active observation: accent #b85a3f at 0.85 on hitbox and twin, so a selected point shows as a disc of hitbox radius. Side, severity and other observations are not shown. A locale-aware tooltip follows the mouse.
  5. Horse_head.svg is the same drawing as Horse.svg with viewBox="60 100 500 380", which is the draft's head view_box.
  6. Every zone rule lives in EditorRoute.tsx (552 lines): click dispatch, spine, bilateral and plain zone handlers, both picker confirmations, the three bone maps, highlight derivation, disclaimer, export. The store does whole-object replacement only.
  7. Label text drives logic in two places: zoneMatch.ts (fuzzy SVG label to catalog zone, used by ObservationCard) and spineZones.ts (region from label roots, used by the spine sync and the picker's initial tab). The draft renames 23 annotations and 13 zone names, so both would misbehave.
  8. The PDF depends on markers for one thing: the highlight of the selected zone before rasterising (colorizedSvgString). Labels come from the SVG attributes and the catalog, finding text from the snapshots, vertebrae print as raw codes. The attachment is the full Report v2 JSON; import rejects any other version with a typed error.
  9. The practitioner's archive is made of PDFs with v2 attachments produced by the deployed app. Their import must keep working in production.
  10. Tests: 41 files, 278 cases, happy-dom, rasterisation mocked everywhere. Seven char.* files (91 cases) pin the legacy assets: ids, attribute counts, click-chain outcomes in v2 shape, PDF strings, the head viewBox. 66 cases import the registry or read species/equine/* directly.
  11. Two authoring tools read the legacy data-anno-* format: the SVG editor route (1858 lines, vanilla DOM, no test) and pathology-editor.html (1700 lines, no test). Both are declared "not ported" by the frontend architecture; the merged sheet editor replaces them later (Step 17).

2. Target shape

2.1 Report document v3 (packages/domain)

Report v3
├─ version: 3
├─ id, createdAt, date, practitioner, animal, owner      unchanged (snapshots)
├─ sheet: { sheetId, versionId, documentSha256 }         exact sheet the report was built on
├─ observations[]: { id, zones[], findings[], freeTextFindings[], severity?, comment }
│     zone:    { annotationId, viewId, side?, vertebrae?: { region: string, index }[] }
│     finding: { findingZoneId, path[], labelFrSnapshot, labelEnSnapshot,
│                requiresVetReferral?, side?, unresolved?: true }
├─ conclusion, recommendations, nextAppointment?         unchanged
└─ localAnnotations: []                                  reserved (OPEN_QUESTIONS Q6), empty in Step 5
  • annotationId + viewId replace boneId + detailSourceId. The pair is the zone identity everywhere (toggle, bilateral removal, spine sync).
  • vertebrae[].region becomes a free string checked against vertebral_config.regions at runtime, not a closed enum (BDR-031).
  • severity keeps its three values as stable codes mild | moderate | severe; the French and English labels come from i18n. The persisted values stop being accented French words.
  • unresolved: true marks a finding whose (findingZoneId, path) does not exist in the referenced sheet. The snapshots still display it and the PDF still prints it. Nothing is dropped.
  • sheet is required: a report always says which document it was built on. For the bundled draft, sheetId and versionId are the seed's deterministic ids and documentSha256 the hash of draft/document.json.
  • Locale stays out of the report (BDR-014). The plan's "locale of last export" belongs to the PDF attachment envelope of Step 6, not to the report.
  • localAnnotations is present and empty so that Step 14 does not need a version 4 to add report-only points once Q6 is decided.

2.2 v2 → v3 adapter and the migration map

The pipeline of Step 4c already records every rename and removal. It gains one generated file, draft/report-migration-map.json:

{ annotations: { "<legacy data-anno-id>": "<annotation id>" },          from legacy-id-map
  views:       { "head": "head", "": "main" },                           detailSourceId → viewId
  findingPaths: { "<zone>/<legacy path>": "<zone>/<new path>" | null } } from the applier's records

The finding-path map is computed from the legacy baseline and the applier records: a rename of a category or node rewrites the prefix of every path under it; a removed subtree maps to null; a category removed and re-added under another id (sphenoid, CHG-011) maps leaf by leaf when the same leaf id exists at the same relative place under the new category, otherwise null. The file is committed and golden-tested like the other artifacts, and the CHANGELOG gains the counts: expected 442 identical paths, 136 remapped, at most 34 unresolved.

migrateReportV2ToV3(report, map, sheetRef) is a pure function in packages/domain: zones through annotations and views, findings through findingPaths (null → unresolved: true, path kept as is), severity through the code table, sheet filled from sheetRef. It never throws on content: an unknown legacy id is kept verbatim and flagged, because losing a practitioner's zone silently is worse than carrying an unresolved one.

Where v2 documents come from: sessionStorage['osteo:draft'] (migrated on load, then saved back as v3) and the PDF attachments of the archive (migrated at import). Both paths use the same function.

2.3 Sheet provider and bundling

SheetProvider
  getReferenceSheet(): Promise<LoadedSheet>
  LoadedSheet = { ref: { sheetId, versionId, documentSha256 }, document: AnatomicalSheetDocument,
                  assets: Record<svg_asset_id, string /* SVG text */> }

One implementation in Step 5, bundledSheetProvider, importing the generated seed through a Vite alias (@sheets → supabase/seed/anatomical-sheets, server.fs.allow widened to the repository root for dev). No copy of the document into apps/app, no public/ fetch: the golden tests already guarantee that the imported files are the pipeline's output, and the Dockerfile copies the whole repository into the build context. The Supabase implementation comes with Step 13 behind the same interface.

The provider returns the draft, as decided (BDR-037). The import of legacy-import/document.json is not bundled: it is the migration baseline, not a sheet the practitioner works on.

2.4 Separation: model, interaction service, store, UI

packages/domain        canonical sheet (read-only in the app) + Report v3 + adapter
services/sheetIndex.ts  pure lookups over a LoadedSheet: annotationsByView, annotation(id),
                        findingZone(id), regions(), nodeAt(zoneId, path)   (replaces Bone maps,
                        zoneMatch, spineZones)
services/zoneInteraction.ts  pure: decideZoneClick(annotation, observation, hasActive) →
                        open_detail | activate_fallback | open_vertebra_picker |
                        open_laterality_picker | remove_both_sides | toggle
                        + pure reducers: toggleZone, addSides, syncVertebrae (BDR-019 semantics)
state/reportStore.ts    holds Report v3; actions call the reducers; persistence behind
                        ReportPersistence with sessionStoragePersistence (migrates v2 on load)
UI                      EditorRoute wires events to the service and the pickers; AnatomyCanvas
                        and DetailModal render a view; ObservationCard reads sheetIndex

The store keeps activeObservationIndex client-side as today. The route stops holding business rules and shrinks under the 300 lines the plan asks.

2.5 Rendering

renderAnnotationLayer(view, annotations, states, style) is a pure function producing SVG elements for one view, appended after the drawing inside one <svg viewBox=...>:

  • the drawing is the cleaned asset text, parsed once and sanitised (no <script>, no event attributes, LRN-025), its root attributes dropped;
  • the viewBox is the view's view_box when set, else the asset's own; the head view therefore renders the same drawing cropped to 60 100 500 380, which is exactly what Horse_head.svg did;
  • each point annotation becomes the legacy pair: a transparent hitbox (r from the geometry) carrying data-anno-id, data-anno-kind, data-anno-lateral, data-anno-region, data-anno-opens-view, and a visible twin whose radius, opacity and stroke follow a style table keyed by view kind (main: r × 22/34, opacity 0.65; detail: r × 15/27, opacity 0.5; black 1.5 stroke);
  • zone annotations (spine) become one polygon with the legacy magenta style; detail triggers the dashed orange polygon; path geometries a <path>;
  • colours come from categories[].color, filled by a technical changeset with the legacy values (articulations #ff9500, os #a41e65, charnieres-vertebrales #ff0000, cadrans-du-crane #1baa08, zone-colonne #e100ff); the two per-view quirks of the head file (#ff8800 joints, #d507c4 hyoid) are dropped in favour of one colour per category;
  • data-state="current" and the accent rule stay as they are, so the selected look is unchanged;
  • a <title> child "FR / EN" and the mouse tooltip stay (names from the document, locale-aware).

The click delegation (closest('[data-anno-id]')) is unchanged. parseSvgBones and the Bone type disappear: the layer is built from the document, so there is nothing to parse back.

For the visual check asked by the user, the same function serialises the main and head views with no state into draft/review/app-main.svg and app-head.svg through the pipeline, rasterised by the operator with ImageMagick like the 4c overlays. The before images are the current app's two files; the after images are those renders. Framing and marker look are compared side by side before the UI work starts.

2.6 PDF in Step 5 (shim)

observationPage takes the loaded sheet instead of refetching files: zone titles from annotations[].name, finding headers from finding_zones[].name, vertebrae still as codes, finding text from the snapshots (unresolved ones printed as today, nothing special). The highlight is produced by rendering the view through renderAnnotationLayer with data-state="current" on the selected annotations, then rasterising as today. The picture keeps the same drawing, the same accent and the same halo; only the moved points move.

The attachment carries the Report v3 as is. Import accepts v2 (migrated) and v3. This touches pdf/import.ts and pdf/attachment.ts, which CLAUDE.md gates behind an explicit confirmation: decision D3 below. The alternative, converting v3 back to v2 for the attachment, would need a reverse id map and would throw away the unresolved flags; it is not proposed.

3. Replace or refactor

Current code Fate Why
domain/species/** (registry, manifest, vertebrae, pathologies loader, bundled pathologies.json) delete the sheet document carries species, views, assets, regions and the finding tree
lib/zoneMatch.ts delete finding_zone_id is explicit; its only consumer (ObservationCard) reads sheetIndex
lib/spineZones.ts replace by syncVertebrae in the interaction service, keyed by vertebral_region_code region from data, no label roots; BDR-019 semantics kept and tested one-to-one
anatomy/svgConvention.ts, anatomy/types.ts (Bone) delete nothing to parse: the layer is generated
anatomy/svgLoader.ts replace by a sanitising parser of the bundled asset text one place, tested
anatomy/labels.ts keep pickLocaleLabel, drop boneLabel labels are LocalizedText
components/canvas/AnatomyCanvas.tsx, DetailModal.tsx rewrite thin: props = view + layer + states same DOM contract for clicks and CSS
app/routes/EditorRoute.tsx rewrite as wiring (< 300 lines) rules move to the service
state/reportStore.ts split: pure actions, persistence adapter, v3 MIGRATION_STRATEGY §2 move A and B
components/observation/VertebraPicker.tsx adapt: regions and counts from vertebral_config free codes, count_range
components/observation/{ObservationCard,FindingsTreePicker}.tsx adapt: tree from sheetIndex, ids v3 no fuzzy match
pdf/export.ts, pdf/render/observationPage.ts adapt (shim) §2.6
pdf/attachment.ts, pdf/import.ts adapt: v2 migrated, v3 native decision D3
app/routes/SvgEditorRoute.tsx, EditorsRoute.tsx, public/pathology-editor.html, styles/svg-editor.css delete in Step 5 (decision D4) or keep reading public/species/* untouched they edit a format the product no longer uses; the audit docs keep their functional reference for Step 17
public/species/equine/*.svg, pathologies.json keep until D4 is settled, then delete with the tools the app itself stops reading them
docs/ANATOMY-SVG-CONVENTION.md replace by "Annotation rendering contract" (attributes emitted by the layer, states, style table) already out of sync with the code

4. Regression risks and controls

Area Risk Control
Zone selection wrong identity after id change: a click on hip not matching a migrated zone identity = (annotationId, viewId) everywhere; click-chain tests migrated one-to-one with v3 expectations; adapter test on the golden v2 fixtures
Laterality bilateral flag lost (legacy: absence of attribute = unpaired; canonical: explicit) service reads annotation.laterality; test: each of the 10 bilateral annotations opens the side picker, the 18 others do not
Vertebrae region inference gone; Cd range 15–21 vs picker cap 18; picker edits all regions at once syncVertebrae keyed by vertebral_region_code; equivalence test against the legacy syncSpineZones outcomes on the same inputs; picker shows count by default and lets the practitioner extend to count_range.max (decision D6)
Findings 170 legacy paths; snapshots must still print; tree picker must not crash on unresolved migration map golden-tested; adapter test over all 612 legacy leaves; ObservationCard shows unresolved findings from snapshots with a neutral marker, no selection state
PDF highlight picture changes; labels renamed; v2 archive import golden PDFs produced by the current app before any change (full and minimal reports) become fixtures: import them with the new code and compare the migrated document to the expected v3 fixture; page-text assertions updated to the new labels, listed in the CHANGELOG of the step
Draft persistence a v2 draft in sessionStorage silently dropped readPersistedDraft migrates v2, rejects nothing silently (logs in DEV), test with the v2 fixture
Head view framing differs from Horse_head.svg; detail title Détail — head same viewBox by construction; title from views[].name (decision D7); before/after renders compared by the user
Build seed folder outside apps/app Vite alias + fs.allow; Docker build in CI already copies the repository; a build test imports the alias
Performance layer re-rendered on each state change memoised per view; states applied through attributes, not re-creation
Orphan findings removing a zone leaves its findings (BDR-019 wart) kept as is in Step 5, flagged unresolved only when the sheet lacks the path; cleaning is a separate decision (D5)

5. Visible changes versus today

Change Cause Needs validation
10 points at new positions, one new point (carpus) curated draft already validated in 4c (to_confirm), nothing new
23 annotation names and 13 zone names renamed (tooltips, badges, PDF) curated draft already validated in 4c
Findings tree: sphenoid restructured, new nodes, new descriptions, English descriptions curated draft already validated in 4c
Head detail title shows the view name ("Tête") instead of "Détail — head" view names in the document D7
Head joints and hyoid colours aligned on the main view colours one colour per category D1
Vertebra picker can go beyond the usual count up to the documented maximum count_range D6
Editor header mentions the sheet and its status ("brouillon de référence, non validé") user rule on inherited data D2
Disclaimer text with the legal articles curated draft validated in 4c, question 3 still open
/editors, /svg-editor and the pathology editor removed D4 D4

Nothing else changes: layout, colours of the drawing, marker sizes, selection accent, tooltip, pickers, cards, PDF layout.

6. Tests

Before any code change: produce the golden artifacts of the current app and freeze them: report-v2.full.pdf and report-v2.minimal.pdf exported by the deployed version, plus the expected v3 documents after migration.

Migrated one-to-one (same assertion, new shape), with the replacing test named in the step's CHANGELOG:

Characterisation today Replacement
char.clickChain (12) services/zoneInteraction branch tests on the draft annotations; outcomes in v3 shape
char.svgCatalogLink, anatomy.horse sheetIndex tests: 28 annotations, 27 link a zone, one trigger opens head, 10 bilateral, 5 regions
lib.spineZones (11) syncVertebrae equivalence table (same inputs, same outputs, codes instead of labels)
lib.zoneMatch (23) deleted with the module; the importer kept the 26/26 proof in packages/anatomy
char.pdfFull same report through the shim: drawn strings updated to the document labels; attachment v3; v2 golden PDF imported and deep-equal to the expected v3
state.reportStore*, state.draftMirror unchanged semantics on v3; plus v2 draft migration on load
components.VertebraPicker regions from vertebral_config, count_range extension
char.catalog, char.pathologyEditor deleted with the legacy copy and the editor (D4), their invariants live in packages/anatomy golden tests

New: adapter over all 612 legacy leaves (counts pinned), layer renderer contract (attributes, radii, colours per category, state attribute), sanitiser, bundled provider (hash equals the seed's), PDF highlight rendering now unmocked on the layer function (the rasteriser stays mocked).

Visual check: draft/review/app-main.svg and app-head.svg rendered with ImageMagick and compared with screenshots of the current app, before the UI work starts and again at the end of the step.

7. Migration sequence

Each increment lands green (typecheck, lint, tests, build) on one feature branch, in this order:

  1. Freeze: golden v2 PDFs and expected v3 documents; CHARACTERIZATION_REPORT refreshed (41 files, 278 cases).
  2. Pipeline: report-migration-map.json, app-main.svg / app-head.svg, category colours changeset; golden tests.
  3. packages/domain: Report v3, adapter, tests on fixtures and on the 612 leaves.
  4. App foundation: sheet provider, sheetIndex, layer renderer and sanitiser, AnatomyCanvas and DetailModal on views. Legacy flows still run on the registry until step 6.
  5. Interaction service and store split, persistence adapter with v2 migration, pickers and cards on sheetIndex, route rewired.
  6. PDF shim and attachment v3, import of v2 (gate D3).
  7. Delete the legacy modules and tests, apply D4, replace the SVG convention doc, update CLAUDE.md, CHANGELOG, plan note, memory.
  8. Manual validation FR and EN of the full flow, visual before/after, gates (verifier, security).

Sizing: the largest increments are 4 and 5. The plan's "largest refactor of the app core" holds, but every increment is reversible on its own.

8. Decisions to validate

  • D1. Marker colours. One colour per category stored in the document (legacy main-view values); the head file's two quirks disappear. Radii, opacities and strokes stay application style.
  • D2. Review status in the app. Not shown per node in the practitioner's editor, no badge on drawings. The editor header shows the sheet name and status line "Brouillon de référence, non validé médicalement". Review interfaces (REVIEW-REPORT today, the editor of Step 17 later) carry the three statuses explicitly.
  • D3. Attachment v3 and v2 import. Step 5 edits pdf/attachment.ts and pdf/import.ts: v3 written, v2 read through the adapter, v1 still refused. Explicit confirmation requested here per CLAUDE.md.
  • D4. Legacy authoring tools. Recommended: delete /editors, /svg-editor, pathology-editor.html and the public/species copies in Step 5; the audit documents keep the functional reference for the merged editor (Step 17). Alternative: keep them untouched, reading public/species.
  • D5. Orphan findings. Keep the current behaviour (findings survive zone removal), add nothing in Step 5. Cleaning on zone removal would be a behaviour change to decide separately.
  • D6. Vertebra picker and ranges. Show count columns by default with a control to extend up to count_range.max (Cd 21, T 19); below min is not offered. Without this control the range stays data only.
  • D7. Detail view title. Use the view's localized name ("Tête" / "Head") instead of "Détail — head".
  • D8. Severity codes. Persist mild | moderate | severe, labels through i18n; the adapter maps the French values.

9. Left to later steps

  • Q6 (report-only points): localAnnotations reserved, empty.
  • Locale of the last export: attachment envelope of Step 6.
  • Sheet snapshot in the attachment, branding object: Step 6.
  • Supabase SheetProvider, Storage-served asset: Step 13.
  • Merged sheet editor replacing the deleted tools: Step 17.