docs(20-01): complete apply-template plan — My Templates tab + template apply branch

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

.planning/phases/20-apply-template-and-portal-nav/20-01-SUMMARY.md

@@ -0,0 +1,105 @@
+---
+phase: 20-apply-template-and-portal-nav
+plan: "01"
+subsystem: document-template-apply
+tags: [templates, documents, modal, api]
+dependency_graph:
+  requires: [phase-18-template-schema-and-crud-api, phase-19-template-editor-ui]
+  provides: [template-apply-to-document, my-templates-tab]
+  affects: [AddDocumentModal, POST /api/documents]
+tech_stack:
+  added: []
+  patterns: [snapshot-copy-with-fresh-uuids, role-to-email-mapping, lazy-fetch-on-tab-switch]
+key_files:
+  created: []
+  modified:
+    - teressa-copeland-homes/src/app/api/documents/route.ts
+    - teressa-copeland-homes/src/app/portal/_components/AddDocumentModal.tsx
+decisions:
+  - "documentTemplateId branch placed before fileBuffer and formTemplateId branches — returns early so existing paths are fully unchanged"
+  - "SIGNER_COLORS constant extracted at module level for reuse in role-to-email mapping"
+  - "resolvedFormTemplateId used (not reassigning formTemplateId let var) to avoid confusion with the existing library branch variable"
+  - "handleSwitchToTemplates lazy-fetches only on first click — docTemplatesLoaded flag prevents repeated fetches on tab toggle"
+  - "handleSelectDocTemplate clears selectedTemplate and customFile for mutual exclusivity; handleSelectTemplate now also clears selectedDocTemplate"
+metrics:
+  duration_minutes: 2
+  completed_date: "2026-04-06"
+  tasks_completed: 2
+  files_modified: 2
+---
+
+# Phase 20 Plan 01: Apply Template and Portal Nav Summary
+
+**One-liner:** Template apply branch in POST /api/documents copies fields with fresh UUIDs and maps signer roles to client contacts; AddDocumentModal gains a My Templates tab with lazy-loaded template list.
+
+## Tasks Completed
+
+| # | Task | Commit | Files |
+|---|------|--------|-------|
+| 1 | Extend POST /api/documents with documentTemplateId branch | bdf0cb0 | src/app/api/documents/route.ts |
+| 2 | Add My Templates tab to AddDocumentModal | 2947fa5 | src/app/portal/_components/AddDocumentModal.tsx |
+
+## What Was Built
+
+### Task 1 — POST /api/documents template branch
+
+Extended the JSON body path of the POST handler to accept `documentTemplateId`. When provided:
+
+1. Fetches the `documentTemplates` record with its `formTemplate` relation (for the PDF filename)
+2. Copies the PDF from `seeds/forms/` using the form template's filename
+3. Maps every field to a new object with a fresh `crypto.randomUUID()` — template field IDs never appear in documents
+4. Collects unique signer role labels (stored in `signerEmail` on template fields) in order of first appearance
+5. Fetches the client record and builds `clientEmails = [client.email, ...contacts[].email]`
+6. Maps roles to emails: role[0] → clientEmails[0], role[1] → clientEmails[1], etc.; falls back to the role label if no email at that index
+7. Inserts the document with `signatureFields: copiedFields` and `signers: mappedSigners` and returns 201
+
+The existing custom-upload path and form-library path are completely unchanged.
+
+### Task 2 — AddDocumentModal My Templates tab
+
+Added a two-tab UI (Forms Library | My Templates) to the AddDocumentModal:
+
+- Tab bar uses underline-style active indicator matching project Tailwind conventions
+- My Templates tab lazy-fetches `GET /api/templates` on first click via `docTemplatesLoaded` flag
+- Empty state shown when no templates exist; loading state shown while fetching
+- Template rows show name, form name, and field count
+- Selecting a template clears `selectedTemplate` and `customFile` (mutual exclusivity)
+- Selecting a form or uploading a file clears `selectedDocTemplate`
+- `handleSubmit` has a new top branch: when `selectedDocTemplate` is set, sends `documentTemplateId` to POST /api/documents as JSON
+- Guard condition and submit button disabled state both updated to include `selectedDocTemplate`
+- All existing Forms Library and custom upload markup preserved exactly — only wrapped in `activeTab === 'forms'` conditional
+
+## Verification
+
+- `npx tsc --noEmit` — zero type errors (both tasks)
+- `npm run build` — production build succeeds
+- `documentTemplateId` present in route.ts (4 matches) and AddDocumentModal.tsx (1 match)
+- `crypto.randomUUID` present in route.ts (2 matches: docId + field copy)
+- `SIGNER_COLORS` present in route.ts
+- `activeTab` (5 matches) and `selectedDocTemplate` (6 matches) in AddDocumentModal.tsx
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+None.
+
+### Plan Adjustments
+
+**handleFileChange also clears selectedDocTemplate** — The plan specified mutual exclusivity in `handleSelectTemplate` and `handleSelectDocTemplate`, but `handleFileChange` (custom file picker) also needed to clear `selectedDocTemplate` to maintain full mutual exclusivity across all three selection paths. Added `setSelectedDocTemplate(null)` to `handleFileChange`. This is a completeness fix, not a deviation from intent.
+
+**resolvedFormTemplateId instead of reassigning formTemplateId** — The plan showed `formTemplateId = docTemplate.formTemplateId` to override the let variable. Instead used a new `const resolvedFormTemplateId` to avoid modifying a shared variable that existing branches also read. Cleaner and avoids any unintended side effects.
+
+## Known Stubs
+
+None — all data paths are fully wired. The template apply branch fetches real data from the database and inserts real documents with copied fields and mapped signers.
+
+## Self-Check: PASSED
+
+Files exist:
+- FOUND: teressa-copeland-homes/src/app/api/documents/route.ts
+- FOUND: teressa-copeland-homes/src/app/portal/_components/AddDocumentModal.tsx
+
+Commits exist:
+- bdf0cb0 — feat(20-01): extend POST /api/documents with documentTemplateId branch
+- 2947fa5 — feat(20-01): add My Templates tab to AddDocumentModal