chore(domain): drop equine findings JSON v1.1 + refactor plan

Adds the schema-v1.1 hierarchical findings JSON authored by the
domain expert at src/domain/species/equine/pathologies.json
(3-zone sample: sphenoid/ssb/atm — placeholder before full-body
authoring).

JSON is inert: not yet imported by the loader (still exports the
empty Pathology[]), so build and tests stay green.

TODO rewritten to sequence the V1 refactor:
- B0 findings schema + JSON loader with Zod parse at boot
- B1 ReportSchema v2 (observation.findings = path + snapshot)
- B2 FindingsTreePicker replacing flat PathologyPicker
- B3 i18n FR/EN site + PDF (locale store, dict, switcher)
- B4 PDF observationPage rendering findings
- B5 stub cleanup
- C  full horse.json authoring + QA + docs + deploy

Known fixup: JSON species.id is "horse" but registry uses
"equine"; align JSON to "equine" at integration time.

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Bastien ChanotandClaude committed 2026-05-19 07:44:10 +02:00
1 parent 50ad18f4ed
commit a3afdcb763
2 files changed
+828 -73

No files matched your search

+142 -73
View File
@@ -1,13 +1,13 @@
# TODO — Osteo Report MVP
## Status (2026-05-19): editor flow + PDF roundtrip fully working — closing V1
## Status (2026-05-19): editor flow + PDF roundtrip working — V1 pivots toward hierarchical findings + i18n
Last 24h: PDF rendering polished (eyebrow/title/severity pill, 2-col SVG grid,
text-area reservation), editor nav (back btn + clickable Brand) + in-place
identity edit dialog, zone-highlight scoped to active obs, detail-popup repaint
on async SVG mount, headers harmonized.
Major scope decision: pathology model rewritten from flat `Pathology[]` to
**hierarchical findings tree per zone**, with FR/EN bilingual content for site
and PDF. Schema v1.1 JSON authored by domain expert is in place. Refactor
required before MVP can ship.
All 100 tests green, lint 0, typecheck clean.
All 100 tests green pre-refactor.
---
@@ -21,82 +21,135 @@ All 100 tests green, lint 0, typecheck clean.
- [x] sessionStorage draft mirror + localStorage practitioner cache
- [x] UI primitives: Button, Card, Dialog, Input, Label, Select, Textarea, Badge, Chip
- [x] Canvas: AnatomyCanvas (data-state highlighting, async-mount safe), DetailModal
- [x] Observation chain: ObservationList, ObservationCard, PathologyPicker,
VertebraPicker (region tabs + chips, preselect region from label),
SeveritySelector, FreeTextPathologyInput
- [x] Report forms: PractitionerForm, AnimalForm, ConclusionPanel,
NextAppointmentPicker, ReportHeader (with edit-infos dialog + home nav)
- [x] Routes: HomeRoute (CTAs + session draft card), NewReportRoute,
EditorRoute (split layout + dialog), NotFoundRoute
- [x] PDF pipeline: fonts (Inter + Fraunces TTF), header, observationPage
(2-col SVG grid, eyebrow/title/severity pill, text-area reservation),
conclusionPage, attachment.ts (embed + extract JSON), export, import
- [x] Docker: Dockerfile multi-stage, docker-compose, entrypoint.sh
(window.__APP_CONFIG__ runtime injection), nginx.conf SPA fallback
- [x] Brand identity via env vars end-to-end (config/env.ts → ConfigProvider)
- [x] Tests: 100/100 pass (schemas, store, anatomy parser, PDF roundtrip,
canvas, pickers, components)
- [x] Observation chain: ObservationList, ObservationCard, PathologyPicker (flat — TO REPLACE),
VertebraPicker, SeveritySelector, FreeTextPathologyInput
- [x] Report forms + edit-infos dialog + home nav
- [x] Routes: Home, NewReport, Editor (split layout + dialog), NotFound
- [x] PDF pipeline: fonts, header, observationPage (2-col SVG grid),
conclusionPage, attachment.ts, export, import
- [x] Docker: Dockerfile, compose, entrypoint.sh runtime env, nginx SPA fallback
- [x] Brand identity via env (ConfigProvider)
- [x] Tests: 100/100 pass
- [x] **Pathology JSON sample dropped** at `src/domain/species/equine/pathologies.json`
(schema v1.1, 3 zones: sphenoid/ssb/atm — placeholder before full-body)
---
## Phase B — REMAINING for V1/MVP ship
## Phase B — V1 REFACTOR (hierarchical findings + i18n)
### B1. Equine pathology database (BLOCKING)
- [ ] `src/domain/species/equine/pathologies.ts` — currently empty (`[]`)
- [ ] Author 40-60 entries with source citations (manual / journal / database / web)
- [ ] Each entry: PathologySchema.parse() + ≥1 source + boneIds (or [] = all zones)
- [ ] Client review of batch before commit
- [ ] Test: `species.equinePathologies.test.ts` already exists — will validate count + source presence once filled
### B0. Domain model — Findings tree (BLOCKING — foundational)
### B2. Stub cleanup (small)
- [ ] `src/components/canvas/ZoneTooltip.tsx` — unused stub. Decide: implement (hover tooltip listing observations owning the bone) or delete
- [ ] `src/components/ui/Toast.tsx` — unused stub. Decide: implement (success/error notifications for PDF export/import) or delete
- [ ] `src/components/observation/ObservationEditor.tsx` — referenced in CLAUDE.md folder map but file does not exist (replaced by inline edit in ObservationCard). Remove from CLAUDE.md structure list
**Decision**: replace flat `Pathology[]` with `FindingsTree` per zone, path-based
serialization in observations. Bump `ReportSchema.version` 1 → 2. No retro-compat
(no production PDFs).
### B3. PDF QA pass (manual)
- [ ] Full flow: HomeRoute → NewReport → fill all fields → editor → 3+ observations
with main + detail SVGs + vertebrae + severity + comment → export PDF
- [ ] Open PDF in Acrobat (or qpdf) → verify:
- Fonts embedded (no system-font substitution)
- JSON attachment present (`pdfdetach -list`)
- SVG rasterization sharp at 1200px target
- Multi-SVG observation: 2-col grid renders, no overflow, text sections visible
- [ ] Re-import same PDF → state hydrated identically (deep equal check)
- [ ] Test in Firefox + Chrome + Safari (DOMParser + canvas behavior)
- [ ] **Schema**: `src/domain/schema/findings.ts` (new)
- `FindingNodeSchema`: `{ id, name_fr, name_en, description_fr?, description_en?, requires_vet_referral?, sources?, children? }`
- `ZoneSchema`: `{ id, name_fr, name_en, categories: FindingNode[] }`
- `SpeciesFindingsSchema`: `{ schema_version, scope_disclaimer, species, zones: Record<string, Zone> }`
- Recursive Zod (`z.lazy`) for children
- [ ] **Loader**: rewrite `src/domain/species/equine/pathologies.ts`
- `import data from './pathologies.json'`
- `SpeciesFindingsSchema.parse(data)` at boot → fail-fast on bad JSON
- Export both `default` (parsed object) AND a backward-compat empty `Pathology[]`
until callers migrated, then drop the legacy export
- [ ] **Species manifest** (`types.ts`): replace `pathologies: PathologiesLoader`
with `findings: () => Promise<{ default: SpeciesFindings }>`
- [ ] **Fix JSON**: change `species.id` from `"horse"` → `"equine"` to match registry
- [ ] **Tests**: `tests/unit/species.equineFindings.test.ts`
- Parse succeeds with provided JSON
- Every leaf has `name_fr`+`name_en`
- `scope_disclaimer` non-empty
- At least 1 zone with at least 1 category with at least 1 leaf
- Delete old `species.equinePathologies.test.ts`
### B4. Docker deploy validation
- [ ] `docker build -t osteo-report .` succeeds with current pnpm-lock.yaml
- [ ] `docker compose up --build` boots → http://localhost:8080 serves app
- [ ] env vars (APP_SITE_NAME, APP_BRAND_NAME, APP_FOOTER_NAME, APP_TAGLINE)
reflected in browser via entrypoint.sh-injected env.js
- [ ] nginx PORT envsubst verified (try PORT=9000)
- [ ] SPA deep-link fallback works (refresh on /editor doesn't 404)
### B1. Report schema v2 — observation findings
### B5. Documentation final pass
- [ ] README.md — install, dev, build, Docker, env vars, license
- [ ] docs/ANATOMY-SVG-CONVENTION.md — already exists, verify accurate post-LRN-004
- [ ] docs/ADDING-A-SPECIES.md — verify steps still match registry shape
- [ ] docs/PDF-FORMAT.md — describe attachment schema + version contract
- [ ] CHANGELOG.md — create with V1 entry summarizing scope
- [ ] **Schema**: `src/domain/schema/observation.ts`
- Replace `pathologyIds: string[]` + `freeTextPathologies: string[]` with:
```
findings: Array<{
zoneId: string
path: string[] // ['category','sub','leaf']
labelFrSnapshot: string
labelEnSnapshot: string
requiresVetReferral?: boolean
}>
freeTextFindings: string[]
```
- [ ] **Schema**: `src/domain/schema/report.ts` — bump `version` literal `1` → `2`
- [ ] **Store**: rewrite observation update helpers, drop pathology-specific actions
- [ ] **PDF import**: hard-fail on v1 with friendly message (no v1 PDFs in prod)
- [ ] **Tests**: schema tests for v2 shape
### B6. Production deploy (Scaleway VPS)
- [ ] DNS + TLS (Caddy or nginx + Let's Encrypt)
- [ ] CI: GitHub Actions → build image → push to registry → SSH deploy
- [ ] Backup: VPS snapshot + image registry retention
### B2. UI — Findings tree picker (replaces PathologyPicker)
- [ ] **New component**: `src/components/observation/FindingsTreePicker.tsx`
- Receives `zoneId`, `tree: Zone`, `selected: Finding[]`, `onChange`
- Breadcrumb (`Zone > Category > Sub > ...`)
- Click intermediate node → drill into children
- Click leaf → toggle selection
- "Back" button to climb breadcrumb
- Show `description_fr/en` (selected via current locale) when present
- ⚠️ icon badge when `requires_vet_referral` true
- [ ] **Disclaimer**: show `scope_disclaimer` once per session (e.g. in editor or NewReport)
- Track shown-this-session via sessionStorage flag
- [ ] **Migrate ObservationCard**: replace PathologyPicker render with FindingsTreePicker
- [ ] **Delete**: old `PathologyPicker.tsx` + its test + flat schema field cleanup
- [ ] **Tests**: tree navigation, leaf selection, breadcrumb, vet-referral flag
### B3. i18n FR/EN — site + PDF
- [ ] **Locale state**: `src/state/localeStore.ts` Zustand: `'fr' | 'en'`,
persisted in localStorage `osteo:locale`
- [ ] **i18n strings**: `src/i18n/{fr,en}.ts` — UI strings dictionary
- Migrate hardcoded French labels in components (buttons, headers, placeholders, toasts)
- Helper hook `useT()` returning `(key: string) => string`
- [ ] **Language switcher**: small FR/EN toggle in ReportHeader (next to Brand)
- [ ] **Findings rendering**: components pick `name_fr`/`name_en` based on current locale
- [ ] **PDF render**: `exportReportToPdf(report, { locale })` parameter
- All static PDF labels (eyebrow, section names) read from i18n dict
- Findings rendered via `labelFrSnapshot`/`labelEnSnapshot` depending on locale at export
- Date formatting locale-aware (`formatDateFr` → `formatDate(date, locale)`)
- [ ] **Tests**: locale switch updates labels; PDF roundtrip preserves locale snapshot
### B4. PDF observationPage updates
- [ ] Render `findings` instead of `pathologyIds` (list joined `·`)
- [ ] Show vet-referral icon next to flagged findings
- [ ] `scope_disclaimer` footer on each obs page or first page only — decide
- [ ] Update `LRN-009`-style layout still applies (text-area reservation)
### B5. Stub cleanup
- [ ] `ZoneTooltip.tsx` — delete (unused)
- [ ] `Toast.tsx` — implement OR delete (decide: notifications for PDF export/import?)
- [ ] `ObservationEditor.tsx` — remove reference from CLAUDE.md folder map
---
## Phase C — POST-V1 (not in MVP scope)
## Phase C — V1 SHIP gate
Captured here so they're not lost; do NOT pull into V1 without explicit decision.
- [ ] Author full `horse.json` (replacing 3-zone placeholder with all corps SVG zones)
- [ ] PDF QA manual pass: full flow → export → re-import roundtrip
- Fonts embed, JSON attached, multi-SVG grid OK, locale FR + EN exports
- [ ] Docker build + compose up smoke test
- [ ] env-var brand identity verified
- [ ] README finalize (install, dev, Docker, env vars, locale, MIT)
- [ ] CHANGELOG v1.0.0 entry
- [ ] docs/PATHOLOGIES-FORMAT.md — schema doc + authoring guide for adding species
- [ ] Scaleway VPS deploy (TLS + CI build/push/deploy)
- Mobile delivery: Capacitor wrap (iOS + Android) — pdf-lib + canvg compatible,
Filesystem plugin for download, HashRouter required. See conversation 2026-05-19.
- User accounts + cloud sync (Supabase or self-host Postgres + JWT auth).
- Multi-praticien (move localStorage practitioner cache into server profile).
- Appointment booking + reminders (push notifications via FCM/APNs).
- Additional species (canine, bovine, feline) — registry already polymorphic.
- Pathology DB expansion + community contributions.
---
## Phase D — POST-V1 (not in MVP scope)
- Capacitor wrap (iOS + Android)
- Accounts + cloud sync (Supabase or self-host)
- Multi-praticien (move localStorage cache to server profile)
- RDV booking + push reminders
- Other species (dog, cat, cow, goat, pig, chicken JSONs)
- Pathology DB community contributions
---
@@ -104,9 +157,25 @@ Captured here so they're not lost; do NOT pull into V1 without explicit decision
- BDR-001..BDR-008 — decisions registry
- LRN-001..LRN-010 — learnings registry
- BLK-001..BLK-004 — blockers registry (all resolved)
- BLK-001..BLK-004 — blockers (all resolved)
Latest learnings to apply when implementing remaining items:
- LRN-009: pdf-lib variable-image layout (pre-rasterize → reserve → grid)
- LRN-010: gate DOM-mutate effect on async-mount loaded state
- LRN-006: strip authoring annotations before rasterizing for print
Apply when implementing B-phase:
- LRN-004 (data-anno-special opaque to parser) — zone IDs in JSON must match SVG `data-anno-id`
- LRN-009 (pre-rasterize → reserve → grid) — keep applied in PDF observationPage
- LRN-010 (gate DOM-mutate on async-mount) — relevant for any new SVG-mutating effect
---
## Estimated effort
| Phase | Hours |
|---|---|
| B0. Findings schema + loader + tests | 3 |
| B1. ReportSchema v2 + store + PDF import | 3 |
| B2. FindingsTreePicker + disclaimer + integration | 6 |
| B3. i18n FR/EN site + PDF | 5 |
| B4. PDF observationPage update | 2 |
| B5. Stub cleanup | 0.5 |
| C. Full horse.json authoring (user) | external |
| C. QA + docs + deploy | 4 |
| **Total dev** | **~23h** |