Merge chore/step-05-migration-analysis into develop
ci / check (push) Canceled after 0s
ci / docker (push) Canceled after 0s
ci / supabase (push) Canceled after 0s

This commit is contained in:
bchanot committed 2026-10-10 11:04:23 +02:00
commit 199e328298
4 files changed
+386

No files matched your search

+1
View File
@@ -189,3 +189,4 @@ Step 4 validated + finished into develop. User decisions on the 7 open points
- 2026-10-10 Step 4c on feature/step-04c-equine-curation: Docker `faunosteo_` convention (BDR-035); schema v2 (references, review_status, count_range; migration 20261010100000, pgTAP 008); curation pipeline (executor) + review overlays; 4 research agents (skull, axial, limbs, osteo/legal) → 44 changes / 679 ops / 48 refs authored from scratch python modules; draft 811 nodes, 28 annotations, 0 integrity errors; 9 points moved, carpus added, 9 questions for the osteopath. Root check green, real stack pgTAP + types clean, docker build OK. BDR-036, LRN-042. Gates next; stop for user validation; no publication.
- Gates 4c: verifier ×3 (4→2→1 écarts, last 3 doc lines fixed by hand at cap), executor closed the applier rule + typed tests; security PASS (LOW url scheme → SQL rule `reference.url.scheme`). Real stack 267/267, Storage e2e OK. EVAL-010. Awaiting user validation; `.env.example` COMPOSE_PROJECT_NAME left to the user (file denied).
- Step 4c VALIDATED by user 2026-10-10 → tracking: head view check documented (spec §6), BLK-008 migration limit, BDR-037, DEPLOY.md `.env.example` note. Finished into develop. Next: Step 5 (app on the canonical sheet), design points flagged before any UI work.
- Step 5 preparation (2026-10-10): 4 analyzer agents (core/store, rendering, PDF, tests) + plan/spec reading → docs/development/STEP5_MIGRATION_ANALYSIS.md on chore/step-05-migration-analysis. Key facts: all 27 legacy data-anno-ids differ from canonical ids; 170/612 legacy finding paths moved/removed by curation → generated report-migration-map; markers never drawn by the app (in the SVG); PDF depends on markers only for the highlight; 66 tests import the registry. 8 decisions D1–D8 await the user. No implementation.
+9
View File
@@ -86,6 +86,15 @@ feat/findings-tree-v2 merged (FindingsTreePicker tracked in HEAD); all work belo
- [x] 4c.5 reports: REVIEW-REPORT.md for the osteopath (10 sections, questions ranked), CHANGELOG table, before/after review SVGs (draft/review/, PNG renders by operator), quantitative before/after.
- [ ] 4c follow-up (open, not blocking Step 5): 11 questions for the osteopath (draft/REVIEW-REPORT.md §10) → next changeset; legal scope text to re-read on consolidated Légifrance articles before publication; BLK-008 data migration v1→v2 before real data; user action `.env.example` COMPOSE_PROJECT_NAME=faunosteo (DEPLOY.md)
- [x] 4c.6 verify (root check 68+21+100+278, PGlite + real stack 267/267, types, docker build, Storage e2e; verifier ×3 → fixes, security PASS; EVAL-010): pnpm check, PGlite + real stack pgTAP, types, docker build, golden tests; gates verifier + security; docs (spec §6/§7, SUPABASE.md, CLAUDE.md, plan Step 4c, CHANGELOG); memory (BDR/LRN/EVAL/journal). Stop for user validation.
- [ ] Step 5 — application on the canonical sheet (analysis 2026-10-10, branch chore/step-05-migration-analysis, AWAITING user validation of docs/development/STEP5_MIGRATION_ANALYSIS.md and decisions D1–D8; no implementation before)
- [ ] 5.0 freeze: golden v2 PDFs + expected v3 docs; CHARACTERIZATION_REPORT refreshed
- [ ] 5.1 pipeline: report-migration-map.json (annotations, views, findingPaths 442/136/≤34), app-main.svg + app-head.svg review renders, category colours changeset (D1)
- [ ] 5.2 packages/domain: Report v3 (annotationId+viewId, free region codes, severity codes D8, sheet ref, unresolved findings, localAnnotations []), migrateReportV2ToV3, tests on fixtures + 612 leaves
- [ ] 5.3 app foundation: bundledSheetProvider (Vite alias @sheets), sheetIndex, sanitiser, renderAnnotationLayer (legacy look), AnatomyCanvas/DetailModal on views (head = crop)
- [ ] 5.4 zoneInteraction service + reducers, store split + sessionStoragePersistence (v2 migration on load), pickers/cards on sheetIndex (D6 ranges, D7 title), EditorRoute < 300 lines
- [ ] 5.5 PDF shim + attachment v3 + v2 import (gate D3)
- [ ] 5.6 delete legacy (registry, species/*, zoneMatch, spineZones, svgConvention, D4 tools), SVG convention doc replaced, CLAUDE.md map, CHANGELOG, plan note, memory
- [ ] 5.7 manual FR/EN flow, visual before/after, gates verifier + security
---
+6
View File
@@ -155,6 +155,12 @@ Risks: subtle divergences between parser and importer on the detail trigger (no
CHANGELOG, REVIEW-REPORT, before/after review drawings), seed layout legacy-import/ + curation/ +
draft/ (the `v1/` folder is gone), research-backed audit of the equine sheet (44 changes, 48
references, levels A/B/C, nothing published), Docker naming convention (BDR-035).
Step 5 preparation 2026-10-10: docs/development/STEP5_MIGRATION_ANALYSIS.md (Report v3 shape,
v2→v3 adapter fed by a generated report-migration-map, bundled SheetProvider, annotation layer
renderer reproducing the legacy markers, interaction service + store split, PDF shim with
attachment v3, replace-or-refactor table, risks, tests, 8 decisions D1–D8). Awaiting validation;
the orientations below supersede "annotation_finding_map" (inline finding_zone_id, BDR-031) and
"locale of last export" (locale stays out of the report, BDR-014).
```
```text
@@ -0,0 +1,370 @@
# 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`)
```text
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`:
```text
{ 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
```text
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
```text
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.