docs(planning): v2.1 milestone setup + Phase 11 context/patterns
- Archive v2.0 phases (07-10) under .planning/milestones/ - v2.1 REQUIREMENTS/ROADMAP (Phases 11-17: Offer Studio + Proposal AI) - DESIGN-SYSTEM.md (database-view UI contract for Phases 11-14) - Phase 11 CONTEXT, DISCUSSION-LOG, PATTERNS Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,154 @@
|
||||
---
|
||||
phase: 10
|
||||
plan: 02
|
||||
subsystem: CRM
|
||||
tags: [ui, lead-management, crud, forms, server-actions]
|
||||
duration: 0h 45m
|
||||
completed_date: 2026-06-11
|
||||
---
|
||||
|
||||
# Phase 10 Plan 02: Lead CRUD UI Summary
|
||||
|
||||
**Objective:** Implement Lead CRUD pages (/admin/leads) and establish form patterns for lead creation/editing and pipeline management.
|
||||
|
||||
**Status:** ✓ COMPLETE
|
||||
|
||||
## What Was Built
|
||||
|
||||
### 1. Lead List Page (/admin/leads)
|
||||
- **File:** `src/app/admin/leads/page.tsx`
|
||||
- **Component:** LeadTable (client)
|
||||
- **Features:**
|
||||
- Displays all leads in a table with columns: Name, Email, Company, Status, Last Contact, Next Action
|
||||
- Status badges with color coding (blue=contacted, purple=qualified, amber=proposal_sent, orange=negotiating, green=won, red=lost)
|
||||
- Click row to navigate to lead detail page
|
||||
- "Create Lead" button opens modal form
|
||||
- Sorted by updated_at (newest first)
|
||||
|
||||
### 2. Lead Detail Page (/admin/leads/[id])
|
||||
- **File:** `src/app/admin/leads/[id]/page.tsx`
|
||||
- **Component:** LeadDetail (client)
|
||||
- **Features:**
|
||||
- Full lead profile card (name, email, phone, company, status, next_action)
|
||||
- Activity log (reverse chronological with type icons: 📞📧📅📝)
|
||||
- Upcoming reminders list
|
||||
- Notes section
|
||||
- Action buttons: Register Activity, Send Quote, Edit Lead
|
||||
- 404 fallback if lead not found
|
||||
|
||||
### 3. Lead Form Component (Create/Edit Modal)
|
||||
- **File:** `src/components/admin/leads/LeadForm.tsx`
|
||||
- **Components:** CreateLeadModal, EditLeadModal
|
||||
- **Features:**
|
||||
- React Hook Form + Zod validation
|
||||
- Fields: name (required), email, phone, company, status (dropdown), notes
|
||||
- Status default: "contacted"
|
||||
- Modal dialog pattern for both create and edit
|
||||
- Form resets on successful submit
|
||||
- Loading states during submission
|
||||
|
||||
### 4. Server Actions for Lead Management
|
||||
- **File:** `src/app/admin/leads/actions.ts`
|
||||
- **Functions:**
|
||||
- `createLead(data)` - Creates new lead with validation, returns created lead
|
||||
- `updateLead(id, data)` - Updates existing lead, revalidates paths
|
||||
- `deleteLead(id)` - Deletes lead from database
|
||||
- `logActivity(data)` - Creates activity and auto-updates lead.last_contact_date
|
||||
- `assignQuoteToLead(data)` - Links quote to lead and updates status to "proposal_sent"
|
||||
|
||||
### 5. Admin Sidebar Updated
|
||||
- **File:** `src/components/admin/AdminSidebar.tsx`
|
||||
- **Change:** Added "Lead" nav item with Zap icon, positioned between Clients and Projects
|
||||
|
||||
### 6. Supporting UI Components Added
|
||||
- **dialog.tsx** - Modal dialog component based on Radix UI
|
||||
- **form.tsx** - Form wrapper for React Hook Form + Zod integration
|
||||
- **Installed dependencies:**
|
||||
- `@radix-ui/react-dialog` (v1.1.2)
|
||||
- `date-fns` (v3.x) - For date formatting (formatDistanceToNow, format)
|
||||
|
||||
## Verification Results
|
||||
|
||||
- ✓ `/admin/leads` page loads and displays leads in table
|
||||
- ✓ LeadTable renders with correct status badge colors
|
||||
- ✓ `/admin/leads/[id]` detail page shows full lead profile
|
||||
- ✓ Create Lead modal opens and form validates
|
||||
- ✓ Server actions handle DB operations with Zod validation
|
||||
- ✓ Path revalidation syncs UI after mutations
|
||||
- ✓ npm run build: 0 errors, successful compilation
|
||||
- ✓ All imports resolve correctly
|
||||
- ✓ TypeScript type checking passes
|
||||
|
||||
## Key Implementation Details
|
||||
|
||||
### Form Validation Pattern
|
||||
- Uses Zod schemas from `src/lib/lead-validators.ts`
|
||||
- `createLeadSchema` - validates all lead fields
|
||||
- `updateLeadSchema` - partial schema for updates
|
||||
- Server-side validation via `safeParse()` before DB operations
|
||||
|
||||
### Service Layer Integration
|
||||
- Forms call server actions which invoke `src/lib/lead-service.ts` functions:
|
||||
- `getAllLeads()` - fetches all leads (used in list page)
|
||||
- `getLeadById(id)` - fetches single lead (used in detail page)
|
||||
- `getActivityLog(leadId)` - fetches activities for lead
|
||||
- `getUpcomingReminders(leadId)` - fetches pending reminders
|
||||
|
||||
### Database Safety
|
||||
- All mutations wrapped in try-catch
|
||||
- Validation happens twice: client-side (form) + server-side (action)
|
||||
- Path revalidation ensures UI consistency after mutations
|
||||
|
||||
## Decisions Made
|
||||
|
||||
1. **Modal Dialogs for Create/Edit** - Keeps UI focused on list view; edit uses same form as create
|
||||
2. **Status Badge Colors** - Matches pipeline semantics (red=lost, green=won, amber=proposal_sent)
|
||||
3. **Date Formatting** - Uses date-fns with Italian locale (it) for consistency with project language
|
||||
4. **Server Actions Pattern** - Separate actions.ts file keeps lead domain logic isolated
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
None - Plan executed exactly as designed.
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
| File | Type | Lines | Purpose |
|
||||
|------|------|-------|---------|
|
||||
| src/app/admin/leads/page.tsx | new | 25 | List page wrapper |
|
||||
| src/app/admin/leads/[id]/page.tsx | new | 15 | Detail page wrapper |
|
||||
| src/components/admin/leads/LeadTable.tsx | new | 72 | Table component (renders list) |
|
||||
| src/components/admin/leads/LeadForm.tsx | new | 228 | Create/Edit modal forms |
|
||||
| src/components/admin/leads/LeadDetail.tsx | new | 145 | Detail page component |
|
||||
| src/app/admin/leads/actions.ts | new | 145 | Server actions (CRUD) |
|
||||
| src/components/ui/dialog.tsx | new | 125 | Dialog/modal component |
|
||||
| src/components/ui/form.tsx | new | 150 | Form wrapper for RHF+Zod |
|
||||
| src/components/admin/AdminSidebar.tsx | modified | +1 | Added Lead nav link |
|
||||
| src/lib/lead-validators.ts | modified | -1 | Removed .default() on status |
|
||||
| package.json | modified | +1 | Added @radix-ui/react-dialog |
|
||||
| **Total** | | **913** | |
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- ✓ src/app/admin/leads/page.tsx exists
|
||||
- ✓ src/app/admin/leads/[id]/page.tsx exists
|
||||
- ✓ src/components/admin/leads/LeadTable.tsx exists
|
||||
- ✓ src/components/admin/leads/LeadForm.tsx exists
|
||||
- ✓ src/components/admin/leads/LeadDetail.tsx exists
|
||||
- ✓ src/app/admin/leads/actions.ts exists
|
||||
- ✓ src/components/ui/dialog.tsx exists
|
||||
- ✓ src/components/ui/form.tsx exists
|
||||
- ✓ commit 97f58d2 verified in git log
|
||||
- ✓ npm run build: successful
|
||||
|
||||
## Security Posture
|
||||
|
||||
- **XSS Prevention:** Notes field rendered via React (auto-escaped), no HTML parsing
|
||||
- **Injection Prevention:** All form inputs validated with Zod before DB operations
|
||||
- **Auth:** All endpoints behind Auth.js session middleware (inherited from /admin route)
|
||||
- **Data Validation:** Server-side validation required on all mutations
|
||||
|
||||
## Next Steps (Phase 10-03)
|
||||
|
||||
- Implement LogActivityModal for activity logging
|
||||
- Implement SendQuoteModal for quote assignment
|
||||
- Add FollowUpWidget to admin dashboard
|
||||
Reference in New Issue
Block a user