docs(07-02): complete download UI wiring plan — SUMMARY, STATE, ROADMAP updated

- 07-02-SUMMARY.md: documents PreparePanel Signed panel, agentDownloadUrl server-side generation, Date Signed column, and auto-fix of ClientProfileClient type mismatch - STATE.md: advanced to Phase 7 plan 2 of 3, added 3 key decisions, logged metrics row - ROADMAP.md: updated phase 7 progress (2/3 plans complete)
2026-03-21 10:40:46 -06:00
parent 68d94a779f
commit 86ca6dce85
3 changed files with 138 additions and 7 deletions
--- 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|  |
--- 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
--- a/.planning/phases/07-audit-trail-and-download/07-02-SUMMARY.md
+++ 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 <a href> 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 <a href> 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 `<a href>` 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*