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:
1 parent
ce2ec26112
commit
0476276a8f
19 files changed
+276
-112
No files matched your search
@@ -319,3 +319,11 @@ Status: closed; content awaits professional review (REVIEW-REPORT §10, 9 questi
|
||||
|
||||
User decisions: curated equine draft = reference draft of the app until published (no publication without professional review); technical integrity ≠ medical validation (`inherited` / `reviewed` / `to_confirm` stay visible, REVIEW-REPORT the hand-off doc for the osteopath, 11 open questions → next changeset); future schema changes = incremental non-destructive migrations (BLK-008); legal scope text re-read on consolidated Légifrance texts before publication; head view preserved as crop, per-view assets still possible. Docker `faunosteo_` rule permanent; `.env.example` change documented in DEPLOY.md (file denied to Claude). SaaS development continues without waiting for medical validation.
|
||||
Status: closed.
|
||||
|
||||
---
|
||||
|
||||
## BDR-038 | 2026-10-10 | Step 5: app on the canonical sheet — bundled sheet, layer renderer, Report v3, migration map
|
||||
|
||||
Sheet source: `SheetProvider` interface; Step 5 implementation = Vite virtual module `virtual:faunosteo-sheet` built from the seed draft (`vite/sheet-bundle.ts`), mode `SHEET_BUNDLE=draft|none`, default draft for dev server, none for builds/CI/Docker (`--build-arg SHEET_BUNDLE=draft` = explicit preview) → unvalidated draft never ships by accident (D2). Markers: pure renderer `@faunosteo/anatomy/render` (element tree, no DOM) reproduces legacy look (hitbox r + twin r−12, opacities 0.65/0.5, spine 0.3, trigger 0.06 dashed); colours = document data (`categories[].color`, additive `annotations[].color` for the head shades, schema_version stays 2 for additive optional fields); same renderer feeds `draft/review/app-<view>.svg` for visual checks. Report v3 in packages/domain: `(annotationId, viewId)` zones with label snapshots, `(findingZoneId, path)` findings, severity codes, `sheet {sheetId, versionId|null, documentSha256}`, `unresolved: true` for what migration cannot place, `localAnnotations: []` reserved. Migration map generated by the pipeline from applier records (replay renames/moves/removals + unique re-homing): 792 nodes → 571/180/7/34. Interaction = pure service + reducers (BDR-019 kept); store = v3 + persistence adapter (v2 draft migrated on restore). D4 applied: registry, matchers, SVG parser, editors, pathology-editor, public species assets deleted; legacy sources moved to `supabase/seed/.../legacy-sources/` (importer input).
|
||||
Alt rejected: copying the draft into apps/app (duplication, drift); runtime fetch of `/sheets/*.json` (still public, no gain); UUID annotation ids (BDR-031); converting v3→v2 for attachments (lossy); per-view colour table in the app (horse knowledge in generic code).
|
||||
Status: closed; awaiting user validation of Step 5.
|
||||
@@ -190,3 +190,4 @@ Step 4 validated + finished into develop. User decisions on the 7 open points
|
||||
- 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.
|
||||
- Step 5 implemented (2026-10-10, feature/step-05-app-on-canonical-sheet): domain report v3 + migration (80 tests), pipeline migration map/sheet-ref/app review drawings + layer renderer (110), app rewritten on the sheet (99 tests: service, store, provider, canvas, pickers, PDF v2/v3, route), legacy code removed, docs rewritten (ANNOTATION-RENDERING.md replaces the SVG convention). Root check green, docker build OK, real stack 267/267, default build carries no sheet. BDR-038, LRN-043. Gates next; awaiting user validation.
|
||||
@@ -323,3 +323,10 @@ Apply: every pgTAP touching storage.*; every workspace CLI.
|
||||
|
||||
Authoring 44 changes / 679 ops by hand is error-prone → scratch python modules (one per research theme, shared helpers `set_op/cite_op/add_change`, auto-numbered ids, targets derived from the baseline by walking it) built into changes.json; the pipeline's Zod + integrity rules catch any bad target at once. Order of modules = order of ops: a later module must address ids renamed by an earlier one (consultation-reason category ids). Stylised drawing: render with `magick` + 50-unit grid crops; sample first non-white row per column to prove "point floats above the silhouette" (t18-l1, l6-s1 were 30-70 units above the back). ImageMagick's internal SVG renderer drops shapes with `fill="none"` and shapes containing a `<title>` child → overlay uses fill-opacity and puts `<title>` on the `<g>`. Research agents: one theme each, every citation tagged VERIFIED-fetched/snippet/UNVERIFIED; only fetched or bibliographically confirmed entries enter the registry, unread books say "non consulté" in the citation.
|
||||
Apply: next species/sheet curation; any overlay/diagnostic SVG rasterised with ImageMagick.
|
||||
|
||||
---
|
||||
|
||||
## LRN-043 | 2026-10-10 | Migrating an app onto a new data model: freeze goldens first, make ids + maps data, read fresh state in DOM handlers
|
||||
|
||||
Freeze golden artifacts with the OLD code before touching it (v2 PDFs via a one-shot vitest, MAKE_GOLDEN=1, deleted after): the new importer is then tested against real archive-like bytes. Generate id/path maps from the pipeline's own records (renames/removals), never hand-written, and commit them as golden-tested data. In React routes, click handlers bound through `useEffect` capture stale closures when two DOM clicks land before a re-render (tests dispatch synchronously): read `store.getState()` inside the handler. A sheet needed to restore a draft but only known from the draft → load the default species' sheet when no report is open. Vitest has its own config: a Vite plugin providing a virtual module must be registered there too. ImageMagick cannot verify marker look with `<title>` children or `fill="none"`: strip titles for the raster only.
|
||||
Apply: Step 6 (PDF v3 snapshot), Step 13 (Supabase SheetProvider), any future schema bump.
|
||||
@@ -86,15 +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
|
||||
- [ ] Step 5 — application on the canonical sheet (analysis validated 2026-10-10; implemented on feature/step-05-app-on-canonical-sheet, AWAITING user validation; D5 orphan findings documented as UX follow-up)
|
||||
- [x] 5.0 freeze: golden v2 PDFs + expected v3 docs; CHARACTERIZATION_REPORT refreshed
|
||||
- [x] 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)
|
||||
- [x] 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
|
||||
- [x] 5.3 app foundation: bundledSheetProvider (Vite alias @sheets), sheetIndex, sanitiser, renderAnnotationLayer (legacy look), AnatomyCanvas/DetailModal on views (head = crop)
|
||||
- [x] 5.4 zoneInteraction service + reducers, store split + sessionStoragePersistence (v2 migration on load), pickers/cards on sheetIndex (D6 ranges, D7 title), EditorRoute < 300 lines
|
||||
- [x] 5.5 PDF shim + attachment v3 + v2 import (gate D3)
|
||||
- [x] 5.6 delete legacy (registry, species/*, zoneMatch, spineZones, svgConvention, D4 tools), SVG convention doc replaced, CLAUDE.md map, CHANGELOG, plan note, memory
|
||||
- [~] 5.7 visual before/after done (cmp renders), root check + docker + real stack green; gates verifier + security pending; manual FR/EN flow = user validation
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -11,6 +11,7 @@ Versions follow [Semantic Versioning](https://semver.org/).
|
||||
- **Supabase foundation** — local stack (`supabase/config.toml`), migrations (schemas `private` / `audit`, `profiles`, platform roles with audited RPCs), pgTAP suite run on PGlite (`pnpm test:run`) and on the real stack (`pnpm db:test`), `@faunosteo/supabase` typed client + generated types. No UI change.
|
||||
- **Anatomical sheet model** — `@faunosteo/domain`: canonical sheet document (views tree, annotations with stable ids and explicit laterality, ordered vertebral regions, typed finding categories, explicit annotation → finding zone links, FR/EN labels) with integrity validation; tables `species`, `anatomical_sheets`, `anatomical_sheet_versions` (published rows immutable, one draft per sheet, deletion preconditions), `anatomical_sheet_assets`; lifecycle RPCs (create, draft, publish, deprecate, delete, fork with provenance, archive, assets) audited and under RLS. Spec: `docs/development/ANATOMICAL_SHEET_MODEL.md`.
|
||||
|
||||
- **Application on the canonical sheet (Step 5)** — the editor renders the bundled reference sheet (curated equine draft, `SHEET_BUNDLE=draft`; a default build carries no sheet): markers drawn from the document with the legacy look (`@faunosteo/anatomy/render`), head view as a crop of the same drawing, zone interaction service, pickers on the sheet's regions (usual count, extension to the documented range) and finding zones. Report document **v3** (`packages/domain/report`): zones by annotation and view ids, findings by zone and path, severity codes, exact sheet reference; v2 PDFs and drafts migrate through the generated `report-migration-map.json`, unresolved items kept with their labels. Removed: species registry, label matchers, SVG convention parser, `/editors`, `/svg-editor`, `pathology-editor.html`, `scaffold:species`; the legacy sources now live under `supabase/seed/anatomical-sheets/equine/legacy-sources/`.
|
||||
- **Equine sheet curation (Step 4c)** — document schema v2 (references registry, `review_status` on findings and annotations, configurable vertebral `count_range`; migration `20261010100000`, pgTAP 008); `@faunosteo/anatomy` curation pipeline: authored changeset (`curation/changes.json`, levels A/B/C, before/after records) applied to the legacy baseline → working draft with `CHANGELOG.md`, `REVIEW-REPORT.md` (10 sections for the osteopath) and before/after review drawings; one cleaned SVG asset, head view as a crop. Content: research-backed audit of the horse sheet (44 changes, 48 verifiable references): sphenoid zone restructured, NAV terminology, FR/EN translations, vertebral ranges, ten SVG points relocated, carpus zone added, veterinary red flags, legal disclaimer anchored on R. 243-6 / R. 243-8, osteopathic-model status on unvalidated concepts, 11 questions for the professional. Still a private DRAFT, not published. Docker resources prefixed `faunosteo_` (Compose project and container).
|
||||
- **Equine import (Step 4b)** — `@faunosteo/anatomy` deterministic importer: `Horse.svg` + `Horse_head.svg` + `pathologies.json` → canonical document, legacy id map, French import report, idempotent seed creating the official sheet `faunosteo-cheval` as a private DRAFT (never published by code). Storage bucket `anatomical-sheet-assets` (content-addressed SVGs, read through the sheet, operator upload script).
|
||||
|
||||
|
||||
@@ -14,8 +14,10 @@ attachment so importing it restores the session for a follow-up.
|
||||
SPA deployed via Docker + nginx on Scaleway VPS. Backend foundation on Supabase
|
||||
(PostgreSQL + Auth + RLS) since Step 3 of the SaaS plan: profiles, platform roles and
|
||||
audit log exist; Step 4 added the canonical anatomical sheet model (`packages/domain`,
|
||||
tables `species`, `anatomical_sheets` / `_versions` / `_assets`). The UI does not use
|
||||
the client yet (local-only flows unchanged).
|
||||
tables `species`, `anatomical_sheets` / `_versions` / `_assets`). Step 5 moved the
|
||||
application onto that model: the editor renders the bundled reference sheet (the
|
||||
curated equine DRAFT, `SHEET_BUNDLE=draft`), writes Report v3 and imports v2 PDFs
|
||||
through a generated migration map. The Supabase client is still unused by the UI.
|
||||
MVP species: equine only. Open-source MIT.
|
||||
|
||||
---
|
||||
@@ -81,6 +83,11 @@ pnpm db:reset # replay from zero
|
||||
pnpm db:test # pgTAP on the real stack
|
||||
pnpm db:types # regenerate packages/supabase/src/database.types.ts
|
||||
pnpm db:types:check # CI diff
|
||||
|
||||
# Reference sheet in the app: the dev server bundles the curated draft; a build does not
|
||||
pnpm build:preview # SHEET_BUNDLE=draft build (manual validation, preview deployments)
|
||||
pnpm preview:draft # same, then serves it
|
||||
pnpm import:equine # regenerate legacy-import/ and draft/ (document, migration map, review drawings)
|
||||
```
|
||||
|
||||
## Docker commands
|
||||
@@ -89,6 +96,9 @@ pnpm db:types:check # CI diff
|
||||
# Build image
|
||||
docker build -t faunosteo .
|
||||
|
||||
# Build an image that embeds the reference DRAFT sheet (preview only, never the default)
|
||||
docker build --build-arg SHEET_BUNDLE=draft -t faunosteo .
|
||||
|
||||
# Run with compose (reads .env for APP_* vars)
|
||||
docker compose up --build
|
||||
|
||||
@@ -136,40 +146,28 @@ pnpm format # Prettier write
|
||||
```
|
||||
faunosteo/
|
||||
├─ apps/app/ ← @faunosteo/app (everything below until packages/)
|
||||
├─ public/
|
||||
│ ├─ species/equine/{Horse,Horse_head}.svg ← real anatomy SVGs
|
||||
│ └─ pathology-editor.html ← standalone JSON editor (served as static file)
|
||||
├─ public/ ← logos only (no anatomy asset: the sheet is bundled)
|
||||
├─ vite/sheet-bundle.ts ← Vite plugin: `virtual:faunosteo-sheet` (SHEET_BUNDLE=draft|none)
|
||||
├─ src/
|
||||
│ ├─ app/
|
||||
│ │ ├─ App.tsx ← root router
|
||||
│ │ ├─ routes/{Home,NewReport,Editor,Editors,SvgEditor,NotFound}Route.tsx
|
||||
│ │ ├─ routes/{Home,NewReport,Editor,NotFound}Route.tsx
|
||||
│ │ └─ providers/ConfigProvider.tsx ← AppConfig context
|
||||
│ ├─ config/env.ts ← runtime config resolution
|
||||
│ ├─ domain/
|
||||
│ │ ├─ schema/ ← Zod schemas (source of truth)
|
||||
│ │ │ ├─ report.ts
|
||||
│ │ │ ├─ observation.ts
|
||||
│ │ │ ├─ practitioner.ts
|
||||
│ │ │ ├─ animal.ts
|
||||
│ │ │ └─ findings.ts
|
||||
│ │ └─ species/
|
||||
│ │ ├─ types.ts ← SpeciesManifest interface
|
||||
│ │ ├─ registry.ts ← getSpecies(), getAllSpecies()
|
||||
│ │ └─ equine/{index,vertebrae,pathologies}.{ts,json}
|
||||
│ ├─ sheets/{provider,useSheet}.ts ← SheetProvider interface, bundled implementation, per-species hook
|
||||
│ ├─ services/
|
||||
│ │ ├─ sheetIndex.ts ← read-only lookups over the loaded sheet (ids, never labels)
|
||||
│ │ └─ zoneInteraction.ts ← pure click decision + observation reducers (zones, sides, vertebrae)
|
||||
│ ├─ i18n/
|
||||
│ │ ├─ types.ts ← Locale type + Dict type
|
||||
│ │ ├─ fr.ts + en.ts ← translation dicts (flat key → string)
|
||||
│ │ ├─ index.ts ← getDict(locale)
|
||||
│ │ └─ useT.ts ← useT() hook (reads localeStore)
|
||||
│ ├─ state/
|
||||
│ │ ├─ reportStore.ts ← Zustand store
|
||||
│ │ ├─ reportStore.ts ← Zustand store (Report v3) + persistence.ts (sessionStorage adapter, v2 draft migration)
|
||||
│ │ ├─ localeStore.ts ← locale Zustand store (persisted to localStorage)
|
||||
│ │ └─ practitionerCache.ts ← localStorage prefill
|
||||
│ ├─ anatomy/
|
||||
│ │ ├─ types.ts ← Bone, BoneCategory, BoneState
|
||||
│ │ ├─ svgConvention.ts ← parseSvgBones()
|
||||
│ │ ├─ svgLoader.ts ← loadSvg()
|
||||
│ │ └─ labels.ts ← boneLabel(bone, locale, fallback)
|
||||
│ ├─ anatomy/drawing.ts ← sanitised asset + generated annotation layer → inline <svg> per view
|
||||
│ ├─ components/
|
||||
│ │ ├─ ui/{Button,Card,Dialog,Input,Label,Select,Textarea,Badge,Chip}.tsx
|
||||
│ │ ├─ canvas/{AnatomyCanvas,DetailModal}.tsx
|
||||
@@ -182,8 +180,8 @@ faunosteo/
|
||||
│ ├─ pdf/
|
||||
│ │ ├─ export.ts + import.ts + attachment.ts + fonts.ts
|
||||
│ │ └─ render/{header,footer,observationPage,conclusionPage,svgToPng,text,logo,linkAnnotation}.ts
|
||||
│ ├─ lib/{dates,id,assert,zoneMatch,spineZones,supabase}.ts ← supabase.ts: getSupabaseClient() | null
|
||||
│ ├─ styles/{index,tokens,svg-editor}.css ← Tailwind v4 CSS-first + SVG editor styles
|
||||
│ ├─ lib/{dates,id,assert,supabase}.ts ← supabase.ts: getSupabaseClient() | null
|
||||
│ ├─ styles/{index,tokens}.css ← Tailwind v4 CSS-first
|
||||
│ └─ main.tsx
|
||||
├─ tests/
|
||||
│ ├─ setup.ts
|
||||
@@ -192,8 +190,7 @@ faunosteo/
|
||||
│ ├─ entrypoint.sh ← injects env.js at container start
|
||||
│ └─ nginx.conf ← SPA fallback + PORT envsubst
|
||||
├─ docs/
|
||||
│ ├─ ANATOMY-SVG-CONVENTION.md ← SVG data-* contract
|
||||
│ ├─ ADDING-A-SPECIES.md
|
||||
│ ├─ ANNOTATION-RENDERING.md ← annotation layer contract (attributes, styles, colours)
|
||||
│ ├─ PDF-FORMAT.md
|
||||
│ ├─ faunosteo-audit/ ← audit of the current system (frozen at 83e40af)
|
||||
│ ├─ development/ ← SaaS implementation plan, WORKSPACE.md
|
||||
@@ -204,7 +201,7 @@ faunosteo/
|
||||
├─ packages/domain/ ← @faunosteo/domain (pure, no DOM, zod only)
|
||||
│ ├─ src/anatomical-sheet/{schema,validate,create}.ts ← canonical sheet document + integrity rules
|
||||
│ └─ tests/{fixtures/horse-slice.ts,*.test.ts}
|
||||
├─ packages/anatomy/ ← @faunosteo/anatomy: legacy importer (SVG + catalog → canonical document) + curation
|
||||
├─ packages/anatomy/ ← @faunosteo/anatomy: legacy importer, curation pipeline, pure annotation-layer renderer (`./render`)
|
||||
│ ├─ src/legacy/{svg,catalog,regions,ids,report,importer}.ts, src/cli/import-equine.ts
|
||||
│ ├─ src/curation/{schema,targets,fields,ops,rename,apply,types,assets,labels,stats,changelog,review-report,overlay,seed,sources,pipeline}.ts ← changeset → draft
|
||||
│ └─ tests/ ← counts preserved, special cases, determinism, curation ops, golden artifacts
|
||||
@@ -215,9 +212,10 @@ faunosteo/
|
||||
│ ├─ config.toml, seed.sql ← CLI config (public schema only), local dev accounts
|
||||
│ ├─ migrations/*.sql ← forward-only; foundation, profiles, platform_roles, anatomical_sheets, storage, sheet_document_schema_v2
|
||||
│ ├─ seed/anatomical-sheets/equine/
|
||||
│ │ ├─ legacy-sources/ ← the historical Horse.svg, Horse_head.svg, pathologies.json, vertebrae.ts (importer input, never edited)
|
||||
│ │ ├─ legacy-import/ ← GENERATED baseline: document, id map, IMPORT-REPORT, SVG copies (no SQL)
|
||||
│ │ ├─ curation/{changes,references}.json ← AUTHORED changeset + references registry (never generated)
|
||||
│ │ └─ draft/ ← GENERATED working revision: document, cleaned horse.svg, CHANGELOG, REVIEW-REPORT, review/*.svg, equine_draft.sql
|
||||
│ │ └─ draft/ ← GENERATED working revision: document, cleaned horse.svg, sheet-ref, report-migration-map, CHANGELOG, REVIEW-REPORT, review/*.svg, equine_draft.sql
|
||||
│ └─ tests/*.sql ← pgTAP: allowed + denied paths per policy
|
||||
├─ packages/README.md ← shared packages index
|
||||
├─ .gitea/workflows/ci.yml ← CI: install, typecheck, test, lint, build, docker
|
||||
@@ -238,13 +236,16 @@ User interaction
|
||||
→ Zustand store (reportStore)
|
||||
→ Components read store via selectors (no prop drilling)
|
||||
|
||||
Sheet loading
|
||||
→ useSheet(speciesId) → SheetProvider (bundled: virtual:faunosteo-sheet, SHEET_BUNDLE=draft)
|
||||
→ Zod-validated document + assets + migration map → buildSheetIndex()
|
||||
|
||||
SVG interaction
|
||||
→ AnatomyCanvas fetches SVG text via loadSvg()
|
||||
→ parseSvgBones() walks DOM → Bone map
|
||||
→ delegated click listener → getBoneIdFromEvent()
|
||||
→ if spine-zone → VertebraPicker modal
|
||||
→ if data-anno-opens-detail → DetailModal (loads detail SVG)
|
||||
→ else → updateObservation() in store
|
||||
→ AnatomyCanvas builds the view: sanitised asset + renderAnnotationLayer() (markers from the document)
|
||||
→ delegated click on [data-anno-id] → decideZoneClick() (services/zoneInteraction, pure)
|
||||
→ open_view → DetailModal (same drawing, view_box crop, or the view's own asset)
|
||||
→ open_vertebra_picker / open_laterality_picker → pickers → reducers (ensureZone, addSides, syncVertebrae)
|
||||
→ toggle / remove_both_sides → updateObservation() in store
|
||||
|
||||
PDF export
|
||||
→ exportReportToPdf(report, { locale })
|
||||
@@ -256,9 +257,9 @@ PDF export
|
||||
→ Uint8Array → browser download
|
||||
|
||||
PDF import
|
||||
→ importReportFromPdf(bytes)
|
||||
→ extractReportJson → Zod validate
|
||||
→ hydrateReport() → navigate /editor
|
||||
→ importReportFromPdf(bytes, migrationMap)
|
||||
→ extractReportJson → readReportDocument (v3 as is, v2 migrated, else incompatible_version)
|
||||
→ hydrateReport() → navigate /editor (unresolved zones/findings kept and flagged)
|
||||
|
||||
Runtime config
|
||||
→ Docker entrypoint writes env.js (window.__APP_CONFIG__)
|
||||
@@ -290,7 +291,7 @@ Database (Supabase)
|
||||
- Both dicts must share the exact same key set; a key missing in one dict logs a warning in DEV
|
||||
- Get the translate function in any component: `const t = useT()` then `t('common.cancel')`
|
||||
- `src/state/localeStore.ts` holds current `Locale` (`'fr' | 'en'`), persisted to `localStorage` key `osteo:locale`; default: navigator-detected `fr`/`en`, or `'fr'` if no match
|
||||
- Finding leaf labels (zone names shown in PDF) are resolved at export time via SVG `data-anno-name-fr` / `data-anno-name-en` attributes — not from the dict
|
||||
- Zone and finding names shown in the editor and the PDF come from the sheet document (`{ fr, en }` labels) and from the report's snapshots, not from the dict
|
||||
- PDF static labels (section headings, metadata) come from the dict via `getDict(locale)` in `exportReportToPdf`
|
||||
|
||||
### Identity strings
|
||||
@@ -298,34 +299,40 @@ Database (Supabase)
|
||||
- Always read from ConfigProvider via useConfig()
|
||||
- src/config/env.ts is the only place with defaults
|
||||
|
||||
### SVG convention
|
||||
- docs/ANATOMY-SVG-CONVENTION.md is the source of truth
|
||||
- Every clickable element must have: data-anno-id, data-anno-name-fr, data-anno-name-en, data-anno-category
|
||||
- SvgConventionError thrown on any missing required attribute
|
||||
- Never rely on element id or className for click targeting — always data-anno-id
|
||||
### Annotation rendering
|
||||
- docs/ANNOTATION-RENDERING.md is the source of truth: the drawing carries no annotation element, the app draws
|
||||
the markers from the document (`@faunosteo/anatomy/render`), with the attributes listed there
|
||||
- Never rely on element id, className or a label for click targeting or behaviour — always `data-anno-id`
|
||||
and the annotation's fields (`laterality`, `vertebral_region_code`, `opens_view_id`)
|
||||
- Marker look (radii, opacities, strokes) is renderer style; colours are document data (`color` on categories
|
||||
and annotations); no graphic redesign without prior validation
|
||||
|
||||
### Schemas
|
||||
- domain/schema/*.ts are the data contracts — never change without bumping version
|
||||
- `packages/domain/src/report/*.ts` are the report data contracts (v3 current, v2 input only); never change
|
||||
without bumping the version on a breaking change (additive optional fields keep it)
|
||||
- All user-provided data goes through Zod parse before hitting the store
|
||||
- ReportSchema.version = 2 (v1 attachments rejected at import with a typed error); future breaking changes → version 3
|
||||
- Report version 3: zones by `(annotationId, viewId)`, findings by `(findingZoneId, path)`, severities
|
||||
`mild|moderate|severe`, `sheet` reference; v2 is migrated through `report-migration-map.json`
|
||||
(`migrateReportV2ToV3`, never throws on content, `unresolved: true` marks what the sheet no longer holds);
|
||||
v1 and unknown versions are refused with a typed error
|
||||
|
||||
### Stores
|
||||
- No direct store mutation outside Zustand actions
|
||||
- No business logic in components — delegate to store actions
|
||||
- sessionStorage key: osteo:draft (auto-saved on every observation change)
|
||||
- sessionStorage key: osteo:draft (auto-saved on every change, v3; a v2 draft is migrated on restore once the sheet is loaded)
|
||||
- localStorage key: osteo:lastPractitioner (practitioner prefill cache)
|
||||
|
||||
### PDF
|
||||
- A4 portrait: 595.28 × 841.89 pt
|
||||
- No raw URLs in PDF output — abbreviated citations only
|
||||
- JSON attachment filename must start with osteo-report
|
||||
- JSON attachment filename must start with osteo-report; content = Report v3; import accepts v2 (migrated) and v3
|
||||
- Fonts are StandardFonts (Helvetica/TimesRoman, WinAnsi encoding) — TTF Inter/Fraunces planned but not yet embedded. Any non-Latin-1 glyph in PDF text must use an ASCII surrogate until the TTF migration lands (e.g. `(!)` instead of `⚠`).
|
||||
|
||||
### Pathology DB
|
||||
- All entries must pass PathologySchema.parse()
|
||||
- Each entry needs ≥1 source with citation
|
||||
- boneIds: [] = all zones; speciesIds: [] = all species
|
||||
- Source types: manual | journal | database | web
|
||||
### Anatomical sheet content
|
||||
- The findings catalog, the vertebral regions and the markers are the canonical sheet document; every content
|
||||
change goes through `supabase/seed/anatomical-sheets/equine/curation/changes.json` (see the sheet model section)
|
||||
- The curated draft is the reference content in development (`SHEET_BUNDLE=draft`); it is not medically
|
||||
validated and a production build carries no sheet unless that flag is set on purpose
|
||||
|
||||
### Database (Supabase)
|
||||
- Platform roles (`platform_role`: owner/admin/moderator/support) are NOT professional
|
||||
@@ -404,11 +411,11 @@ Database (Supabase)
|
||||
|
||||
- Run `pnpm typecheck && pnpm test:run` before every commit.
|
||||
- Domain schema changes (domain/schema/*.ts) require updating all callers + bumping version if breaking.
|
||||
- SVG convention changes require updating docs/ANATOMY-SVG-CONVENTION.md first.
|
||||
- Never modify anatomy SVGs in public/species/ — they are source assets from the user.
|
||||
- Pathology DB entries must be source-cited before commit; client review required for MVP batch.
|
||||
- Annotation rendering changes require updating docs/ANNOTATION-RENDERING.md first.
|
||||
- Never modify the legacy sources under `supabase/seed/anatomical-sheets/equine/legacy-sources/` — they are the
|
||||
importer's input (the user's historical files).
|
||||
- Ask before any change to importReportFromPdf or extractReportJson — these handle user data.
|
||||
- After PDF roundtrip tests fail: check attachment bytes, then Zod validation, then DecompressionStream inflation.
|
||||
- After PDF roundtrip tests fail: check attachment bytes, then Zod validation (v3, or v2 through the migration map), then DecompressionStream inflation.
|
||||
- Node 24 / pnpm 10.13.1: `corepack enable` or `corepack pnpm`; never a global install.
|
||||
- SQL change: `pnpm --filter @faunosteo/supabase test:run` (PGlite) before commit; `pnpm db:reset && pnpm db:test`
|
||||
on the real stack when Docker is available; regenerate types (`pnpm db:types`).
|
||||
|
||||
@@ -21,6 +21,19 @@ The host should publish only ports `22`, `80`, `443` to the internet. The
|
||||
container port (`8080` by default) should stay loopback-only — the host
|
||||
reverse proxy reads from it on `127.0.0.1:8080`.
|
||||
|
||||
### Reference sheet in the image (SHEET_BUNDLE)
|
||||
|
||||
The application needs an anatomical sheet to work. Until sheets are served by
|
||||
Supabase (plan Step 13) the only source is the sheet bundled at build time:
|
||||
|
||||
| Build | Sheet in the bundle |
|
||||
|---|---|
|
||||
| `docker build .` / `pnpm build` (default, CI) | none: the app shows "no anatomical sheet" and refuses to create or import a report |
|
||||
| `docker build --build-arg SHEET_BUNDLE=draft .` / `pnpm build:preview` | the curated equine DRAFT, medically unvalidated |
|
||||
|
||||
Bundling the draft is a deliberate preview decision, never the default: the
|
||||
draft content is readable by anyone who can load the application (BDR-037).
|
||||
|
||||
### Docker resource naming
|
||||
|
||||
Expected change in `.env.example` (file not editable by the assistant):
|
||||
|
||||
@@ -5,10 +5,11 @@ SVGs — click zones, build observations, export a self-contained PDF with the
|
||||
full report JSON embedded as a native PDF attachment. Re-importing that PDF
|
||||
restores the state for a follow-up.
|
||||
|
||||
Multi-species by design. MVP data set covers the **horse** (équin). Additional
|
||||
species — dog, cat, goat, cow, pig, rabbit, donkey, sheep — drop in by adding
|
||||
their SVG schematic + manifest + pathology file under `src/domain/species/`.
|
||||
See [`docs/ADDING-A-SPECIES.md`](docs/ADDING-A-SPECIES.md) for the recipe.
|
||||
Multi-species by design. The MVP ships the **horse** sheet: a canonical anatomical
|
||||
sheet document (drawing + annotations + findings catalog, `packages/domain`)
|
||||
generated and curated under `supabase/seed/anatomical-sheets/equine/`. Another
|
||||
species is another sheet document, no code change.
|
||||
See `docs/development/ANATOMICAL_SHEET_MODEL.md` §6 for how a sheet is produced.
|
||||
|
||||
Open to every praticien who wants to use it. No authentication, no backend,
|
||||
no central server in v1 — the PDF is the long-term record. Phase 2 will add
|
||||
@@ -19,20 +20,17 @@ contract.
|
||||
|
||||
## Features
|
||||
|
||||
- **Anatomy canvas** — inline SVG with clickable zones; hitbox+visible twin pattern; delegated click listener
|
||||
- **Anatomy canvas** — inline SVG drawing with markers rendered from the sheet document (hitbox + visible twin, delegated click listener)
|
||||
- **Observation builder** — group zones into clinical observations with severity and free-text notes
|
||||
- **Hierarchical findings tree** — per-zone picker with breadcrumb drill-down through the expert-authored catalog (26 zones for the horse), vet-referral badges on sensitive leaves, scope-disclaimer modal once per session
|
||||
- **Vertebra picker** — region tabs (C/T/L/S/Cd) with multi-select chip grid for precise vertebral notation
|
||||
- **Detail popups** — click a zone (e.g. head) to open a secondary SVG with finer-grained zones
|
||||
- **PDF export** — A4 portrait with rasterized anatomy SVGs (native browser `Image`/`canvas` pipeline), structured observations, and the full report JSON as a native PDF attachment
|
||||
- **Detail views** — click the head trigger to open the head view (a crop of the same drawing, or a view's own asset)
|
||||
- **PDF export** — A4 portrait with rasterized views, structured observations, and the full Report v3 JSON as a native PDF attachment; older v2 PDFs import through a generated migration map
|
||||
- **PDF re-import** — open a previously exported PDF to restore the session for a follow-up
|
||||
- **Bilingual UI** — full FR/EN interface with a one-click language switcher; default locale auto-detected from the browser, then persisted
|
||||
- **Configurable identity** — site name, brand, footer, tagline all come from env vars; nothing hardcoded
|
||||
- **Practitioner cache** — last-used practitioner block prefilled via localStorage
|
||||
- **Pathology editor** — standalone `pathology-editor.html` tool (no build step) for visually editing the species findings JSON via SVG zone selection; exports a downloadable JSON file
|
||||
- **Laterality** — left/right side selection on bilateral zones, reflected in badges and the PDF
|
||||
- **SVG anatomy editor** — in-app `/svg-editor` tool to annotate anatomy SVGs
|
||||
- **Welcome screen + editors page** — tabbed entry with a project SVG picker and an `/editors` listing
|
||||
- **Footer branding** — global footer (copyright, "Powered by ZenQuality", partner logo), on site + PDF
|
||||
|
||||
---
|
||||
@@ -101,9 +99,9 @@ For production deployment (VPS provisioning, firewall, TLS, nginx reverse proxy,
|
||||
## Documentation
|
||||
|
||||
- [CLAUDE.md](CLAUDE.md) — project conventions, stack reference, architecture overview
|
||||
- [docs/ANATOMY-SVG-CONVENTION.md](docs/ANATOMY-SVG-CONVENTION.md) — SVG data-* contract (source of truth)
|
||||
- [docs/ADDING-A-SPECIES.md](docs/ADDING-A-SPECIES.md) — guide for adding a second species post-MVP
|
||||
- [docs/PATHOLOGIES-FORMAT.md](docs/PATHOLOGIES-FORMAT.md) — findings catalog format + authoring guide
|
||||
- [docs/ANNOTATION-RENDERING.md](docs/ANNOTATION-RENDERING.md) — annotation layer contract (markers drawn from the sheet document)
|
||||
- [docs/development/ANATOMICAL_SHEET_MODEL.md](docs/development/ANATOMICAL_SHEET_MODEL.md) — canonical anatomical sheet document, curation pipeline, report migration map
|
||||
- [docs/development/STEP5_MIGRATION_ANALYSIS.md](docs/development/STEP5_MIGRATION_ANALYSIS.md) — how the application moved onto the canonical sheet (Report v3)
|
||||
- [docs/PDF-FORMAT.md](docs/PDF-FORMAT.md) — PDF page layout and attachment contract
|
||||
- [docs/development/SUPABASE.md](docs/development/SUPABASE.md) — local Supabase stack, migrations, RLS tests, generated types
|
||||
- [DEPLOY.md](DEPLOY.md) — production VPS deploy guide (Docker + nginx + TLS + hardening)
|
||||
@@ -117,25 +115,26 @@ For production deployment (VPS provisioning, firewall, TLS, nginx reverse proxy,
|
||||
```
|
||||
faunosteo/ pnpm workspace (see docs/development/WORKSPACE.md)
|
||||
├─ apps/app/ the private application (@faunosteo/app):
|
||||
├─ public/species/equine/ anatomy SVGs (Horse.svg, Horse_head.svg)
|
||||
├─ vite/sheet-bundle.ts Vite plugin bundling the reference sheet (SHEET_BUNDLE=draft|none)
|
||||
├─ src/app/ routes + ConfigProvider
|
||||
├─ src/config/ runtime env config resolution
|
||||
├─ src/domain/ Zod schemas + species registry + equine data
|
||||
├─ src/sheets/ SheetProvider (bundled implementation) + useSheet hook
|
||||
├─ src/services/ sheet index (lookups by id) + zone interaction service (pure)
|
||||
├─ src/i18n/ translation dicts (fr/en) + useT() hook
|
||||
├─ src/state/ Zustand store + locale store + localStorage cache
|
||||
├─ src/anatomy/ SVG parser + loader
|
||||
├─ src/state/ Zustand store (Report v3) + persistence adapter + locale store
|
||||
├─ src/anatomy/ drawing: sanitised asset + annotation layer → inline SVG per view
|
||||
├─ src/components/ UI primitives, canvas, observation, report
|
||||
├─ src/pdf/ export/import/attachment/fonts + renderers
|
||||
├─ src/lib/ id, dates, assert utilities
|
||||
├─ src/styles/ Tailwind v4 CSS + design tokens
|
||||
├─ tests/unit/ vitest tests (apps/app/tests, incl. characterisation suite)
|
||||
├─ packages/domain/ @faunosteo/domain: canonical anatomical sheet document (Zod) + integrity rules
|
||||
├─ tests/unit/ vitest tests on the bundled sheet (+ frozen v2 fixtures)
|
||||
├─ packages/domain/ @faunosteo/domain: canonical sheet document + report document (v3, v2 migration)
|
||||
├─ packages/anatomy/ @faunosteo/anatomy: legacy importer, curation pipeline, annotation-layer renderer
|
||||
├─ packages/supabase/ @faunosteo/supabase: typed client, generated types, PGlite SQL test harness
|
||||
├─ supabase/ CLI config, SQL migrations, local seed, pgTAP tests
|
||||
├─ supabase/ CLI config, SQL migrations, local seed (incl. the equine sheet), pgTAP tests
|
||||
├─ docker/ entrypoint.sh + nginx.conf
|
||||
├─ docs/ conventions + species guide + PDF spec
|
||||
├─ index.html SPA entry point
|
||||
└─ public/pathology-editor.html standalone pathology JSON editor (served as static file)
|
||||
├─ docs/ conventions, sheet model, PDF spec, development plan
|
||||
└─ index.html SPA entry point
|
||||
```
|
||||
|
||||
---
|
||||
@@ -146,16 +145,16 @@ v0.1.0 MVP — implementation complete.
|
||||
|
||||
- `pnpm typecheck` ✅
|
||||
- `pnpm lint` ✅
|
||||
- `pnpm test:run` ✅ — 271 tests across 39 files
|
||||
- `pnpm test:run` ✅ — 310 tests across the workspace (domain, anatomy, supabase, app)
|
||||
- `pnpm build` ✅
|
||||
|
||||
The first species data set ships with the real `Horse.svg` + `Horse_head.svg`
|
||||
anatomy sources at `public/species/equine/` and a full v2.0 findings catalog
|
||||
(26 zones, 792 nodes, 612 leaves, 41 vet-referral leaves) authored by the
|
||||
domain expert. Adding **dog, cat, goat, cow, pig, rabbit, donkey, sheep** is
|
||||
the same procedure: convention-compliant SVG + manifest + findings JSON. See
|
||||
[docs/ADDING-A-SPECIES.md](docs/ADDING-A-SPECIES.md) and
|
||||
[docs/PATHOLOGIES-FORMAT.md](docs/PATHOLOGIES-FORMAT.md).
|
||||
The first species ships as the equine anatomical sheet: the historical
|
||||
`Horse.svg`, `Horse_head.svg` and findings catalog (26 zones, 792 nodes)
|
||||
imported, then audited and curated (`supabase/seed/anatomical-sheets/equine/`,
|
||||
44 traced changes, 48 references). The application bundles that curated
|
||||
draft in development (`SHEET_BUNDLE=draft`); it is not medically validated and
|
||||
a production build carries no sheet unless asked. Another species is another
|
||||
sheet document produced the same way.
|
||||
|
||||
Manual QA checklist: `.claude/audits/MVP-QA.md` — walk it through `pnpm dev`
|
||||
before delivery.
|
||||
|
||||
@@ -0,0 +1,70 @@
|
||||
# Annotation rendering contract
|
||||
|
||||
**Status**: source of truth since Step 5. Replaces `ANATOMY-SVG-CONVENTION.md`
|
||||
(the legacy `data-anno-*` attributes authored inside the SVG files).
|
||||
|
||||
The drawing of a sheet is a plain SVG asset with no annotation element. The
|
||||
application draws the markers itself from the canonical document
|
||||
(`docs/development/ANATOMICAL_SHEET_MODEL.md`): `renderAnnotationLayer` in
|
||||
`packages/anatomy/src/render/layer.ts` turns the annotations of one view into
|
||||
a pure element tree, materialised in the browser (`apps/app/src/anatomy/drawing.ts`)
|
||||
or serialised by the pipeline (`draft/review/app-<view>.svg`).
|
||||
|
||||
## Elements emitted per annotation
|
||||
|
||||
| Kind | Geometry | Elements |
|
||||
|---|---|---|
|
||||
| `point` | circle | transparent hitbox (`r` of the geometry, `pointer-events: all`) + visible twin (`r − 12`, category or annotation colour, `fill-opacity` 0.65 on the main view / 0.5 on a detail view, black 1.5 stroke, `pointer-events: none`) |
|
||||
| `zone` | polygon or path | one filled shape (`fill-opacity` 0.3, stroke 2) |
|
||||
| `detail_trigger` | polygon or path | one dashed outline (`fill-opacity` 0.06, stroke 2, dash `8,4`, class `detail-zone`) |
|
||||
|
||||
Annotations without geometry draw nothing. Each element carries a `<title>`
|
||||
"FR / EN" (native tooltip) and the attributes below.
|
||||
|
||||
## Attributes (the application's read contract)
|
||||
|
||||
| Attribute | Value |
|
||||
|---|---|
|
||||
| `data-anno-id` | annotation id (stable, the report's `annotationId`) |
|
||||
| `data-anno-kind` | `point`, `zone` or `detail_trigger` |
|
||||
| `data-anno-name-fr`, `data-anno-name-en` | annotation name; for a trigger, the opened view's name |
|
||||
| `data-anno-lateral` | `unpaired`, `bilateral`, `left` or `right` |
|
||||
| `data-anno-zone` | `finding_zone_id` when the annotation links a finding zone |
|
||||
| `data-anno-region` | `vertebral_region_code` when the annotation opens the vertebra picker |
|
||||
| `data-anno-opens-view` | `opens_view_id` of a trigger |
|
||||
| `data-state` | `current` when the annotation belongs to the active observation |
|
||||
|
||||
Click handling walks up to the nearest `[data-anno-id]` and hands
|
||||
`(annotationId, viewId)` to the interaction service
|
||||
(`apps/app/src/services/zoneInteraction.ts`). Behaviour never depends on a
|
||||
label, an element id or a class.
|
||||
|
||||
## Colours
|
||||
|
||||
`categories[].color` gives the colour of every annotation of a category;
|
||||
`annotations[].color` overrides it (the head view keeps the shades the legacy
|
||||
file used for the TMJ, the SBS and the hyoid). Both are document data, written
|
||||
by the curation changeset, never by the renderer. Without either, the renderer
|
||||
falls back to `#888888`.
|
||||
|
||||
## Views
|
||||
|
||||
A view renders on its `view_box` when set (the head view is the crop
|
||||
`60 100 500 380` of the main drawing), else on the asset's own `viewBox`. A
|
||||
detail view with its own `svg_asset_id` renders that asset: independent
|
||||
drawings per view stay possible.
|
||||
|
||||
## Styling and states
|
||||
|
||||
The application stylesheet keeps the legacy rules: `.svg-canvas [data-state='current']`
|
||||
fills the selected markers with the accent colour at 0.85, every `[data-anno-id]`
|
||||
shows a pointer cursor and brightens on hover. The PDF export reuses the same
|
||||
layer, then recolours the selected markers and hides the others before
|
||||
rasterising (`apps/app/src/pdf/render/observationPage.ts`).
|
||||
|
||||
## Checking the look
|
||||
|
||||
`pnpm import:equine` writes `draft/review/app-main.svg` and `app-head.svg`.
|
||||
Rasterise them with ImageMagick next to the legacy files (strip the `<title>`
|
||||
elements first, ImageMagick's own SVG renderer drops shapes that carry one) to
|
||||
compare markers and framing before and after a change.
|
||||
@@ -1,3 +1,7 @@
|
||||
**Status (2026-10-10)**: legacy format. `pathologies.json` is now an input of the
|
||||
importer only (`supabase/seed/anatomical-sheets/equine/legacy-sources/`); the
|
||||
application reads the canonical sheet document (`docs/development/ANATOMICAL_SHEET_MODEL.md`).
|
||||
|
||||
# Pathologies / Findings JSON Format
|
||||
|
||||
Each species ships a `pathologies.json` next to its `index.ts` manifest.
|
||||
|
||||
@@ -10,3 +10,20 @@ Will cover:
|
||||
- JSON attachment spec (EmbeddedFiles, afRelationship:Data)
|
||||
- Font handling (pdf-lib StandardFonts Helvetica/Times-Roman, WinAnsi; TTF Inter/Fraunces planned, not shipped)
|
||||
- Import/re-import roundtrip contract
|
||||
|
||||
## Attachment versions (Step 5)
|
||||
|
||||
The attachment `osteo-report.json` carries the Report **v3** document
|
||||
(`packages/domain/src/report/v3.ts`): zones by `(annotationId, viewId)`,
|
||||
findings by `(findingZoneId, path)` with label snapshots, severity codes,
|
||||
the `sheet` reference (sheet id, version id, sha256 of the document) and the
|
||||
reserved `localAnnotations`.
|
||||
|
||||
Import (`importReportFromPdf(bytes, migrationMap)`) accepts:
|
||||
|
||||
- v3: read as is;
|
||||
- v2 (PDFs produced by the application before Step 5, the practitioner's
|
||||
archive): migrated through the sheet's `report-migration-map.json`; a zone
|
||||
or finding the map cannot place is kept with its snapshots and flagged
|
||||
`unresolved: true`; the outcome reports `migrated` and the unresolved counts;
|
||||
- any other version: `ImportError('incompatible_version', foundVersion)`.
|
||||
@@ -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),
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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
|
||||
|
||||
+1
-1
@@ -9,7 +9,7 @@ Planned packages and the step that creates each one:
|
||||
| Package | Content | Created at |
|
||||
|---|---|---|
|
||||
| `@faunosteo/domain` | Zod schemas: anatomical sheet document + integrity rules (**created**, Step 4); report document, entitlement capabilities later | Step 4 (sheet model) |
|
||||
| `@faunosteo/anatomy` | legacy importer (**created**, Step 4b), curation pipeline: changeset → working draft (**created**, Step 4c); renderer helpers, spine logic later | Step 4b (importer) |
|
||||
| `@faunosteo/anatomy` | legacy importer (**created**, Step 4b), curation pipeline: changeset → working draft + report migration map (**created**, Steps 4c/5), pure annotation-layer renderer `@faunosteo/anatomy/render` shared with the app (**created**, Step 5) | Step 4b (importer) |
|
||||
| `@faunosteo/pdf` | export / import / attachment, render helpers | Step 6 (PDF v3) |
|
||||
| `@faunosteo/i18n` | FR/EN dictionaries (no React) + `useT` | first second consumer (public-web or worker) |
|
||||
| `@faunosteo/supabase` | browser client factory, generated database types, PGlite harness running the pgTAP suite, sheet publish gate | **created**, Step 3 |
|
||||
|
||||
@@ -127,10 +127,10 @@ describe('annotation layer on the real draft', () => {
|
||||
'<svg xmlns="http://www.w3.org/2000/svg"/>',
|
||||
'image/svg+xml',
|
||||
)
|
||||
const element = createLayerElement(
|
||||
doc as never,
|
||||
layer,
|
||||
) as unknown as Element
|
||||
const element = createLayerElement(doc as never, layer) as unknown as {
|
||||
getAttribute(name: string): string | null
|
||||
getElementsByTagName(tag: string): { length: number }
|
||||
}
|
||||
expect(element.getAttribute('data-layer')).toBe('annotations')
|
||||
expect(element.getElementsByTagName('circle')).toHaveLength(18)
|
||||
const text = serializeLayer(layer)
|
||||
|
||||
Reference in new issue
Block a user