diff --git a/.claude/memory/decisions.md b/.claude/memory/decisions.md index db367645..4d749b60 100644 --- a/.claude/memory/decisions.md +++ b/.claude/memory/decisions.md @@ -64,3 +64,28 @@ Status: closed — deviation accepted. Each PDF page leads with bold-uppercase accent eyebrow (size 9), Times 22 title, 2pt × 48pt accent rule under title. Section labels follow same eyebrow style (uppercase bold accent) above their values. Observation severity rendered as filled color-coded pill (sage / amber / red) next to the obs number. Alts: plain text titles only — rejected (overlapped header rule + read unstyled). Status: closed. + +--- + +## BDR-009 | 2026-05-20 | Findings JSON keeps snake_case in TS, observation snapshot uses camelCase + +JSON catalog fields (name_fr/name_en/description_fr/requires_vet_referral/...) stay snake_case in TS types/Zod schema — no transform layer. Domain-expert authored, reads natural in JSON, zero remap cost. Observation Finding snapshot uses camelCase (labelFrSnapshot/labelEnSnapshot/requiresVetReferral) per app convention. +Alt: Zod transform to camelCase everywhere — rejected (extra layer, hides JSON shape, no real upside for a static catalog). +Status: closed. + +--- + +## BDR-010 | 2026-05-20 | Observation findings snapshot labels at selection time + +Finding stores labelFrSnapshot + labelEnSnapshot copied from leaf at click time. Exported reports remain readable years later even if catalog renames/restructures leaves. Path[] still carried for future re-link/migration. +Alt: lookup labels on render via path — rejected (breaks already-exported PDFs if catalog edits). +Status: closed. + +--- + +## BDR-011 | 2026-05-20 | v1 PDF import — hard-fail with version-specific FR message + +importReportFromPdf detects `data.version !== 2` BEFORE strict Zod parse, throws IncompatibleReportVersionError, wrapped into ImportError with explicit "v{n}, incompatible avec v2, réexportez..." message. No retro-compat shim (no prod PDFs in the wild). +Alt: silent generic ImportError — rejected (user can't tell why import failed). +Alt: v1→v2 migration adapter — rejected (no install base to justify cost). +Status: closed. diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md index 9af12e2b..66cd9c62 100644 --- a/.claude/memory/journal.md +++ b/.claude/memory/journal.md @@ -35,3 +35,15 @@ feat(editor): home-nav (back btn + clickable Brand link to "/") + "Modifier les - hotfix(editor): zone-highlight scoped to active obs only (collapsed obs no longer leave faint 'linked'/'multi' tints). AnatomyCanvas re-paints highlights after async SVG mount so DetailModal popup zones color correctly. NewReportRoute header harmonized with editor — back btn + clickable Brand left-aligned. 3 files (hotfix cap +1, accepted). LRN-010 captured. - domain pivot decided: flat Pathology[] → hierarchical findings tree per zone, path+snapshot serialization, FR/EN bilingual site+PDF. ReportSchema bumps v1→v2 (no retro-compat, no prod PDFs). Sample 3-zone JSON v1.1 dropped at src/domain/species/equine/pathologies.json — inert (loader not migrated). TODO rewritten as B0..B5 + C ship gate, ~23h dev. - NEXT SESSION: run /ship-feature on B0 (findings Zod schema + JSON loader) + B1 (ReportSchema v2 + observation.findings) + B2 (FindingsTreePicker replacing flat PathologyPicker). I18N (B3) deferred to separate feature. Reconcile JSON species.id (currently "equin") vs registry species.id ("equine") before parse — pick one. + +--- + +## 2026-05-20 + +Bundled B0+B1+B2 shipped on feat/findings-tree-v2. 3 atomic commits. +- B0 (f80e161): findings.ts Zod schema (recursive z.lazy + explicit ZodType), SpeciesFindingsSchema.parse(JSON) at boot, manifest swaps pathologies→findings, JSON species.id "equin"→"equine", new species.equineFindings test (5). +- B1 (d08d773): ObservationSchema.findings + freeTextFindings, ReportSchema.version 1→2, store emptyObservation+initReport updated, PDF import detects v1 via IncompatibleReportVersionError + ImportError wraps message (FR), pathology.ts schema + test deleted. +- B2 (b67f4cd): FindingsTreePicker (breadcrumb, drill, leaf toggle, retour, vet-referral ⚠, description_fr), ObservationCard renders one picker per zone with catalog, FreeTextPathologyInput renamed FreeTextFindingInput, scope_disclaimer modal once/session via osteo:disclaimer-shown sessionStorage flag, PDF observationPage renders findings via labelFrSnapshot with ⚠ prefix on vet-referral. B5 folded in: Toast + ZoneTooltip stubs deleted, CLAUDE.md folder map refreshed. +- 107/107 tests green, lint 0 warn, typecheck clean, vite build OK (882KB main + 15KB lazy pathologies chunk). +- BDR-009 (snake_case JSON fields preserved in TS), LRN-011 (Zod recursive via z.lazy + explicit ZodType), LRN-012 (sessionStorage flag pattern for once-per-session UX modals) to capitalize. +- NEXT: push branch + PR. After merge: B3 (i18n FR/EN) + B4 (PDF observationPage polish for vet-referral) + C (full horse.json + QA + deploy). diff --git a/.claude/memory/learnings.md b/.claude/memory/learnings.md index fdb550d4..a182dc46 100644 --- a/.claude/memory/learnings.md +++ b/.claude/memory/learnings.md @@ -80,3 +80,17 @@ Apply: any pdf-lib page where image count is data-driven and text must remain vi Symptom: highlight effect (querySelectorAll + setAttribute) silently no-ops when sibling effect appends DOM async via loadSvg().then(append). First render: mutate-effect runs against empty container, then DOM arrives, then nothing re-paints because deps didn't change. Symptom is intermittent ("sometimes highlighted, sometimes not") — actually depends on which effect resolves first on a given mount. Fix pattern: hold a `loadedSrc` state, set it to null at src-change, set it to src right after appendChild, and depend the mutate-effect on [data, loadedSrc, src] with guard `if (loadedSrc !== src) return`. Now the mutate-effect re-runs both on data change AND when DOM finishes mounting. Apply: any React component that mounts external DOM async and applies attribute/style mutations in a separate effect. Includes inline SVG injection, MapLibre overlays, Lottie players. Never rely on effect ordering across an async boundary. + +--- + +## LRN-011 | 2026-05-20 | Zod recursive schema via z.lazy + explicit ZodType + +Recursive shapes (FindingNode with optional children: FindingNode[]) need TS interface declared first, then `const FindingNodeSchema: z.ZodType = z.lazy(() => z.object({...}))`. Without the explicit ZodType annotation, TS infers `any` for the recursive arm and the entire downstream type chain collapses. Without z.lazy, the schema references itself before initialization → runtime ReferenceError. +Apply: any tree/AST-style schema in Zod 3.x. Declare interface first, type the schema explicitly, wrap recursive shape in z.lazy. Same trick works for ZodType when the recursion is via children: U[]. + +--- + +## LRN-012 | 2026-05-20 | Once-per-session UX modal via sessionStorage flag + +Pattern: state `disclaimer: string | null`, useEffect on the data dep that reads `sessionStorage.getItem(FLAG)`; if absent, set state to the message. Acknowledge handler writes the flag and clears state. Survives reloads within tab, resets on new tab. Cheaper than persisting per-user (no backend) and respects practitioner intent — they see the legal scope reminder once per work session. +Apply: any single-praticien tool needing one-shot acknowledgment per session (legal disclaimers, version-change notices, GDPR banners scoped to a session). Use a stable string key prefixed with `osteo:` to avoid collision. diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index 10b907ab..8c817af9 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -1,13 +1,13 @@ # TODO — Osteo Report MVP -## Status (2026-05-19): editor flow + PDF roundtrip working — V1 pivots toward hierarchical findings + i18n +## Status (2026-05-20): findings tree refactor landed (B0+B1+B2) — i18n + full horse catalog next -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. +Domain pivot bundle (B0 schema, B1 report v2, B2 UI/PDF) shipped on +`feat/findings-tree-v2`. Editor now consumes the hierarchical +`SpeciesFindings` tree; PDF roundtrip green; v1 legacy reports hard-fail +with a French-language message. -All 100 tests green pre-refactor. +107/107 tests green, lint 0, typecheck clean, vite build OK. --- @@ -37,66 +37,29 @@ All 100 tests green pre-refactor. ## Phase B — V1 REFACTOR (hierarchical findings + i18n) -### B0. Domain model — Findings tree (BLOCKING — foundational) +### B0. Domain model — Findings tree (DONE 2026-05-20) -**Decision**: replace flat `Pathology[]` with `FindingsTree` per zone, path-based -serialization in observations. Bump `ReportSchema.version` 1 → 2. No retro-compat -(no production PDFs). +- [x] **Schema**: `src/domain/schema/findings.ts` — `FindingNodeSchema` (recursive via `z.lazy`), `ZoneFindingsSchema`, `SpeciesFindingsSchema`, `SourceRefSchema` +- [x] **Loader**: `src/domain/species/equine/pathologies.ts` parses the JSON via `SpeciesFindingsSchema.parse(data)` at boot (fail-fast) +- [x] **Species manifest**: `findings: FindingsLoader` replaces `pathologies` in `SpeciesManifest` +- [x] **JSON fix**: `species.id` set to `"equine"` to match registry +- [x] **Tests**: `tests/unit/species.equineFindings.test.ts` (5 cases) replaces deleted `species.equinePathologies.test.ts` -- [ ] **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 }` - - 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` +### B1. Report schema v2 — observation findings (DONE 2026-05-20) -### B1. Report schema v2 — observation findings +- [x] `ObservationSchema` carries `findings: Finding[]` + `freeTextFindings: string[]`; old `pathologyIds`/`freeTextPathologies` removed +- [x] `ReportSchema.version` literal bumped `1` → `2` +- [x] Store `emptyObservation` + `initReport` updated to the v2 shape +- [x] PDF import surfaces a distinct French-language `IncompatibleReportVersionError` message on v1 attachments (detected before Zod parse) +- [x] Schema + store + PDF tests updated; `pathology.ts` schema + test deleted -- [ ] **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 +### B2. UI — Findings tree picker (DONE 2026-05-20) -### 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 +- [x] `src/components/observation/FindingsTreePicker.tsx` (breadcrumb, drill-down, leaf toggle, retour button, vet-referral ⚠ badge, description_fr surfacing) +- [x] `scope_disclaimer` modal shown once per session via `osteo:disclaimer-shown` sessionStorage flag +- [x] `ObservationCard` migrated — one picker per zone with a catalog entry, single `FreeTextFindingInput` below +- [x] `PathologyPicker` + `FreeTextPathologyInput` + their tests deleted; `FreeTextFindingInput` renamed equivalent kept +- [x] `tests/unit/components.FindingsTreePicker.test.tsx` covers navigation, leaf select, vet-referral flag, retour, deselect ### B3. i18n FR/EN — site + PDF @@ -120,11 +83,11 @@ serialization in observations. Bump `ReportSchema.version` 1 → 2. No retro-com - [ ] `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 +### B5. Stub cleanup (DONE 2026-05-20) -- [ ] `ZoneTooltip.tsx` — delete (unused) -- [ ] `Toast.tsx` — implement OR delete (decide: notifications for PDF export/import?) -- [ ] `ObservationEditor.tsx` — remove reference from CLAUDE.md folder map +- [x] `ZoneTooltip.tsx` deleted (unused stub) +- [x] `Toast.tsx` deleted (unused stub — re-introduce later if notifications needed) +- [x] CLAUDE.md folder map updated — `ObservationEditor`/`Toast`/`ZoneTooltip` removed, `FindingsTreePicker`/`FreeTextFindingInput`/`findings.ts` added ---