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
ci / check (push) Canceled after 0s
ci / docker (push) Canceled after 0s
ci / supabase (push) Canceled after 0s
This commit is contained in:
commit
199e328298
4 files changed
+386
No files matched your search
@@ -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.
|
||||
@@ -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
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user