Files
faunosteo/.claude/memory/decisions.md
T
Bastien ChanotandClaude Opus 4.7 31bd82de58 chore(memory+docs): /ship-feature B3 capitalize — BDR-014/015 + LRN-017..019 + EVAL-002 + journal + TODO
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>
2026-05-20 07:43:11 +02:00

6.8 KiB
Raw Blame History

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.