chore(memory): TODO + journal + BDR-009..011 + LRN-011..012

Mark B0/B1/B2/B5 done on TODO. Journal 2026-05-20 entry with the three
commit SHAs and a per-phase recap. Three new design decisions captured:
JSON snake_case kept in TS (BDR-009), snapshot labels at selection time
(BDR-010), hard-fail v1 PDF with FR-language message (BDR-011). Two new
learnings: Zod recursive schemas via z.lazy + explicit ZodType<T>
(LRN-011), once-per-session UX modal via sessionStorage flag (LRN-012).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Bastien ChanotandClaude Opus 4.7 committed 2026-05-20 03:51:36 +02:00
1 parent b67f4cd82b
commit b7b094535e
4 files changed
+79 -65

No files matched your search

+25
View File
@@ -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.
+12
View File
@@ -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<FindingNode>), 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<T>), 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).
+14
View File
@@ -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<T>
Recursive shapes (FindingNode with optional children: FindingNode[]) need TS interface declared first, then `const FindingNodeSchema: z.ZodType<FindingNode> = z.lazy(() => z.object({...}))`. Without the explicit ZodType<T> 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<U[]> 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.
+28 -65
View File
@@ -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<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`
### 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
---