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
@@ -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`).
|
||||
|
||||
Reference in new issue
Block a user