diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md index 4e0643bd..6e63f40f 100644 --- a/.claude/memory/journal.md +++ b/.claude/memory/journal.md @@ -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. diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index 230f5965..5f83e6e6 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -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 --- diff --git a/docs/development/IMPLEMENTATION_PLAN.md b/docs/development/IMPLEMENTATION_PLAN.md index bcf7dae4..13595b8d 100644 --- a/docs/development/IMPLEMENTATION_PLAN.md +++ b/docs/development/IMPLEMENTATION_PLAN.md @@ -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 diff --git a/docs/development/STEP5_MIGRATION_ANALYSIS.md b/docs/development/STEP5_MIGRATION_ANALYSIS.md new file mode 100644 index 00000000..3043de8a --- /dev/null +++ b/docs/development/STEP5_MIGRATION_ANALYSIS.md @@ -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 `-observations` category became + `-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 + (``): 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: { "": "" }, from legacy-id-map + views: { "head": "head", "": "main" }, detailSourceId → viewId + findingPaths: { "/": "/" | 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 = { ref: { sheetId, versionId, documentSha256 }, document: AnatomicalSheetDocument, + assets: Record } +``` + +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 +``: + +- the drawing is the cleaned asset text, parsed once and sanitised (no + `