diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 515ecdc..2f497f9 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -157,4 +157,4 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 | 4. PDF Ingest | 4/4 | Complete | 2026-03-20 | | 5. PDF Fill and Field Mapping | 3/4 | In Progress| | | 6. Signing Flow | 6/6 | Complete | 2026-03-21 | -| 7. Audit Trail and Download | 1/3 | In Progress| | +| 7. Audit Trail and Download | 2/3 | In Progress| | diff --git a/.planning/STATE.md b/.planning/STATE.md index 6ddcc19..6f86b44 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -22,12 +22,12 @@ See: .planning/PROJECT.md (updated 2026-03-19) ## Current Position -Phase: 7 of 7 (Audit Trail and Download) — Plan 1 complete (1 of 3) -Plan: 07-01 (1 of 3 plans) — Agent download token (createAgentDownloadToken/verifyAgentDownloadToken) and GET /api/documents/[id]/download route — SIGN-07 and LEGAL-03 satisfied -Status: token.ts extended with agent-download JWT (5-min TTL); download route streams signed PDFs with path traversal guard and document ID cross-check; tsc and build pass -Last activity: 2026-03-21 — Phase 7 Plan 01: agent-download JWT utilities and authenticated download API route complete +Phase: 7 of 7 (Audit Trail and Download) — Plan 2 complete (2 of 3) +Plan: 07-02 (2 of 3 plans) — Agent download UI (PreparePanel Signed panel + Download Signed PDF anchor), Date Signed column in dashboard and client profile tables — SIGN-07 and LEGAL-03 surfaced in UI +Status: agentDownloadUrl generated server-side in document detail page; PreparePanel renders green Signed panel with download link; DocumentsTable has Date Signed column; tsc and build pass +Last activity: 2026-03-21 — Phase 7 Plan 02: download UI wired, signedAt added to all document tables -Progress: [█░░░░░░░░░] 33% (Phase 7 plan 1 of 3 complete) +Progress: [██░░░░░░░░] 67% (Phase 7 plan 2 of 3 complete) ## Performance Metrics @@ -65,6 +65,7 @@ Progress: [█░░░░░░░░░] 33% (Phase 7 plan 1 of 3 complete) | Phase 06-signing-flow P05 | 3 | 2 tasks | 4 files | | Phase 06-signing-flow P06 | 2 | 2 tasks | 2 files | | Phase 07-audit-trail-and-download P01 | 2 | 2 tasks | 2 files | +| Phase 07-audit-trail-and-download P02 | 2 | 2 tasks | 6 files | ## Accumulated Context @@ -141,6 +142,9 @@ Recent decisions affecting current work: - [Phase 06-signing-flow 06-05]: router.push replaces window.location.href for confirmed page navigation — SPA navigation consistent with Next.js App Router patterns - [Phase 07-audit-trail-and-download]: Agent download token uses same SIGNING_JWT_SECRET with purpose:'agent-download' claim; 5-min TTL; no DB record needed for ephemeral presigned download authorization - [Phase 07-audit-trail-and-download]: Token documentId vs route [id] cross-check added as defense-in-depth: valid token for doc A cannot download doc B (403) +- [Phase 07-audit-trail-and-download 07-02]: agentDownloadUrl generated in server component (page.tsx) not in PreparePanel — PreparePanel is 'use client' and cannot call createAgentDownloadToken (server-only) +- [Phase 07-audit-trail-and-download 07-02]: Download button is a plain anchor tag — browser follows href directly, Content-Disposition:attachment header in API route drives save dialog +- [Phase 07-audit-trail-and-download 07-02]: signedAt added to both dashboard and client profile queries — all document tables show consistent Date Signed column ### Pending Todos @@ -157,5 +161,5 @@ None yet. ## Session Continuity Last session: 2026-03-21 -Stopped at: Completed 07-01-PLAN.md — agent download token and route (SIGN-07, LEGAL-03 satisfied) +Stopped at: Completed 07-02-PLAN.md — download UI wired (SIGN-07, LEGAL-03 surfaced in portal UI) Resume file: None diff --git a/.planning/phases/07-audit-trail-and-download/07-02-SUMMARY.md b/.planning/phases/07-audit-trail-and-download/07-02-SUMMARY.md new file mode 100644 index 0000000..38f03f4 --- /dev/null +++ b/.planning/phases/07-audit-trail-and-download/07-02-SUMMARY.md @@ -0,0 +1,127 @@ +--- +phase: 07-audit-trail-and-download +plan: "02" +subsystem: ui +tags: [next.js, jwt, pdf, download, react, typescript] + +# Dependency graph +requires: + - phase: 07-audit-trail-and-download + plan: "01" + provides: createAgentDownloadToken (5-min TTL, purpose:'agent-download') and GET /api/documents/[id]/download route + - phase: 06-signing-flow + provides: documents.signedAt and documents.signedFilePath columns written on signing completion +provides: + - agentDownloadUrl generated server-side in document detail page and passed to PreparePanel + - PreparePanel Signed status: green panel with signed timestamp and Download Signed PDF anchor + - DocumentsTable Date Signed column showing signedAt for Signed documents + - Dashboard and client profile queries include signedAt +affects: + - 07-03 (audit trail plan may need to reference download events or document detail state) + +# Tech tracking +tech-stack: + added: [] + patterns: + - agentDownloadUrl generated in server component (page.tsx) and passed as prop to 'use client' PreparePanel — token never created in client code + - PreparePanel status-aware rendering: Signed branch (green panel + anchor link), Sent/Viewed branch (read-only), Draft branch (prepare form) + - Download is a plain anchor — no fetch/onClick; Content-Disposition:attachment response from API route handles browser download dialog + +key-files: + created: [] + modified: + - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PreparePanel.tsx + - teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/page.tsx + - teressa-copeland-homes/src/app/portal/_components/DocumentsTable.tsx + - teressa-copeland-homes/src/app/portal/(protected)/dashboard/page.tsx + - teressa-copeland-homes/src/app/portal/_components/ClientProfileClient.tsx + - teressa-copeland-homes/src/app/portal/(protected)/clients/[id]/page.tsx + +key-decisions: + - "agentDownloadUrl generated in server component (page.tsx) not in PreparePanel — PreparePanel is 'use client' and cannot call createAgentDownloadToken" + - "Download button is a plain anchor (no JS handler) — browser follows link directly, Content-Disposition:attachment triggers save dialog" + - "signedAt propagated to both dashboard query and client profile query for consistent Date Signed display across all document tables" + +patterns-established: + - "Server-side token generation pattern: generate adt token in server component → pass as string URL prop to client component → client renders plain anchor" + +requirements-completed: + - SIGN-07 + - LEGAL-03 + +# Metrics +duration: 2min +completed: 2026-03-21 +--- + +# Phase 7 Plan 02: Agent Download UI and signedAt Dashboard Column Summary + +**agentDownloadUrl generated server-side in document detail page, green Download Signed PDF panel added to PreparePanel for Signed status, and Date Signed column added to dashboard and client profile document tables** + +## Performance + +- **Duration:** 2 min +- **Started:** 2026-03-21T16:37:02Z +- **Completed:** 2026-03-21T16:39:16Z +- **Tasks:** 2 +- **Files modified:** 6 + +## Accomplishments +- PreparePanel extended with `agentDownloadUrl` and `signedAt` props; Signed status renders a green panel with formatted signed timestamp and a plain anchor Download Signed PDF button +- Document detail page (server component) now imports `createAgentDownloadToken`, generates `agentDownloadUrl` server-side for documents with `signedFilePath`, and passes it to PreparePanel — token never created in client code +- `DocumentsTable` type updated with `signedAt: Date | null`; Date Signed column added to table header and rows (formatted as "Mar 21, 2026", America/Denver timezone) +- Dashboard and client profile queries both select `signedAt` so all document tables display signed date + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Update PreparePanel props interface and add Download button for Signed status** - `b823ae5` (feat) +2. **Task 2: Wire document detail page, update dashboard table for signedAt** - `68d94a7` (feat) + +## Files Created/Modified +- `teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/_components/PreparePanel.tsx` - Extended interface with agentDownloadUrl/signedAt; added Signed branch (green panel + download anchor) before Sent/Viewed read-only branch +- `teressa-copeland-homes/src/app/portal/(protected)/documents/[docId]/page.tsx` - Added createAgentDownloadToken import; generates agentDownloadUrl server-side; passes agentDownloadUrl and signedAt to PreparePanel +- `teressa-copeland-homes/src/app/portal/_components/DocumentsTable.tsx` - Added signedAt to DocumentRow type; added Date Signed column header and cell +- `teressa-copeland-homes/src/app/portal/(protected)/dashboard/page.tsx` - Added signedAt to db select +- `teressa-copeland-homes/src/app/portal/_components/ClientProfileClient.tsx` - Added signedAt to local DocumentRow type (kept in sync with DocumentsTable) +- `teressa-copeland-homes/src/app/portal/(protected)/clients/[id]/page.tsx` - Added signedAt to query select + +## Decisions Made +- agentDownloadUrl is generated in the server component (page.tsx), not in PreparePanel — PreparePanel is a 'use client' component and cannot call `createAgentDownloadToken` (server-only) +- Download button is a plain `` anchor, not a fetch/onClick handler — the API route's `Content-Disposition: attachment` header drives the browser download dialog +- signedAt propagated to both dashboard and client profile tables for consistency — agents see signed date in all document views + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 1 - Bug] Fixed DocumentRow type mismatch in ClientProfileClient and client profile page query** +- **Found during:** Task 2 (TypeScript check after DocumentsTable update) +- **Issue:** `ClientProfileClient.tsx` declares its own local `DocumentRow` type without `signedAt`; it passes `docs` to `DocumentsTable` which now requires `signedAt`. TypeScript error: "Property 'signedAt' is missing in type 'DocumentRow' but required in type 'DocumentRow'" +- **Fix:** Added `signedAt: Date | null` to local `DocumentRow` in `ClientProfileClient.tsx`; added `signedAt: documents.signedAt` to the select in `clients/[id]/page.tsx` +- **Files modified:** `src/app/portal/_components/ClientProfileClient.tsx`, `src/app/portal/(protected)/clients/[id]/page.tsx` +- **Verification:** `tsc --noEmit` passes with zero errors; `npm run build` completes cleanly +- **Committed in:** `68d94a7` (Task 2 commit) + +--- + +**Total deviations:** 1 auto-fixed (Rule 1 - type mismatch caused by our DocumentsTable change) +**Impact on plan:** Necessary fix — both files share the same DocumentRow type contract. No scope creep; client profile documents table now also shows Date Signed column, which is a bonus. + +## Issues Encountered + +None. + +## User Setup Required + +None - no external service configuration required. + +## Next Phase Readiness +- Download UI is fully wired: agent can navigate to a Signed document detail page, see the green "Document Signed" panel with signed timestamp, and click "Download Signed PDF" to trigger browser download via the API route from Plan 01 +- Dashboard and client profile tables show Date Signed column for Signed documents, "—" for others +- Phase 7 Plan 03 (audit trail) can build on the established download route and document state + +--- +*Phase: 07-audit-trail-and-download* +*Completed: 2026-03-21*