Tasks: Fechamento das Lacunas Pós-Migração¶

Input: Design documents from specs/003-post-migration-gaps/ Prerequisites: plan.md, spec.md, research.md, data-model.md, contracts/, quickstart.md Tests: Required by FR-020 and the project constitution.

Format: `[ID] [P?] [Story] Description`¶

[P]: Can run in parallel after its phase prerequisites.
[US1], [US2], [US3]: maps work to an independently testable user story.
Every task includes its implementation or evidence path.

Phase 1: Setup and contract baselines¶

Purpose: Freeze contracts and prepare deterministic vertical-slice validation.

T001 Review and approve feature scope, unavailable-metric behavior, and rollout gates in specs/003-post-migration-gaps/spec.md and specs/003-post-migration-gaps/plan.md
T002 [P] Add deterministic two-owner post-migration fixture helpers in prontuare-web/tests/fixtures/post-migration.ts
T003 [P] Add shared safe error-envelope assertions for new routes in prontuare-api/test/helpers.ts
T004 Record baseline typecheck/build/test results and current mock/calendar behavior in specs/003-post-migration-gaps/evidence/baseline.md

Phase 2: Foundational boundary hardening¶

Purpose: Shared API/client date, error, and ownership behavior required by US1 and US2.

⚠️ CRITICAL: Complete before the user-story phases.

T005 Add validated IANA timezone and bounded semi-open interval utilities in prontuare-api/src/lib/time-range.ts
T006 [P] Add timezone/range boundary unit tests covering invalid zones, DST, day, month, and 42-day limit in prontuare-api/test/time-range.unit.test.ts
T007 Extend public API error handling with stable code and request identifier behavior in prontuare-api/src/lib/http-error.ts
T008 [P] Add dashboard and calendar response types, discriminated metric unions, and safe API errors in prontuare-web/lib/api.ts
T009 Register shared route modules without changing existing route compatibility in prontuare-api/src/main.ts

Checkpoint: Boundary utilities and client contracts compile independently.

Phase 3: User Story 1 — Visualizar e operar a agenda em um calendário (Priority: P1) 🎯 MVP¶

Goal: Restore month/week calendar navigation and move OAuth connection management to settings.

Independent Test: With deterministic appointments, /calendar renders correct month/week placement, navigation, overlaps, actions, failure/empty states, mobile list and owner isolation; /calendar/settings retains provider connection flows.

Tests for User Story 1¶

T010 [P] [US1] Add API integration cases for bounded ranges, deterministic ordering, minimal patient display data, cancelled events and cross-owner isolation in prontuare-api/test/calendar.integration.test.ts
T011 [P] [US1] Add calendar browser scenarios for month/week navigation, overlap, empty/error/retry, keyboard and mobile fallback in prontuare-web/tests/calendar-dashboard.spec.ts
T012 [P] [US1] Add OAuth settings redirect success/cancel/failure assertions in prontuare-api/test/calendar.integration.test.ts

Implementation for User Story 1¶

Checkpoint: US1 is deployable and testable without dashboard or external lookup decisions.

Phase 4: User Story 2 — Consultar indicadores reais do dia e do mês (Priority: P2)¶

Goal: Replace all dashboard mocks with one owner-scoped snapshot and explicit unavailable metrics.

Independent Test: A deterministic owner sees exact active-patient and today-appointment totals; documents and revenue show unavailable; another owner's rows never affect totals; errors never become false zero.

Tests for User Story 2¶

T026 [P] [US2] Add integration tests for active/inactive patients, cancelled appointments, timezone boundaries, common referenceAt, unavailable metrics and owner isolation in prontuare-api/test/dashboard.integration.test.ts
T027 [P] [US2] Extend browser tests with dashboard loading, exact totals, unavailable labels, failure and retry behavior in prontuare-web/tests/calendar-dashboard.spec.ts

Implementation for User Story 2¶

T028 [US2] Implement owner-scoped patient and appointment aggregates with one reference instant in prontuare-api/src/domains/dashboard/dashboard.service.ts
T029 [US2] Implement authenticated GET /dashboard/summary validation and response contract in prontuare-api/src/domains/dashboard/dashboard.routes.ts
T030 [US2] Register dashboard routes under the existing /api group in prontuare-api/src/main.ts
T031 [US2] Add typed getDashboardSummary client method and metric reason mapping in prontuare-web/lib/api.ts
T032 [US2] Replace list-patient query and all static card values with one summary query, skeletons, unavailable states and retry in prontuare-web/app/(dashboard)/page.tsx
T033 [US2] Link the dashboard quick action to the existing appointment creation flow in prontuare-web/app/(dashboard)/page.tsx
T034 [US2] Verify API tests, web typecheck/build and Playwright US2 flow; record exact evidence and gaps in specs/003-post-migration-gaps/evidence/us2-dashboard.md

Checkpoint: US2 is independently deployable after foundational work; no mock metric remains.

Phase 5: User Story 3 — Decidir e governar consultas externas brasileiras (Priority: P3)¶

Goal: Close the migration audit with an explicit owner decision for CEP, CNPJ and CFP, without silently adding integrations.

Independent Test: Every lookup row is approved as adopt, replace or retire with complete risk/fallback/UI/API consequences; manual input remains truthful and available.

T035 [P] [US3] Inventory current CEP/CNPJ formatting, network calls and user-facing claims in prontuare-web/hooks/use-cep.ts, prontuare-web/hooks/use-cnpj.ts, prontuare-web/components/cep-field.tsx, and prontuare-web/components/cnpj-field.tsx; record evidence in specs/003-post-migration-gaps/evidence/external-lookups-audit.md
T036 [P] [US3] Inventory legacy CFP/CEP/CNPJ endpoints, credentials, callers and tests under apps/api-core/ and apps/web/; record compatibility findings in specs/003-post-migration-gaps/evidence/external-lookups-audit.md
T037 [US3] Complete candidate source, privacy/terms, cost/quota, availability and fallback analysis for all three rows in specs/003-post-migration-gaps/contracts/external-lookups-decision.md
T038 [US3] Obtain and record owner decisions, owner name and review dates for CEP, CNPJ and CFP in specs/003-post-migration-gaps/contracts/external-lookups-decision.md
T039 [US3] Align misleading autofill/validation copy with approved retire/defer decisions while preserving manual input in prontuare-web/components/cep-field.tsx, prontuare-web/components/cnpj-field.tsx, and prontuare-web/app/onboarding/professional-profile/page.tsx
T040 [US3] Create follow-up feature specs for each approved adopt/replace decision under specs/ before any provider code, credential or dependency is added
T041 [US3] Record decision verification and any spawned feature links in specs/003-post-migration-gaps/evidence/us3-lookups.md

Checkpoint: Audit can close; integrations remain gated by their own approved specs.

Phase 6: Polish and cross-cutting verification¶

Purpose: Prove the combined feature meets constitutional and deployment gates.

T042 [P] Add pt-BR strings and preserve i18n-ready keys for new calendar/dashboard states in prontuare-web/lib/i18n.ts
T043 [P] Review focus, labels, contrast-independent states and responsive behavior against FR-007 in prontuare-web/components/calendar/
T044 [P] Measure representative API p95 and browser-visible timing against SC-003; record dataset and environment in specs/003-post-migration-gaps/evidence/performance.md
T045 Run all API typecheck/tests and web typecheck/build/E2E commands from specs/003-post-migration-gaps/quickstart.md; record pass/fail and untested items in specs/003-post-migration-gaps/evidence/final.md
T046 Reconcile implemented behavior and evidence against FR-001–FR-020 and SC-001–SC-008 in specs/003-post-migration-gaps/evidence/traceability.md
T047 Document API-first rollout, web rollout, health checks and rollback evidence in specs/003-post-migration-gaps/evidence/release.md

Dependencies and execution order¶

Phase dependencies¶

Phase 1 has no implementation dependency, but T001 owner approval gates all code tasks.
Phase 2 depends on Phase 1 contract approval.
US1 and US2 depend on Phase 2; after it, they may proceed independently.
US3 depends only on T001 and can run in parallel with US1/US2, except T038 requires owner input.
Phase 6 depends on completed slices in scope for the release.

User-story dependency graph¶

T001 Owner Approval
        |
        v
Phase 2 Foundation
   |             |
   v             v
US1 Calendar   US2 Dashboard

US3 Lookup Decision (parallel after T001)

US1 + US2 + US3 -> Final verification

Parallel opportunities¶

T002 and T003 can run together.
T006, T008 can run while T005/T007 are being implemented against frozen contracts.
US1 tests T010–T012 can be authored in parallel before implementation.
T016–T018 and T021 touch independent web files.
US2 tests T026–T027 can be authored in parallel.
US1 and US2 are independent after Phase 2.
T035 and T036 can audit current and legacy implementations concurrently.
T042–T044 are independent polish checks.

Implementation strategy¶

MVP first¶

Approve spec, plan, contracts and tasks (T001).
Complete foundational boundary work (T005–T009).
Complete US1 calendar (T010–T025).
Stop and validate the restored P0 journey before starting dashboard work.

Incremental delivery¶

Calendar visual restores the critical gap without relying on external providers.
Dashboard removes misleading data while preserving honest unavailable states.
External lookup decisions close governance and may produce separate features.
Final evidence determines deployment readiness; task completion alone does not.

Task format validation¶

All 47 tasks use a checkbox, sequential task ID, optional [P], required story label inside story phases, and an explicit file or directory path.