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:
1 parent
b67f4cd82b
commit
b7b094535e
4 files changed
+79
-65
No files matched your search
@@ -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.
|
||||
@@ -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).
|
||||
@@ -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
@@ -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
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in new issue
Block a user