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. 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). Alts: plain text titles only — rejected (overlapped header rule + read unstyled).
Status: closed. 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. - 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. - 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. - 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. 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. 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. 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 # 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 Domain pivot bundle (B0 schema, B1 report v2, B2 UI/PDF) shipped on
**hierarchical findings tree per zone**, with FR/EN bilingual content for site `feat/findings-tree-v2`. Editor now consumes the hierarchical
and PDF. Schema v1.1 JSON authored by domain expert is in place. Refactor `SpeciesFindings` tree; PDF roundtrip green; v1 legacy reports hard-fail
required before MVP can ship. 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) ## 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 - [x] **Schema**: `src/domain/schema/findings.ts` — `FindingNodeSchema` (recursive via `z.lazy`), `ZoneFindingsSchema`, `SpeciesFindingsSchema`, `SourceRefSchema`
serialization in observations. Bump `ReportSchema.version` 1 → 2. No retro-compat - [x] **Loader**: `src/domain/species/equine/pathologies.ts` parses the JSON via `SpeciesFindingsSchema.parse(data)` at boot (fail-fast)
(no production PDFs). - [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) ### B1. Report schema v2 — observation findings (DONE 2026-05-20)
- `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 - [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` ### B2. UI — Findings tree picker (DONE 2026-05-20)
- 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 (replaces PathologyPicker) - [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
- [ ] **New component**: `src/components/observation/FindingsTreePicker.tsx` - [x] `ObservationCard` migrated — one picker per zone with a catalog entry, single `FreeTextFindingInput` below
- Receives `zoneId`, `tree: Zone`, `selected: Finding[]`, `onChange` - [x] `PathologyPicker` + `FreeTextPathologyInput` + their tests deleted; `FreeTextFindingInput` renamed equivalent kept
- Breadcrumb (`Zone > Category > Sub > ...`) - [x] `tests/unit/components.FindingsTreePicker.test.tsx` covers navigation, leaf select, vet-referral flag, retour, deselect
- 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 ### 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 - [ ] `scope_disclaimer` footer on each obs page or first page only — decide
- [ ] Update `LRN-009`-style layout still applies (text-area reservation) - [ ] Update `LRN-009`-style layout still applies (text-area reservation)
### B5. Stub cleanup ### B5. Stub cleanup (DONE 2026-05-20)
- [ ] `ZoneTooltip.tsx` — delete (unused) - [x] `ZoneTooltip.tsx` deleted (unused stub)
- [ ] `Toast.tsx` — implement OR delete (decide: notifications for PDF export/import?) - [x] `Toast.tsx` deleted (unused stub — re-introduce later if notifications needed)
- [ ] `ObservationEditor.tsx` — remove reference from CLAUDE.md folder map - [x] CLAUDE.md folder map updated — `ObservationEditor`/`Toast`/`ZoneTooltip` removed, `FindingsTreePicker`/`FreeTextFindingInput`/`findings.ts` added
--- ---