---
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*
