Memory registry capitalization after B3 i18n FR/EN ship. - decisions.md +BDR-014 (PDF locale = render preference, store-driven, not Report schema field — dual label snapshot already carried). - decisions.md +BDR-015 (typed ImportError discriminant kind + foundVersion; UI resolves message via dict; review caught hardcoded FR in domain layer). - learnings.md +LRN-017 (i18n dict parity test: Object.keys().sort() equality + non-empty value assertion — cheapest drift guard). - learnings.md +LRN-018 (useT hook pattern: selector subscribe + dict closure-per-render, no prop drilling, missing-key dev-warn + key-literal fallback). - learnings.md +LRN-019 (exhaustive-deps trap when closures over store values appear inside useMemo deps — inline or useCallback). - evals.md +EVAL-002 (B3 review caught critical FR leak in pdf/import.ts + attachment.ts that grep+analyzer both missed — i18n migrations must enumerate ALL string-emitting files including error paths). - journal.md session 3 entry under 2026-05-20. - TODO.md B3 subsection rewritten as DONE with checked checkboxes + cross-refs. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
128 lines
6.8 KiB
Markdown
128 lines
6.8 KiB
Markdown
# Decisions Registry
|
||
|
||
Format: BDR-XXX | Date | Title | Rationale | Alternatives | Status
|
||
|
||
---
|
||
|
||
## BDR-001 | 2026-05-18 | React SPA exception for tool app
|
||
|
||
Tool is practitioner-only, no public indexing needed → SPA valid per CLAUDE.md rule.
|
||
Alt: Next.js SSR rejected — no server, static deploy only.
|
||
Status: closed.
|
||
|
||
---
|
||
|
||
## BDR-002 | 2026-05-18 | SVG inline via DOMParser, not img/object
|
||
|
||
Inline SVG = full CSS control, pointer-events, data-* access.
|
||
img/object = sandboxed, no DOM access, no click delegation.
|
||
Status: closed.
|
||
|
||
---
|
||
|
||
## BDR-003 | 2026-05-18 | PDF attachment via native pdf-lib attach()
|
||
|
||
Native EmbeddedFiles (afRelationship:Data) = proper PDF spec, survives re-save in Acrobat.
|
||
Alt: custom metadata → rejected (non-standard, stripped by some viewers).
|
||
Status: closed.
|
||
|
||
---
|
||
|
||
## BDR-004 | 2026-05-18 | Runtime identity via window.__APP_CONFIG__
|
||
|
||
Build-time VITE_APP_* → baked into bundle; runtime injection via entrypoint.sh → no rebuild needed for brand changes.
|
||
Order: runtime > build-time > defaults.
|
||
Status: closed.
|
||
|
||
---
|
||
|
||
## BDR-005 | 2026-05-18 | Vertebra picker: region tabs + chip grid
|
||
|
||
≥40px touch targets, multi-select, per-region toggle.
|
||
Alt: flat list → too long for 54 total vertebrae.
|
||
Status: closed.
|
||
|
||
---
|
||
|
||
## BDR-006 | 2026-05-18 | Drag-reorder: up/down buttons, not DnD
|
||
|
||
DnD on mobile unreliable; ↑/↓ buttons accessible + simple.
|
||
Status: closed.
|
||
|
||
---
|
||
|
||
## BDR-007 | 2026-05-18 | pnpm 11 used instead of pnpm 9
|
||
|
||
pnpm@9 not available on host; corepack resolved 11.1.3.
|
||
Package.json engine constraint set to >=9 for Docker (Docker uses corepack latest).
|
||
Status: closed — deviation accepted.
|
||
|
||
---
|
||
|
||
## BDR-008 | 2026-05-19 | PDF page layout — branded heading pattern
|
||
|
||
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.
|
||
|
||
---
|
||
|
||
## BDR-012 | 2026-05-20 | Species auto-discovery via Vite import.meta.glob
|
||
|
||
`src/domain/species/registry.ts` uses `import.meta.glob('./*/index.ts', { eager: true })` and registers every module that default-exports a SpeciesManifest. Drop-folder onboarding: scaffold writes index.ts with `export default <id>`, no registry edit needed. Duplicate id → warn + first wins. Missing default export → silently skipped.
|
||
Alt rejected: hardcoded SPECIES_REGISTRY map — forced edits in two places, broke "single source of truth" per species folder.
|
||
Alt rejected: explicit registerSpecies() runtime helper — extra import boilerplate per species, no compile-time check that registration runs.
|
||
Status: closed.
|
||
|
||
---
|
||
|
||
## BDR-013 | 2026-05-20 | SVG↔JSON zone bridge via fuzzy FR/EN label match
|
||
|
||
SVG data-anno-id values stay opaque generator strings (point-mpb..., zone-...). JSON catalog keys are stable human zone names (sphenoid, atm). Bridge runs at observation render: matchZoneFindings normalizes both sides (lowercase + NFD-strip accents + alphanum-only) and scores EN-exact → FR-exact → substring → Levenshtein within max(2, floor(maxLen*0.25)) tolerance. EN first because no accent normalization edge cases.
|
||
Alt rejected: rename SVG data-anno-id to JSON keys — couples opaque SVG generator output to human-meaningful catalog, brittle across SVG re-exports.
|
||
Alt rejected: add new `data-anno-finding-zone` attribute on every hitbox — forces SVG edit per species, double-source for the same info already in name_fr/en.
|
||
Status: closed.
|
||
|
||
---
|
||
|
||
## BDR-014 | 2026-05-20 | PDF locale = render preference, not Report schema field
|
||
|
||
exportReportToPdf takes explicit `{ locale }` option read from localeStore at call site. Locale lives outside Report — never persisted in schema. Rationale: Finding snapshots already carry labelFrSnapshot+labelEnSnapshot (per BDR-010), so render-time locale picks the correct snapshot; no schema bump needed; re-imported PDF can be re-exported in either locale without data migration; embedded JSON byte-identical between locale variants of the same Report.
|
||
Alt rejected: store `locale` field on Report schema — would force v3 bump, complicate re-export ergonomics, duplicate state already in store.
|
||
Alt rejected: default locale to 'fr' in export — caller is route layer, has store, easy to pass; explicit arg makes tests + API surface clean.
|
||
Status: closed.
|
||
|
||
---
|
||
|
||
## BDR-015 | 2026-05-20 | Typed ImportError discriminant (kind + foundVersion) over localized messages
|
||
|
||
ImportError carries `kind: 'invalid_pdf' | 'incompatible_version' | 'no_attachment'` + optional `foundVersion`. Message field collapses to internal sentinel. UI layer (HomeRoute) resolves user-facing string via i18n dict using err.kind, with `{version}` template substitution. Rationale: review caught hardcoded FR in pdf/import.ts + pdf/attachment.ts leaking to EN UI; original "throw with localized message" coupled domain layer to one locale; typed discriminant moves message authoring to the UI layer where i18n lives.
|
||
Alt rejected: keep FR messages, translate via err.message string match — brittle (any rewording breaks the lookup), spreads i18n knowledge into the catch site.
|
||
Alt rejected: pass `t()` into domain layer — wrong direction; domain should not know about React hooks or current locale.
|
||
Status: closed.
|