# Lead → Customer Conversion UI

**Date:** 2026-05-31  
**Status:** Draft  
**Spec:** 75  
**Tier:** All tiers  
**Depends on:** `marketing-leads-pipeline`, `customers-module`, `projects-module`, `foundation-auth-rbac`  
**Referenced by:** `marketing-leads-pipeline`

---

## Overview

Standalone spec for the lead-to-customer conversion UI flow. Spec 22 (`marketing-leads-pipeline`) defines the conversion API (`POST /api/leads/:id/convert`) and the data changes (`leads.customer_id` set, activity logged). This spec owns the UI: the modal, the form fields, and the post-conversion state change in the leads view.

---

## Trigger

Conversion is triggered from the lead detail panel (spec 22 `§ Lead Detail Panel`):

- When `leads.stage = 'WON'`: primary CTA "Convert to Customer" button shown
- When stage is NOT WON: secondary link "Convert (mark as Won first)" with tooltip — clicking it auto-advances to WON then opens the modal

---

## Conversion Modal

```
┌──────────────────────────────────────────────────────────────┐
│  Convert Lead to Customer                                    │
│                                                              │
│  Lead: Acme Corp (contacted: Dana Levi)                      │
│                                                              │
│  ── Customer record ��───────────────────────────────────── │
│                                                              │
│  Customer name *   [Acme Corp________________________]       │
│  Email             [acme@example.com_________________]       │
│  Phone             [050-1234567______________________]       │
│  Company           [Acme Corporation_________________]       │
│                                                              │
│  Fields pre-filled from lead data. Edit if needed.          │
│                                                              │
│  ── Optional: Create a project ────────────────────────── │
│                                                              │
│  ☐ Create a project for this customer                       │
│                                                              │
│  [Cancel]                        [Convert →]                 │
└──────────────────────────────────────────────────────────────┘
```

Fields are pre-filled from `leads.name`, `leads.email`, `leads.phone`, `leads.company`. User can edit before converting.

"Create a project" checkbox expands:

```
│  Project name *    [Acme Corp — Website Project_______]      │
│  Type              [Fixed price ▾]                          │
│  Start date        [2026-06-01___]                          │
```

---

## Post-Conversion State

After successful conversion:

1. Modal closes
2. Lead detail panel CTA changes to "View Customer →" (link to `/customers/{customerId}`)
3. Lead kanban card gains a "✓ Converted" badge on the WON column
4. Activity feed: new entry "Converted to customer: Acme Corp" with link

If a project was created: activity also shows "Project created: {projectName}" with link to `/projects/{projectId}`.

---

## API Call

`POST /api/leads/:id/convert` (spec 22):

```json
{
  "customer": {
    "name": "Acme Corp",
    "email": "acme@example.com",
    "phone": "050-1234567",
    "company": "Acme Corporation"
  },
  "project": {
    "name": "Acme Corp — Website Project",
    "billingType": "fixed",
    "startDate": "2026-06-01"
  }
}
```

`project` field is optional (omitted if checkbox unchecked).

Server:
1. `POST /api/customers` → creates customer (in same transaction)
2. `UPDATE leads SET customer_id = newCustomerId, stage = 'WON'` (if not already WON)
3. Optional: `POST /api/projects` with `customerId = newCustomerId`
4. Insert `lead_activities` record with `type = 'converted'`
5. Audit log entry

---

## Edge Cases

| Situation | Handling |
|-----------|---------|
| Email already exists as a customer | Server returns 409 with `{ existingCustomerId }`. Modal shows: "A customer with this email already exists. Link this lead to them instead?" with confirm button. |
| Lead already converted (`customer_id` set) | Conversion CTA replaced with "View Customer →" (no modal needed) |
| Converting without WON stage | Modal shows warning: "Converting will mark this lead as Won." User confirms. |

---

## Architecture Decisions

| Decision | Choice | Reason |
|----------|--------|--------|
| Pre-fill from lead fields | Not blank form | Lead data is the source; eliminating re-entry reduces friction and errors |
| Optional project creation | In-modal, not separate step | Common workflow: lead won → project starts; bundling saves a navigation step |
| Email conflict → link option | Not hard error | A lead may correspond to an existing customer added through another path; linking (not blocking) is the right UX |