docs(chore): step 5 — annotation rendering contract, CLAUDE.md map and conventions, README, DEPLOY SHEET_BUNDLE, PDF format v3, spec §6 migration map, plan/changelog/strategy notes; BDR-038, LRN-043, TODO

This commit is contained in:
bchanot committed 2026-10-10 11:41:55 +02:00
1 parent ce2ec26112
commit 0476276a8f
19 files changed
+276 -112

No files matched your search

+17 -2
View File
@@ -304,7 +304,9 @@ the decision lands; only the naming one is implemented in this document.
## 6. Official equine sheet: import (Step 4b) and curation (Step 4c)
`packages/anatomy` holds a deterministic pipeline (`pnpm import:equine`)
that reads `Horse.svg`, `Horse_head.svg` and `pathologies.json`, then the
that reads the historical files kept under
`supabase/seed/anatomical-sheets/equine/legacy-sources/` (`Horse.svg`,
`Horse_head.svg`, `pathologies.json`, `vertebrae.ts`, never edited), then the
authored curation files, and writes under
`supabase/seed/anatomical-sheets/equine/`:
@@ -312,7 +314,7 @@ authored curation files, and writes under
| ---------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `legacy-import/` | generated baseline | canonical `document.json`, `legacy-id-map.json` (every legacy `data-anno-id`, category slug and view key → new id), `assets.json` + byte-identical SVG copies, `IMPORT-REPORT.md` (French, for the osteopath: volumes, mappings, anomalies). No SQL. |
| `curation/` | authored, committed | `references.json` (the references registry) and `changes.json` (the changeset) |
| `draft/` | generated working revision | curated `document.json`, `assets.json` + `assets/horse.svg`, `CHANGELOG.md`, `REVIEW-REPORT.md`, `review/annotations-<view>.svg` (before/after drawing per view), `equine_draft.sql` |
| `draft/` | generated working revision | curated `document.json`, `assets.json` + `assets/horse.svg`, `sheet-ref.json` (sheet id, null version id, sha256 of the document), `report-migration-map.json` (legacy ids and finding paths → the draft, for Report v2 imports), `CHANGELOG.md`, `REVIEW-REPORT.md`, `review/annotations-<view>.svg` (before/after drawing per view), `review/app-<view>.svg` (the application's own rendering), `equine_draft.sql` |
Changeset (`packages/anatomy/src/curation/schema.ts`): each change has an
id `CHG-nnn`, a level (A demonstrated error, B supported improvement, C
@@ -388,6 +390,19 @@ database that still holds a schema 1 draft (a dev database seeded before Step
data migration that lifts stored documents to the current schema, then
tightens the CHECK (BLK-008). Future schema bumps follow that order.
Report migration map (Step 5): `draft/report-migration-map.json` replays the
applier's rename, move and removal records over every node of the legacy
baseline (792 nodes: 571 identical, 180 renamed or moved, 7 re-homed under
another category when the match is unique, 34 removed = `null`), maps the 27
legacy `data-anno-id` to annotation ids with the legacy names, and the `head`
detail key to the view. `migrateReportV2ToV3` (packages/domain) reads it; a
report keeps what the map cannot place, flagged `unresolved`.
Annotation colour (Step 5, additive, schema_version stays 2): `annotations[].color`
overrides `categories[].color` for the marker drawn by the application
(docs/ANNOTATION-RENDERING.md); the curation changeset CHG-045 carries the
legacy colours.
Seed: `equine_draft.sql` is idempotent and converging. On a fresh database
it inserts the sheet, the cleaned asset row and the draft through
`private.insert_sheet_draft`; when the sheet's only version is a draft
@@ -1,6 +1,11 @@
# Characterisation report (plan Step 1)
Status: done 2026-10-08, branch `feature/step-01-characterisation-tests`.
Note 2026-10-10 (Step 5): the legacy suites this report lists were replaced one-to-one
by suites on the canonical sheet (`services.zoneInteraction`, `sheets.provider`,
`state.reportStore`, `pdf.roundtrip`, `components.*`, `routes.EditorRoute`); the
frozen v2 fixtures (`report-v2.*.json`, `report-v2.*.pdf`) remain the oracle of the
v2 → v3 migration.
Scope: a tested photograph of the current application before any SaaS
transformation. No file under `src/`, `public/`, `scripts/`, `docker/` was
changed. Commands run on this host: Node 24.21.0, pnpm 10.13.1 (corepack),
+6
View File
@@ -161,6 +161,12 @@ Risks: subtle divergences between parser and importer on the detail trigger (no
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).
Step 5 done 2026-10-10 (branch feature/step-05-app-on-canonical-sheet, awaiting user validation):
Report v3 + v2 migration (packages/domain/report), report-migration-map + sheet-ref + app review
drawings from the pipeline, annotation layer renderer (@faunosteo/anatomy/render), bundled
SheetProvider (SHEET_BUNDLE), zoneInteraction service, store on v3 with persistence adapter, PDF v3
with v2 archive import, legacy registry / matchers / editors / public species assets removed
(legacy sources moved under the seed). Visible changes limited to the validated 4c content and D6/D7.
```
```text
+11
View File
@@ -22,6 +22,9 @@ evolves without a big-bang rewrite. The step-by-step schedule is in
## 2. `reportStore`
Status 2026-10-10: moves A and B done in Step 5 (`state/persistence.ts`,
Report v3 in `packages/domain/report`); move C pending (Cloud reports).
Today: Zustand store holding `Report | null`, 14 actions, a `subscribe` that
mirrors every change to `sessionStorage['osteo:draft']`, restore on boot via
`ReportSchema.safeParse` (`reportStore.ts:42-56`, `159-167`).
@@ -39,6 +42,10 @@ UI state stay client-only.
## 3. Anatomy domain
Status 2026-10-10: points 1, 2, 4, 5 and 6 done (Steps 4, 4b, 5). Point 3 differs:
ids are stable slugs, not UUIDs (BDR-031/034). The renderer emits elements from
the document's geometry, not attributes on legacy elements (docs/ANNOTATION-RENDERING.md).
Today: four sources with no common object (manifest TS, two SVG files
fetched from `public/`, catalog JSON bundled), link by fuzzy label at render
time (audit 02 §1, 06 §1).
@@ -82,6 +89,10 @@ Evolution:
## 4. PDF
Status 2026-10-10: Step 5 took the sheet as export input and attached v3 with
v2 import; points 2 (sheet snapshot in the attachment), 3 (server import) and 5
(branding object) stay for Step 6.
Today: `exportReportToPdf(report, { locale })` re-fetches SVGs from
`public/`, re-parses them for labels, reloads the catalog through the
registry, rasterises in the browser, attaches the raw `Report` JSON.
+2 -1
View File
@@ -19,9 +19,10 @@ supabase/
│ └─ 20261010100000_sheet_document_schema_v2.sql document schema 2: references, review_status, count_range checks
├─ seed.sql LOCAL dev accounts + first owner (never run in prod)
├─ seed/anatomical-sheets/equine/ official equine sheet as a DRAFT, generated by `pnpm import:equine`
│ ├─ legacy-sources/ the historical Horse.svg, Horse_head.svg, pathologies.json, vertebrae.ts (importer input)
│ ├─ legacy-import/ baseline import (document, id map, SVG copies, IMPORT-REPORT.md), no SQL
│ ├─ curation/ authored changes.json + references.json
│ └─ draft/ curated working revision (document, horse.svg, CHANGELOG, REVIEW-REPORT, review/*.svg) + equine_draft.sql: idempotent, converging seed (sheet, 1 asset row, working draft), applied by db reset and by PGlite
│ └─ draft/ curated working revision (document, horse.svg, sheet-ref.json, report-migration-map.json, CHANGELOG, REVIEW-REPORT, review/*.svg; bundled into the app with SHEET_BUNDLE=draft) + equine_draft.sql: idempotent, converging seed (sheet, 1 asset row, working draft), applied by db reset and by PGlite
└─ tests/ pgTAP, one file per concern, allowed AND denied paths
packages/supabase/
├─ src/client.ts createBrowserClient() (anon key, PKCE)
+6 -7
View File
@@ -85,7 +85,6 @@ works as `corepack pnpm <cmd>`.
| `pnpm build` | typecheck + Vite build in every package |
| `pnpm check` | typecheck, test:run, lint, build in sequence (what CI runs) |
| `pnpm format` | Prettier on the whole repository |
| `pnpm scaffold:species` | legacy species scaffold (slated for removal) |
Package-scoped: `pnpm --filter @faunosteo/app <script>`.
@@ -105,13 +104,13 @@ Package-scoped: `pnpm --filter @faunosteo/app <script>`.
"Ignored build scripts" warning.
2. `pnpm typecheck`, `pnpm test:run` (271 tests), `pnpm lint`, `pnpm build`
all exit 0; `apps/app/dist/` contains `index.html`, `env.js`,
`pathology-editor.html`, `species/equine/{Horse.svg,Horse_head.svg,pathologies.json}`.
`favicon`, logos (anatomy assets are bundled from the sheet seed, Step 5).
3. `pnpm dev`, then in the browser: `/` (home), `/new` (form, species defaults
to Cheval), `/editor` (SVG loads, click a hinge, a hip, a spine zone, the
head trigger; pickers open; findings picker lists the zone), export the
PDF, go back to `/` and import it; `/svg-editor` loads a project SVG;
`/pathology-editor.html` loads the pre-wired horse. Behaviour must match
`CHARACTERIZATION_REPORT.md`.
to Cheval), `/editor` (the bundled sheet renders, click a hinge, a hip, a
spine zone, the head trigger; pickers open; findings picker lists the
zone), export the PDF, go back to `/` and import it, then import an older
v2 PDF. Behaviour must match the suites listed in
`CHARACTERIZATION_REPORT.md` (note of 2026-10-10).
4. `grep -rn "/home/\|/Users/" apps/app/tests` returns nothing (no
machine-specific path; fixtures resolve from `import.meta.url`).
5. `docker build -t faunosteo .` then `docker compose up` and