Files
faunosteo/.claude/tasks/IMPLEMENTATION-PLAN.md
T
ZenQuality b5b2e163c9 feat: domain core — schemas, store, equine data, PDF roundtrip
Phase A — Domain & schemas (15 tests):
- Zod schemas: ReportSchema, FindingSchema, PractitionerSchema, SeveritySchema
- Types derived via z.infer (single source of truth)
- newId() helper with optional prefix

Phase B — Equine anatomy + pathology DB (7 tests):
- 26 macro zones, axial subzones C1-7/T1-18/L1-6/S1-5
- 31 pathologies, each citing Merck Vet Manual, PubMed, IMAIOS or LCAO
- Placeholder SVGs (lateral L/R + dorsal) with data-zone convention
- Species registry: equine registered, 8 others remain stubs

Phase C — Zustand store (8 tests):
- Single source of truth with persist middleware (localStorage key osteo-report-draft)
- Actions: hydrate, reset, toggleZone, addFinding, updateFinding, removeFinding, setConclusion/Recommendations/NextAppointment

Phase H/I — PDF export + import roundtrip (2 tests):
- A4 portrait, pdf-lib StandardFonts
- Header (practitioner + animal), anatomy pages (per used view), findings
  table, conclusion/recommendations/RDV page, page footer with date+page#
- Attachment: base64 data URI workaround (pdf-lib treats raw string as
  base64 input, and rejects cross-realm Uint8Array in jsdom tests)
- Import: walks Catalog→Names→EmbeddedFiles→Names array→F stream; inflates
  via pako directly (bypasses pdf-lib's reference-equality FlateDecode check
  which fails across module realms in vitest); validates with ReportSchema

Tooling:
- Add pako 2.x + @types/pako (already transitive of pdf-lib)
- Switch vitest 2 → 3 (already done in prior commit)
- Add 8 test files (34 tests total green)
2026-05-17 07:06:59 +02:00

9.1 KiB

Implementation Plan — Osteo Report V1

Granular tasks, TDD-first when behavior is testable. Each task targets one coherent change. Tasks are ordered so that each unblocks the next. Estimate ≈ 2-5 min of agent work per task.

Status legend: [ ] todo · [~] in progress · [x] done · [s] skipped.


Phase A — Domain & schemas (foundation, no UI)

  • A1 Test: tests/unit/schema.report.test.ts — parse a valid sample Report; reject malformed (missing version, bad species, empty animal name); assert z.infer matches expected fields.
  • A2 Implement: flesh src/schema/report.ts (already drafted) — re-verify enum, required fields, defaults match test.
  • A3 Test: tests/unit/schema.finding.test.ts — severity enum, free pathology flag, linked zones default empty.
  • A4 Implement: src/schema/finding.ts cleanup (already drafted) + ensure default arrays don't break Zod transform.
  • A5 Test: tests/unit/lib.id.test.ts — newId('finding') returns finding_…, length, uniqueness over 1000 calls.
  • A6 Implement: confirm src/lib/id.ts passes.

Phase B — Equine anatomy data

  • B1 Test: tests/unit/species.equine.test.ts — EQUINE_ANATOMY.vertebralFormula is { C7, T18, L6, S5 }; zones include at least neck, withers, thoracic-back, lumbar, sacrum, shoulder-l, shoulder-r, hip-l, hip-r, tail.
  • B2 Implement: fill src/species/equine/anatomy.ts with ~20 macro zones, declare views, declare subzones for vertebral zones (T1-T18, C1-C7, L1-L6, S1-S5).
  • B3 Create placeholder SVGs lateral-left.svg, lateral-right.svg, dorsal.svg in src/species/equine/ with at least 5 zones per view, conforming to convention (data-zone).
  • B4 Wire SVG imports via vite-plugin-svgr — type the import as React component.
  • B5 Test: tests/unit/species.registry.test.ts — registerSpecies('equine', ...) then getSpecies('equine') returns pack; isSpeciesAvailable('chien') is false.
  • B6 Implement: register equine pack at module load (src/species/equine/index.ts).
  • B7 Seed: src/species/equine/pathologies.ts — populate 30 pathologies with sourced citations (Merck Vet Manual, IMAIOS, PubMed, equine clinical journals). Each entry: id, label FR, description, category, applicableZones, sources.
  • B8 Stub: empty src/species/<other>/index.ts so the registry import doesn't crash. Other species register undefined pack — selector marks them disabled.

Phase C — State store

  • C1 Test: tests/unit/state.reportStore.test.ts — hydrate(report) sets all fields; reset() clears; toggleZone('z1') adds then removes; addFinding(f) pushes; updateFinding(id, patch) merges; removeFinding(id) removes; setConclusion('x') sets.
  • C2 Implement: full reportStore actions in src/state/reportStore.ts — typed via z.infer<typeof ReportSchema>. Persist key osteo-report-draft.
  • C3 Add an inferDraftFromStore selector that builds a Report from current store state (used by export).
  • C4 Test: persist round-trip — write store, simulate page reload (clear in-memory state, re-create from localStorage), assert findings restored.

Phase D — Routes & navigation

  • D1 Implement: HomeRoute UI — 2 large cards: "Nouveau bilan" → /new, "Importer un PDF" → file picker. Drag-drop overlay accepts only .pdf.
  • D2 Test: tests/unit/HomeRoute.test.tsx — render shows 2 CTAs; click "Nouveau bilan" navigates /new (use MemoryRouter).
  • D3 Implement: NewReportRoute form — species selector (9 options, 8 disabled badges), practitioner fields (fullName required + phone/email/address/SIRET optional), animal name + owner, sessionDate (default = today). React-hook-form + Zod resolver via PractitionerSchema & ReportSchema.shape.animal.
  • D4 Test: tests/unit/NewReportRoute.test.tsx — submit empty form shows validation errors; submitting valid form calls store.hydrate(newReportSeed) and navigates /editor.
  • D5 Implement: EditorRoute — <AnatomyCanvas /> + side panels (<ZoneSelection />, <FindingPanel />, <ConclusionPanel />, <ExportButton />).

Phase E — Anatomy canvas

  • E1 Implement: AnatomyView — renders one SVG (lateral L / R / dorsal). Attaches onClick to elements with data-zone. Highlights zones using data-selected, data-linked attributes synced with store state.
  • E2 Test: tests/unit/AnatomyView.test.tsx — render with mock SVG that has <rect data-zone="z1" />, click → store.toggleZone('z1') called.
  • E3 Implement: AnatomyCanvas — tabs for the 3 views, animate switch with motion. Persists current view in component state.
  • E4 Implement: ZoneSelection chip bar — shows current selection (zone labels), validate-button creates finding.
  • E5 Implement: ZoomOverlay modal — opens when user clicks "zoom" on a macro zone that has subzones. Uses react-zoom-pan-pinch inside the dialog. Click on subzone → store.addSubzoneSelection.

Phase F — Findings

  • F1 Implement: FindingEditor — multi-select pathology list filtered by applicableZones from current selection. Free-text pathology input. Severity radio. Comment textarea. Linked-zones picker.
  • F2 Test: tests/unit/FindingEditor.test.tsx — selecting two zones from thoracic-back filters pathology list to entries containing that zone; adding a free pathology preserves it on save.
  • F3 Implement: FindingPanel list — shows existing findings (zones, pathologies, severity badge, comment preview); edit/delete actions.

Phase G — Conclusion

  • G1 Implement: ConclusionPanel — textarea conclusion + textarea recommendations + optional date picker for nextAppointment. All wired to store.

Phase H — PDF export

  • H1 Test: tests/unit/pdf.export.test.ts — exportReport(sample, assets) returns a Blob whose content starts with %PDF-; attachments include report.json with parsed content equal to input.
  • H2 Implement: src/pdf/render/header.ts — draw practitioner block + animal/owner/date heading on a page using pdf-lib StandardFonts.
  • H3 Implement: src/pdf/render/anatomyPage.ts — rasterize an SVG view with selected zones highlighted, embed PNG via pdf.embedPng. Use html2canvas alternative: serialize SVG with inline <style> overrides per zone, then Canvg → Blob → toPng.
  • H4 Implement: src/pdf/render/findingsTable.ts — paginate findings table.
  • H5 Implement: src/pdf/render/footer.ts — page number + export date + URL.
  • H6 Implement: src/pdf/export.ts — orchestrate header → anatomy pages (one per view with selections) → findings table → conclusion → footer. Call pdf.attach(JSON.stringify(report), 'report.json', { mimeType: 'application/json' }). Return Blob.

Phase I — PDF import

  • I1 Test: tests/unit/pdf.roundtrip.test.ts — export sample report → load Blob with pdf-lib → importReport(File) → assert returned report deep equals sample.
  • I2 Test: import an external PDF (no attachment) returns { ok: false, reason: 'NO_ATTACHMENT' }.
  • I3 Implement: src/pdf/import.ts — PDFDocument.load(buffer) → iterate attachments → find report.json → JSON.parse → ReportSchema.safeParse → return Result.
  • I4 Wire HomeRoute import button → importReport → on success store.hydrate + navigate /editor; on error show toast with FR message.

Phase J — Design polish & motion

  • J1 Install shadcn components: button, card, dialog, badge, input, textarea, select, separator, toast. (Use shadcn CLI: npx shadcn@canary add button card dialog badge input textarea select separator sonner.)
  • J2 Implement Brand wordmark in src/components/Brand.tsx — typographic logo using Fraunces.
  • J3 Header + Footer across routes.
  • J4 Motion presets: route transitions (fade-up 200ms), modal spring, zone selection scale+tint.
  • J5 Accessibility pass: aria-labels on SVG zones, keyboard focus rings, color-contrast AA.

Phase K — E2E

  • K1 tests/e2e/roundtrip.spec.ts — full flow: load /, click new bilan, fill form (equine), navigate editor, select 2 zones from lateral-left, create finding with 1 pathology, write conclusion, export PDF, reload, import same PDF, assert restored state.

Phase L — Build & deploy verify

  • L1 npm run typecheck && npm run lint && npm run test && npm run build all green.
  • L2 docker compose build succeeds. Image runs and serves the SPA on :80.
  • L3 Verify nginx CSP doesn't break the app in production preview.

Subagent dispatch strategy

Phases A, B, C are independent enough to be done sequentially in main context. Phase H (PDF export) is large enough to warrant a dedicated subagent (write code + tests in isolation, surface a single PR-style diff).

Avoid subagent prompts that explicitly mention clinical wording — earlier content filter incident (BLK-001). Use neutral language: "vet workflow", "zone selection", "report data model".