Mayur Shinde
828 lines
54 KiB
Markdown
828 lines
54 KiB
Markdown
# Leads & Lead Verification — Backend Requirements
|
||
|
||
**Project:** LynkedUp Pro CRM (`lynkeduppro-crm`)
|
||
**Domain service:** `be-crm` (the CRM "data door")
|
||
**Modules covered:** `Leads`, `Lead Verification`
|
||
**Document status:** Implementation-ready. Derived entirely from the current frontend.
|
||
**Author basis:** Reverse-engineered from the completed frontend + the existing backend integration conventions already used by the Team, Mail, Inbox, Messenger, Media and Account modules.
|
||
|
||
---
|
||
|
||
> ## ⚠️ Read this first — current state of the frontend
|
||
>
|
||
> Both modules are **fully built on the UI side but wired to client-side mock data only**. There is **no live backend call anywhere** in `leads.tsx`, `leads-data.ts`, `verify.tsx`, or `verify-data.ts`. Every "write" today (Create Lead, Verify, Mark Unverified, Change Assignee, Update Status, Call, Email, Refresh) only pushes a **toast notification** — no persistence, no network request.
|
||
>
|
||
> This means the **entire** Leads and Lead Verification backend is greenfield. However, the frontend precisely defines the required **fields, enums, filters, sub-statuses, actions and workflows**, so this document treats the mock shapes as the authoritative contract.
|
||
>
|
||
> Wherever a control exists visually but has no behaviour yet, it is tagged **`[Frontend Placeholder / Backend Pending]`** so you know it is a real requirement even though the UI does not call it yet.
|
||
>
|
||
> The design below deliberately **reuses the existing `be-crm` architecture** (query/command data door, not REST). Do **not** invent a REST API — see §11 (Existing Backend Integration) for the mandatory conventions.
|
||
|
||
---
|
||
|
||
## Table of Contents
|
||
|
||
1. [Module Overview](#1-module-overview)
|
||
2. [Existing Frontend Features (exhaustive)](#2-existing-frontend-features-exhaustive)
|
||
3. [User Flows](#3-user-flows)
|
||
4. [Database Models](#4-database-models)
|
||
5. [Entity Relationships](#5-entity-relationships)
|
||
6. [API Contract — Actions (Queries & Commands)](#6-api-contract--actions-queries--commands)
|
||
7. [Validation Rules](#7-validation-rules)
|
||
8. [Reference / Enum Data](#8-reference--enum-data)
|
||
9. [Backend Services](#9-backend-services)
|
||
10. [Error Handling](#10-error-handling)
|
||
11. [Existing Backend Integration (mandatory conventions)](#11-existing-backend-integration-mandatory-conventions)
|
||
12. [Gaps, Discrepancies & Backend-Pending Items](#12-gaps-discrepancies--backend-pending-items)
|
||
|
||
---
|
||
|
||
## 1. Module Overview
|
||
|
||
### 1.1 Leads module
|
||
|
||
**Purpose:** The **Leads** module is the storm-restoration sales pipeline board. It holds prospective roofing jobs (door-knocked, referred, storm-chased, etc.) inside a hail-storm territory (the demo is the Plano, TX hail zone, storm event `2026-04-28`). Each lead is a rich record combining **contact**, **property**, **job details**, **insurance** and **assignment** information, and moves through a sales status pipeline.
|
||
|
||
**Frontend surface:** `src/components/dashboard/leads.tsx` (+ `leads-data.ts`), rendered inside the dashboard shell when the `leads` nav key is active.
|
||
|
||
**Core capabilities visible in the UI:**
|
||
- A **stat strip** (Total / New / Contacted / Appointed / Closed counts).
|
||
- A **board of lead cards** (avatar, priority ring, status pill, address, primary phone, source, canvasser, "updated" relative time).
|
||
- **Search** (by name / address / city / source / canvasser) and **status filter tabs**.
|
||
- A **lead detail modal** (Contact, Property, Job Details, Insurance, Assignment, storm banner).
|
||
- A **New Lead intake** with two modes: **Quick** (single condensed form) and **Full Form** (a 5-step wizard: Contact → Property → Job Details → Insurance → Assignment).
|
||
|
||
### 1.2 Lead Verification module
|
||
|
||
**Purpose:** The **Lead Verification** module is the verification desk that sits **upstream of Leads**. Freshly captured leads (door-knock / web form / storm canvass / referral / call-in) must pass an **identity + insurance + ownership + damage** verification workflow before they become working sales leads. The desk's terminal success action is literally *"Verified and pushed to New Leads"* — i.e., a verified verification record becomes a Lead with status `new`.
|
||
|
||
**Frontend surface:** `src/components/dashboard/verify.tsx` (+ `verify-data.ts`), rendered when the `verify` nav key is active.
|
||
|
||
**Core capabilities visible in the UI:**
|
||
- **Clickable stat tiles** (Verified / In Progress / Assigned / Pending / Unverified) that also act as status filters.
|
||
- A **data table** (Lead ID · Customer · Phone · Source · Assigned To · Status · Verification sub-status · Created · Actions).
|
||
- **Search** + **status / source / assignee** dropdown filters.
|
||
- A **row action set** (View, Verify, and a `⋯` menu: View Details, Verify Lead, Mark Unverified, Change Assignee, Reassign → In Progress, Move to Pending).
|
||
- A **verification detail modal** (Contact, Assignment, Verification Notes, and an **Activity timeline**).
|
||
- A **Refresh** button.
|
||
|
||
### 1.3 Relationship between the two modules
|
||
|
||
```
|
||
Intake sources Lead Verification desk Leads pipeline
|
||
(door knock, web form, ─────► verify identity / ownership / ─────► status = "new"
|
||
storm canvass, referral, insurance / damage → contacted → appointed
|
||
call-in) (verified | in_progress | → closed
|
||
assigned | pending | unverified)
|
||
```
|
||
|
||
- A **Lead Verification** record is the *pre-lead*. When it reaches `verified`, the system **creates / promotes** it into a **Lead** (`status = "new"`). This is the single hard link between the two modules and the most important cross-module command to implement (see `crm.leadVerification.verify` in §6).
|
||
- Both modules are gated by the **same** CRM permission: **`leads.manage`** (see `NAV_PERMISSION` in `sidebar.tsx`). There is no separate verification permission in the frontend.
|
||
- Both are **tenant-scoped** — every record belongs to the signed-in user's organization/tenant (the demo boots as `tenant-acme-01`).
|
||
|
||
### 1.4 User journey (end-to-end)
|
||
|
||
1. A lead is **captured** at an intake source and lands in the **Verification** queue as `pending` (unassigned) or `assigned`.
|
||
2. A **verification specialist** (Wade Hollis, Darlene Brooks, Roy Schaefer in the mock) is assigned and works the record through sub-statuses (`Verifying Identity` → `Confirming Ownership` → `Reviewing Insurance` → `Confirming Damage`).
|
||
3. The specialist either **Verifies** it (→ becomes a Lead, `status = new`) or **Marks Unverified**.
|
||
4. In the **Leads** module, a sales rep / canvasser works the new lead: **Contacted** → **Appointed** → **Closed**, updating status, priority, follow-up date, insurance/claim details and assignment along the way.
|
||
|
||
---
|
||
|
||
## 2. Existing Frontend Features (exhaustive)
|
||
|
||
Only features actually present in the code are listed. Each is tagged **Wired** (has real logic, even if only client-side state) or **`[Placeholder / Backend Pending]`** (UI exists, no behaviour beyond a toast).
|
||
|
||
### 2.1 Leads module features
|
||
|
||
| # | Feature | State | Notes / source |
|
||
|---|---------|-------|----------------|
|
||
| L1 | Lead board / card list | Wired (mock) | `LEADS` array rendered as `LeadCard`s |
|
||
| L2 | Header stat strip (Total, New, Contacted, Appointed, Closed) | Wired (mock) | `countByStatus`; `TOTAL_LEADS = 35` shown as total |
|
||
| L3 | Text search (name, address, city, source, canvasser) | Wired (mock) | `filtered` memo, case-insensitive substring |
|
||
| L4 | Status filter tabs (All / New / Contacted / Appointed / Closed) | Wired (mock) | `STATUS_TABS` |
|
||
| L5 | Lead detail modal (Contact, Property, Job, Insurance, Assignment, storm banner) | Wired (mock, read-only) | `LeadDetail` |
|
||
| L6 | Create Lead — Quick mode | **Placeholder** | `submit()` only validates name then toasts; no persistence |
|
||
| L7 | Create Lead — Full Form wizard (5 steps) | **Placeholder** | steps: Contact / Property / Job / Insurance / Assignment |
|
||
| L8 | Multiple phone numbers (with type Mobile/Home/Work + primary) | Wired (form state) | `addPhone/setPhone/removePhone` |
|
||
| L9 | Multiple email addresses | Wired (form state) | `addEmail/setEmail/removeEmail` |
|
||
| L10 | Site photos upload | **Placeholder** | `addPhoto()` just appends a label string `"Photo N"` — no real upload |
|
||
| L11 | Conditional field: Referral note (source = Referral) | Wired (form state) | `f.source === "Referral"` |
|
||
| L12 | Conditional field: Canvasser search (source = Door Knock) | Wired (form state) | `CanvasserSearch` typeahead over `REPS` |
|
||
| L13 | Priority picker (Low / Medium / High) | Wired (form state) | `PriorityPicker` |
|
||
| L14 | Urgency picker (Standard / High / Emergency) | Wired (form state) | `UrgencyPicker` |
|
||
| L15 | Rep assignment select (incl. "Unassigned") | Wired (form state) | `RepSelect`, options from `REPS` |
|
||
| L16 | Detail action: **Update Status** | **Placeholder** | footer button, no handler |
|
||
| L17 | Detail action: **Call** / **Email** | **Placeholder** | footer buttons, no handler |
|
||
| L18 | Empty state ("No leads match") | Wired | shown when `filtered.length === 0` |
|
||
|
||
**Not present in Leads (do not build unless requested):** edit-existing-lead form, delete, archive, bulk actions, tags editor (only a single static `tag` string exists), notes/comments thread, per-lead activity timeline, attachments list, pagination controls, sorting controls, export.
|
||
|
||
### 2.2 Lead Verification module features
|
||
|
||
| # | Feature | State | Notes / source |
|
||
|---|---------|-------|----------------|
|
||
| V1 | Stat tiles (Verified / In Progress / Assigned / Pending / Unverified) | Wired (mock) | `STAT_ORDER`, counts from `V_LEADS` |
|
||
| V2 | Stat tile click = status filter toggle | Wired (mock) | `setStatus(status === s ? "all" : s)` |
|
||
| V3 | Verification table (9 columns) | Wired (mock) | see column list in §1.2 |
|
||
| V4 | Text search (name, lead ID, phone, source, address) | Wired (mock) | `rows` memo |
|
||
| V5 | Status filter dropdown | Wired (mock) | mirrors stat tiles |
|
||
| V6 | Source filter dropdown | Wired (mock) | `V_SOURCES` |
|
||
| V7 | Assignee filter dropdown | Wired (mock) | `V_ASSIGNEES` |
|
||
| V8 | Row action: **View details** | Wired (mock) | opens `VerifyDetail` |
|
||
| V9 | Row action: **Verify** (quick) | **Placeholder** | toast only |
|
||
| V10 | Row `⋯` menu | Wired (open/close) | portalled dropdown |
|
||
| V11 | Menu: Verify Lead | **Placeholder** | toast only |
|
||
| V12 | Menu: Mark Unverified | **Placeholder** | toast only |
|
||
| V13 | Menu: Change Assignee | **Placeholder** | toast only |
|
||
| V14 | Menu: Reassign (→ In Progress) | **Placeholder** | toast only |
|
||
| V15 | Menu: Move to Pending | **Placeholder** | toast only |
|
||
| V16 | Detail modal — Contact / Assignment sections | Wired (mock, read) | `VerifyDetail` |
|
||
| V17 | Detail modal — Verification Notes | Wired (mock, read) | shown when `notes` present |
|
||
| V18 | Detail modal — Activity timeline | Wired (mock, read + derived) | `buildActivity()` synthesizes when absent |
|
||
| V19 | Detail footer: Verify Lead / Call | **Placeholder** | buttons, no handler |
|
||
| V20 | Refresh button | **Placeholder** | toast only ("Queue refreshed") |
|
||
| V21 | Row count "X of Y leads" | Wired (mock) | implies server total vs filtered count |
|
||
| V22 | Derived email / created-at when absent | Wired (mock) | `deriveEmail`, `deriveCreatedAt` |
|
||
|
||
**Not present in Verification (do not build unless requested):** create-verification-from-UI (records arrive via intake, never created here — mirrors the Inbox "items are never created here" pattern), delete, bulk verify, attachments, document upload, editable contact fields.
|
||
|
||
---
|
||
|
||
## 3. User Flows
|
||
|
||
### 3.1 Lead Verification status flow
|
||
|
||
Statuses (`VStatus`): `unverified`, `pending`, `assigned`, `in_progress`, `verified`.
|
||
Each status also carries a human **sub-status** string (`verification`).
|
||
|
||
```
|
||
intake (door knock / web form / storm canvass / referral / call-in)
|
||
│
|
||
▼
|
||
┌──────────── pending ("Pending Review", unassigned) ────────────┐
|
||
│ │ │
|
||
│ [Change Assignee] │
|
||
│ ▼ │
|
||
│ assigned ("Assigned") │
|
||
│ │ │
|
||
│ [Reassign / start work] │
|
||
│ ▼ │
|
||
│ in_progress ("Verifying Identity" / │
|
||
│ "Confirming Ownership" / │
|
||
│ "Reviewing Insurance" / │
|
||
│ "Confirming Damage") │
|
||
│ │ │ │
|
||
│ [Verify]│ │[Mark Unverified] │
|
||
│ ▼ ▼ │
|
||
│ verified unverified ◄─────────────────────┘
|
||
│ ("Verified") ("Unverified")
|
||
│ │
|
||
│ ▼
|
||
│ ┌───────────────────────────────┐
|
||
└────►│ PROMOTE → create Lead(status = │
|
||
│ "new") + activity "Verified │
|
||
│ and pushed to New Leads." │
|
||
└───────────────────────────────┘
|
||
|
||
[Move to Pending] can send an assigned/in_progress record back to pending.
|
||
```
|
||
|
||
**Allowed transitions (enforce server-side):**
|
||
|
||
| From | To | Trigger command |
|
||
|------|----|-----------------|
|
||
| `pending` | `assigned` | `assign` (set assignee) |
|
||
| `pending` / `assigned` / `in_progress` | `in_progress` | `reassign` / `setInProgress` |
|
||
| `assigned` / `in_progress` | `pending` | `moveToPending` |
|
||
| `pending` / `assigned` / `in_progress` | `verified` | `verify` (→ promotes to Lead) |
|
||
| `pending` / `assigned` / `in_progress` | `unverified` | `markUnverified` |
|
||
| any | (assignee change) | `assign` / `changeAssignee` |
|
||
|
||
> The frontend does not restrict transitions (every action is available on every row), so treat the table above as the **recommended** guard set; at minimum, forbid transitions out of a terminal `verified` record except via an explicit re-open (backend-pending, not in UI).
|
||
|
||
### 3.2 Lead sales status flow
|
||
|
||
Statuses (`LeadStatus`): `new`, `contacted`, `appointed`, `closed`.
|
||
|
||
```
|
||
(created directly OR promoted from a verified verification)
|
||
│
|
||
▼
|
||
new
|
||
│ [Update Status] / rep works the lead
|
||
▼
|
||
contacted
|
||
│
|
||
▼
|
||
appointed (adjuster / inspection appointment set)
|
||
│
|
||
▼
|
||
closed (won/installed/paid — mock leans "won")
|
||
```
|
||
|
||
`priority` (`high` / `medium` / `low`) and `job.urgency` (`Standard` / `High` / `Emergency`) are independent of status and set at creation / update.
|
||
|
||
### 3.3 Create Lead (Full Form wizard) flow
|
||
|
||
```
|
||
Step 1 Contact → firstName*, lastName, phones[] (type + primary), emails[]
|
||
Step 2 Property → address, city, state (default "TX"), zip, propertyType, photos[]
|
||
Step 3 Job → source, leadType, workType, tradeType, urgency, notes
|
||
(source=Referral → referralNote; source=Door Knock → canvasser)
|
||
Step 4 Insurance → insCompany, claimNumber, claimStatus, adjusterName,
|
||
adjusterPhone, policyNumber
|
||
Step 5 Assignment→ assignRep (or Unassigned), priority, followUp date
|
||
→ [Create Lead] → crm.lead.create
|
||
```
|
||
|
||
Quick mode collects a condensed subset (firstName*, lastName, phone[0], address, city, state, zip, source, [referralNote|canvasser], priority, followUp) and submits the same `crm.lead.create`.
|
||
|
||
`*` = the only field the frontend currently enforces is a non-empty **name** (first or last).
|
||
|
||
---
|
||
|
||
## 4. Database Models
|
||
|
||
Storage assumptions follow the existing `be-crm` domain service (relational, multi-tenant). **Every table carries `tenant_id`** and is always filtered by it. Primary keys are opaque server IDs; the human-facing **codes** (`SAL-001`, `LD-V-001`) are separate, per-tenant, monotonic display identifiers.
|
||
|
||
Timestamps are stored as `timestamptz` (UTC, ISO-8601 on the wire). Relative strings like `"3d ago"` and pretty dates like `"Jun 4, 2026"` seen in the mock are **presentation-only** — the API returns ISO timestamps and the client formats them (see `relTime()` in `team-api.ts`).
|
||
|
||
### 4.1 `leads`
|
||
|
||
**Purpose:** One row per sales lead (the Leads board card + detail modal).
|
||
|
||
| Field | Type | Null | Default | Notes |
|
||
|-------|------|------|---------|-------|
|
||
| `id` | uuid / string PK | no | gen | opaque server id |
|
||
| `tenant_id` | uuid/string FK → organizations | no | — | tenant scope; **indexed** |
|
||
| `code` | text | no | seq | display code `SAL-001`; **unique per tenant** |
|
||
| `first_name` | text | no | — | |
|
||
| `last_name` | text | yes | null | name = `first + last`, trimmed |
|
||
| `status` | enum `lead_status` | no | `'new'` | `new` \| `contacted` \| `appointed` \| `closed` |
|
||
| `priority` | enum `lead_priority` | no | `'medium'` | `high` \| `medium` \| `low` (UI Quick default = Medium) |
|
||
| `tag` | text | yes | `'Storm Zone'` | single label chip |
|
||
| `property_address` | text | yes | null | |
|
||
| `property_city` | text | yes | null | |
|
||
| `property_state` | text | yes | `'TX'` | 2-letter; UI default TX |
|
||
| `property_zip` | text | yes | null | |
|
||
| `property_type` | text | yes | null | see `PROPERTY_TYPES` enum |
|
||
| `source` | text | yes | null | see `LEAD_SOURCES` enum |
|
||
| `referral_note` | text | yes | null | only when `source = 'Referral'` |
|
||
| `lead_type` | text | yes | null | see §12 note on the enum conflict |
|
||
| `work_type` | text | yes | null | see `WORK_TYPES` |
|
||
| `trade_type` | text | yes | null | see `TRADE_TYPES` |
|
||
| `urgency` | enum `lead_urgency` | no | `'Standard'` | `Standard` \| `High` \| `Emergency` |
|
||
| `job_notes` | text | yes | null | "Field Notes" |
|
||
| `canvasser_id` | FK → members | yes | null | door-knock canvasser (REP id, e.g. `LUP-1040`) |
|
||
| `insurance_company` | text | yes | null | |
|
||
| `insurance_claim_status` | enum `claim_status` | yes | null | `Not Filed`\|`Filed`\|`Approved`\|`Paid`\|`Denied` |
|
||
| `insurance_claim_number` | text | yes | null | |
|
||
| `insurance_policy_number` | text | yes | null | |
|
||
| `insurance_adjuster_name` | text | yes | null | |
|
||
| `insurance_adjuster_phone` | text | yes | null | |
|
||
| `assigned_to_id` | FK → members | yes | null | rep working the lead |
|
||
| `follow_up_date` | date | yes | null | |
|
||
| `storm_zone` | text | yes | null | e.g. "E Plano / Spring Creek Pkwy" |
|
||
| `storm_date` | date | yes | null | e.g. `2026-04-28` |
|
||
| `storm_detail` | text | yes | null | e.g. `2.5" hail (severe)` |
|
||
| `source_verification_id` | FK → lead_verifications | yes | null | set when promoted from a verification |
|
||
| `created_by_id` | FK → members | yes | null | |
|
||
| `created_at` | timestamptz | no | now() | |
|
||
| `updated_at` | timestamptz | no | now() | drives "updated 3d ago" |
|
||
|
||
**Indexes:** `(tenant_id)`, `(tenant_id, status)`, `(tenant_id, code)` unique, `(tenant_id, assigned_to_id)`, `(tenant_id, source)`, `(tenant_id, updated_at desc)`.
|
||
**Search:** the board search covers name + property address + city + source + canvasser → back with a `tsvector` / trigram index over those columns.
|
||
|
||
**Example row (from `SAL-001`):**
|
||
```json
|
||
{
|
||
"id": "ld_9f2c…", "code": "SAL-001",
|
||
"firstName": "John", "lastName": "Martinez",
|
||
"status": "contacted", "priority": "high", "tag": "Storm Zone",
|
||
"propertyAddress": "4821 Spring Creek Pkwy", "propertyCity": "Plano",
|
||
"propertyState": "TX", "propertyZip": "75023", "propertyType": "Single Family",
|
||
"source": "Door Knock", "leadType": "Insurance",
|
||
"workType": "Roof Replacement", "tradeType": "Roofing", "urgency": "High",
|
||
"jobNotes": "Homeowner showed significant granule loss…",
|
||
"canvasserId": "LUP-1040",
|
||
"insuranceCompany": "State Farm", "insuranceClaimStatus": "Filed",
|
||
"insuranceClaimNumber": "CLM-2026-1000", "insurancePolicyNumber": "POL-080000",
|
||
"insuranceAdjusterName": "Marcus Powell", "insuranceAdjusterPhone": "(972) 700-3000",
|
||
"assignedToId": "LUP-…", "followUpDate": "2026-06-04",
|
||
"stormZone": "E Plano / Spring Creek Pkwy", "stormDate": "2026-04-28",
|
||
"stormDetail": "2.5\" hail (severe)",
|
||
"createdById": "LUP-1040", "createdAt": "2026-05-28T15:00:00Z", "updatedAt": "…"
|
||
}
|
||
```
|
||
|
||
### 4.2 `lead_phones`
|
||
|
||
**Purpose:** A lead has 1..N phone numbers, one primary.
|
||
|
||
| Field | Type | Null | Default | Notes |
|
||
|-------|------|------|---------|-------|
|
||
| `id` | PK | no | gen | |
|
||
| `tenant_id` | FK | no | — | |
|
||
| `lead_id` | FK → leads | no | — | **on delete cascade** |
|
||
| `number` | text | no | — | free-form display, e.g. `(469) 500-1000` |
|
||
| `type` | enum `phone_type` | no | `'Mobile'` | `Mobile` \| `Home` \| `Work` |
|
||
| `is_primary` | bool | no | false | exactly one true per lead (enforce) |
|
||
| `position` | int | no | 0 | display order |
|
||
|
||
**Indexes:** `(lead_id)`. **Constraint:** partial unique `(lead_id) where is_primary` to guarantee a single primary.
|
||
|
||
### 4.3 `lead_emails`
|
||
|
||
| Field | Type | Null | Default | Notes |
|
||
|-------|------|------|---------|-------|
|
||
| `id` | PK | no | gen | |
|
||
| `tenant_id` | FK | no | — | |
|
||
| `lead_id` | FK → leads | no | — | cascade |
|
||
| `address` | text | no | — | validate email format |
|
||
| `type` | text | yes | null | optional label |
|
||
| `is_primary` | bool | no | false | |
|
||
| `position` | int | no | 0 | |
|
||
|
||
### 4.4 `lead_attachments` (site photos) — `[Backend Pending]`
|
||
|
||
**Purpose:** Backs the "Site Photos" uploader (L10). The frontend currently only stores placeholder labels; the real implementation must use the existing media presign flow (§11.5).
|
||
|
||
| Field | Type | Null | Default | Notes |
|
||
|-------|------|------|---------|-------|
|
||
| `id` | PK | no | gen | |
|
||
| `tenant_id` | FK | no | — | |
|
||
| `lead_id` | FK → leads | no | — | cascade |
|
||
| `content_ref` | text | no | — | IIOS object key from `crm.media.presignUpload` |
|
||
| `mime_type` | text | no | — | |
|
||
| `size_bytes` | bigint | no | — | ≤ `26_214_400` (25 MB) |
|
||
| `filename` | text | yes | null | |
|
||
| `uploaded_by_id` | FK → members | yes | null | |
|
||
| `created_at` | timestamptz | no | now() | |
|
||
|
||
### 4.5 `lead_status_history` (audit) — recommended
|
||
|
||
**Purpose:** Backs "Update Status" auditing (no dedicated Leads timeline UI exists yet, but status changes must be auditable and this feeds a future timeline). Mirrors the verification activity concept.
|
||
|
||
| Field | Type | Null | Notes |
|
||
|-------|------|------|-------|
|
||
| `id` | PK | no | |
|
||
| `tenant_id` | FK | no | |
|
||
| `lead_id` | FK → leads | no | cascade |
|
||
| `from_status` | enum | yes | null on create |
|
||
| `to_status` | enum | no | |
|
||
| `actor_id` | FK → members | yes | |
|
||
| `note` | text | yes | |
|
||
| `created_at` | timestamptz | no | |
|
||
|
||
### 4.6 `lead_verifications`
|
||
|
||
**Purpose:** One row per verification-desk record (the Verification table row + detail).
|
||
|
||
| Field | Type | Null | Default | Notes |
|
||
|-------|------|------|---------|-------|
|
||
| `id` | PK | no | gen | |
|
||
| `tenant_id` | FK | no | — | indexed |
|
||
| `code` | text | no | seq | display code `LD-V-001`; **unique per tenant** |
|
||
| `name` | text | no | — | customer full name (single field in UI) |
|
||
| `phone` | text | yes | null | |
|
||
| `email` | text | yes | null | derived client-side when absent (see `deriveEmail`) |
|
||
| `address` | text | yes | null | single-line address string in UI |
|
||
| `source` | text | no | — | see `V_SOURCES` (`Door Knock`, `Web Form`, `Storm Canvass`, `Referral`, `Call-In`) |
|
||
| `status` | enum `verification_status` | no | `'pending'` | `verified`\|`in_progress`\|`assigned`\|`pending`\|`unverified` |
|
||
| `sub_status` | text | no | `'Pending Review'` | the `verification` label, see §8.6 |
|
||
| `assignee_id` | FK → members | yes | null | verification specialist |
|
||
| `notes` | text | yes | null | "Verification Notes" |
|
||
| `promoted_lead_id` | FK → leads | yes | null | set when verified → Lead created |
|
||
| `verified_at` | timestamptz | yes | null | |
|
||
| `created_at` | timestamptz | no | now() | drives "Created" column |
|
||
| `updated_at` | timestamptz | no | now() | |
|
||
|
||
**Indexes:** `(tenant_id)`, `(tenant_id, status)`, `(tenant_id, source)`, `(tenant_id, assignee_id)`, `(tenant_id, code)` unique, `(tenant_id, created_at desc)`.
|
||
**Search:** name + code + phone + source + address → trigram/tsvector.
|
||
|
||
**Example rows (from `LD-V-001` and a lean one):**
|
||
```json
|
||
{ "id":"lv_1…","code":"LD-V-001","name":"Kevin Hartley",
|
||
"phone":"(972) 413-8902","email":"kevin.hartley@gmail.com",
|
||
"address":"2814 Ravenswood Dr, Plano, TX 75023","source":"Door Knock",
|
||
"status":"verified","subStatus":"Verified","assigneeId":"…Wade…",
|
||
"notes":"Ownership confirmed via county records…",
|
||
"verifiedAt":"2026-05-16T19:55:00Z","createdAt":"2026-05-14T14:40:00Z" }
|
||
|
||
{ "id":"lv_11…","code":"LD-V-011","name":"Aaron Blake",
|
||
"phone":"(469) 471-3350","address":"1188 Alma Dr, Plano, TX 75075",
|
||
"source":"Door Knock","status":"pending","subStatus":"Pending Review",
|
||
"assigneeId":null,"createdAt":"2026-05-27T…" }
|
||
```
|
||
|
||
### 4.7 `lead_verification_activities`
|
||
|
||
**Purpose:** The Activity timeline in the verification detail (V18). The frontend synthesizes these when absent (`buildActivity`), but the backend should persist real ones.
|
||
|
||
| Field | Type | Null | Notes |
|
||
|-------|------|------|-------|
|
||
| `id` | PK | no | |
|
||
| `tenant_id` | FK | no | |
|
||
| `verification_id` | FK → lead_verifications | no | cascade |
|
||
| `text` | text | no | e.g. "Assigned to Wade Hollis." |
|
||
| `actor_id` | FK → members | yes | maps to `who` (name shown; "System" when null) |
|
||
| `actor_label` | text | yes | denormalized display name / "System" |
|
||
| `occurred_at` | timestamptz | no | maps to `time` |
|
||
| `kind` | text | yes | optional: `submitted`\|`assigned`\|`in_progress`\|`verified`\|`unverified`\|`note` |
|
||
|
||
**Index:** `(verification_id, occurred_at)`.
|
||
|
||
### 4.8 Referenced existing tables (do **not** recreate)
|
||
|
||
- **`organizations` / tenant** — tenant scope (`tenant_id`). Established at boot / registration (`crm.account.register`).
|
||
- **`members`** — CRM team members (reps, canvassers, verification specialists). Already served by `crm.team.member.search` and carry ids like `LUP-1040` plus `principalId`. Leads/verifications reference members for `assigned_to`, `canvasser`, `assignee`, `created_by`, and activity `actor`. In the mock these are free-text names — the backend must resolve them to member ids (see §12).
|
||
- **Account/permissions** — `crm.account.me` drives `leads.manage` gating.
|
||
|
||
---
|
||
|
||
## 5. Entity Relationships
|
||
|
||
```
|
||
organizations (tenant)
|
||
1 ──────────────< leads
|
||
1 ──────────────< lead_verifications
|
||
1 ──────────────< members
|
||
|
||
members
|
||
1 ──< leads.assigned_to_id
|
||
1 ──< leads.canvasser_id
|
||
1 ──< leads.created_by_id
|
||
1 ──< lead_verifications.assignee_id
|
||
1 ──< lead_verification_activities.actor_id
|
||
1 ──< lead_status_history.actor_id
|
||
|
||
leads
|
||
1 ──< lead_phones (cascade)
|
||
1 ──< lead_emails (cascade)
|
||
1 ──< lead_attachments (cascade) [backend-pending]
|
||
1 ──< lead_status_history (cascade)
|
||
|
||
lead_verifications
|
||
1 ──< lead_verification_activities (cascade)
|
||
1 ──0..1 leads (promotion: lead_verifications.promoted_lead_id
|
||
⇆ leads.source_verification_id)
|
||
```
|
||
|
||
**Cardinality summary**
|
||
|
||
| Relationship | Type | Notes |
|
||
|--------------|------|-------|
|
||
| tenant → lead | 1‑to‑many | all leads tenant-scoped |
|
||
| tenant → verification | 1‑to‑many | |
|
||
| lead → phones | 1‑to‑many | ≥1, exactly one primary |
|
||
| lead → emails | 1‑to‑many | 0..N |
|
||
| lead → attachments | 1‑to‑many | 0..N (pending) |
|
||
| lead → status history | 1‑to‑many | audit |
|
||
| verification → activities | 1‑to‑many | timeline |
|
||
| verification → lead | 1‑to‑(0..1) | promotion link, bidirectional FK |
|
||
| member → lead (assigned/canvasser/creator) | many‑to‑1 each | nullable |
|
||
| member → verification (assignee) | many‑to‑1 | nullable |
|
||
|
||
**Embedded value objects (not separate tables — stored as columns on `leads`):** `storm { zone, date, detail }`, `property { … }`, `job { … }`, `insurance { … }`, `assignment { … }`. They are grouped only for UI sectioning; there is no reuse that justifies separate tables. Phones and emails **are** separate tables because they are 1‑to‑many.
|
||
|
||
---
|
||
|
||
## 6. API Contract — Actions (Queries & Commands)
|
||
|
||
> **Transport & style (mandatory):** These are **not REST routes**. They are `be-crm` **data-door actions** invoked through the AppShell SDK exactly like every other module:
|
||
> - **Reads:** `useQuery<T>("<action>", variables)` → resolves to `T` (or `null` while loading). Errors surface as an `Error` with `.message`.
|
||
> - **Writes:** `sdk.command<T>("<action>", variables)` → resolves to `T`. Commands carry an auto-generated idempotency key.
|
||
> - **Action naming:** `crm.<entity>.<verb>` — dot-namespaced, camelCase segments (matches `crm.team.member.setRoles`, `crm.inbox.transition`, `crm.mail.reply`).
|
||
> - **Collection reads** return either a bare array (like `crm.mail.list`, `crm.inbox.list`) or `{ items: T[], meta }` (like `crm.team.member.search`). For Leads/Verification use **`{ items, meta }`** because the UI needs totals + pagination (§6.1).
|
||
|
||
### 6.1 Standard collection envelope
|
||
|
||
```ts
|
||
interface Meta { total: number; page: number; perPage: number; }
|
||
interface Page<T> { items: T[]; meta: Meta; }
|
||
```
|
||
- `verify.tsx` renders `"{rows.length} of {V_LEADS.length} leads"` → `rows.length` is the filtered page length, `meta.total` is the (filtered or overall) count. Return the **filtered** total so the "X of Y" reads correctly, plus the unfiltered stat counts via the dedicated `*.stats` action.
|
||
- `leads.tsx` shows `TOTAL_LEADS = 35` while only rendering 5 cards → the board is paginated/capped server-side; provide `perPage` (UI has no pager control yet, so default a sensible `perPage`, e.g. 50, and return `meta.total` for the header).
|
||
|
||
### 6.2 Leads — Queries
|
||
|
||
| Action | Variables | Returns | Backs |
|
||
|--------|-----------|---------|-------|
|
||
| `crm.lead.search` | `{ query?, status?, priority?, source?, assigneeId?, page?, perPage? }` | `Page<LeadCardDTO>` | board list L1, search L3, tabs L4 |
|
||
| `crm.lead.get` | `{ id }` | `LeadDTO` (full detail incl. phones/emails/attachments) | detail modal L5 |
|
||
| `crm.lead.stats` | `{}` | `{ total: number, byStatus: { new, contacted, appointed, closed } }` | stat strip L2 |
|
||
|
||
`LeadCardDTO` (list projection — only what the card needs):
|
||
```ts
|
||
{ id, code, name, initials, gradient, priority, status, tag,
|
||
primaryPhone, propertyAddress, propertyCity, propertyState,
|
||
source, canvasserName, updatedAt }
|
||
```
|
||
`LeadDTO` (detail projection): all §4.1 columns + `phones: Phone[]` + `emails: Email[]` + `attachments: Attachment[]` + resolved assignee/canvasser/creator display names + `storm`, `property`, `job`, `insurance`, `assignment` groupings.
|
||
|
||
### 6.3 Leads — Commands
|
||
|
||
| Action | Variables | Returns | Backs |
|
||
|--------|-----------|---------|-------|
|
||
| `crm.lead.create` | full create payload (below) | `LeadDTO` | Create Lead L6/L7 |
|
||
| `crm.lead.update` | `{ id, patch: Partial<LeadInput> }` | `LeadDTO` | edit (backend-pending; UI edit form not built) |
|
||
| `crm.lead.updateStatus` | `{ id, status, note? }` | `LeadDTO` | detail "Update Status" L16 |
|
||
| `crm.lead.assign` | `{ id, assigneeId \| null }` | `LeadDTO` | rep assignment L15 |
|
||
| `crm.lead.attachment.add` | `{ id, attachment: { contentRef, mimeType, sizeBytes, filename } }` | `LeadDTO` | site photos L10 (pending) |
|
||
| `crm.lead.attachment.remove` | `{ id, attachmentId }` | `LeadDTO` | pending |
|
||
| `crm.lead.archive` | `{ id }` | `{ id }` | **pending** — no UI yet; include only if requested |
|
||
| `crm.lead.delete` | `{ id }` | `{ id }` | **pending** — no UI yet; include only if requested |
|
||
|
||
**`crm.lead.create` payload** (union of Quick + Full form, all optional except `firstName`/`lastName` where at least one non-empty):
|
||
```ts
|
||
{
|
||
firstName: string, lastName?: string,
|
||
phones: { number: string, type: "Mobile"|"Home"|"Work", primary?: boolean }[],
|
||
emails?: { address: string, primary?: boolean }[],
|
||
property?: { address?, city?, state?, zip?, type? },
|
||
photos?: { contentRef, mimeType, sizeBytes, filename }[], // real uploads (pending)
|
||
job?: { source?, referralNote?, canvasserId?, leadType?, workType?, tradeType?,
|
||
urgency?: "Standard"|"High"|"Emergency", notes? },
|
||
insurance?: { company?, claimNumber?, claimStatus?, adjusterName?,
|
||
adjusterPhone?, policyNumber? },
|
||
assignment?: { assigneeId?: string|null, priority?: "Low"|"Medium"|"High",
|
||
followUp?: string /* ISO date */ }
|
||
}
|
||
```
|
||
> Note the **priority casing mismatch**: the create form emits `"Low"|"Medium"|"High"` (title-case) while list/detail data uses `"low"|"medium"|"high"`. Normalize to lowercase on write (see §12).
|
||
|
||
### 6.4 Lead Verification — Queries
|
||
|
||
| Action | Variables | Returns | Backs |
|
||
|--------|-----------|---------|-------|
|
||
| `crm.leadVerification.search` | `{ query?, status?, source?, assigneeId?, page?, perPage? }` | `Page<VerificationRowDTO>` | table V3, search V4, filters V5–V7 |
|
||
| `crm.leadVerification.get` | `{ id }` | `VerificationDTO` (+ activities) | detail V16–V18 |
|
||
| `crm.leadVerification.stats` | `{}` | `{ verified, in_progress, assigned, pending, unverified }` | stat tiles V1 |
|
||
| `crm.leadVerification.activity.list` | `{ id }` | `VerificationActivity[]` | timeline V18 (or embed in `.get`) |
|
||
|
||
`VerificationRowDTO`:
|
||
```ts
|
||
{ id, code, name, initials, address, phone, source,
|
||
assignee: { id, initials, name } | null,
|
||
status, verification /* sub_status */, createdAt }
|
||
```
|
||
`VerificationDTO`: adds `email`, `notes`, `verifiedAt`, `promotedLeadId`, `activities[]`.
|
||
|
||
### 6.5 Lead Verification — Commands
|
||
|
||
| Action | Variables | Returns | Backs |
|
||
|--------|-----------|---------|-------|
|
||
| `crm.leadVerification.verify` | `{ id, notes? }` | `{ verification: VerificationDTO, lead: LeadDTO }` | Verify V9/V11/V19 — **promotes to Lead** |
|
||
| `crm.leadVerification.markUnverified` | `{ id, reason? }` | `VerificationDTO` | Mark Unverified V12 |
|
||
| `crm.leadVerification.assign` | `{ id, assigneeId }` | `VerificationDTO` | Change Assignee V13 |
|
||
| `crm.leadVerification.reassign` | `{ id, assigneeId? }` | `VerificationDTO` | Reassign → In Progress V14 |
|
||
| `crm.leadVerification.moveToPending` | `{ id }` | `VerificationDTO` | Move to Pending V15 |
|
||
| `crm.leadVerification.updateStatus` | `{ id, status, subStatus? }` | `VerificationDTO` | generic status set (covers sub-status changes) |
|
||
| `crm.leadVerification.note.add` | `{ id, text }` | `VerificationDTO` | verification notes (pending edit UI) |
|
||
|
||
**`crm.leadVerification.verify` behaviour (the critical cross-module command):**
|
||
1. Load verification; guard status is not already `verified`.
|
||
2. Set `status = 'verified'`, `sub_status = 'Verified'`, `verified_at = now()`, persist `notes` if provided.
|
||
3. **Create a `leads` row** (`status = 'new'`) from the verification's contact/address/source, linking `leads.source_verification_id = verification.id` and `verification.promoted_lead_id = lead.id`.
|
||
4. Append activity: `"Verified and pushed to New Leads."` (actor = current user).
|
||
5. Return both records so the UI can refresh both queues.
|
||
6. Idempotent: a second call with the same idempotency key must not create a duplicate Lead.
|
||
|
||
### 6.6 Shared / reused actions (already exist — reuse, don't rebuild)
|
||
|
||
| Action | Use in Leads/Verification |
|
||
|--------|---------------------------|
|
||
| `crm.account.me` | `leads.manage` permission gate for both modules |
|
||
| `crm.team.member.search { perPage }` | rep / canvasser / assignee pickers (`REPS`, `V_ASSIGNEES`) |
|
||
| `crm.media.presignUpload { mime, sizeBytes }` → `{ objectKey, uploadUrl }` | site-photo upload (browser PUTs bytes directly) |
|
||
| `crm.media.presignDownload { contentRef }` → `{ url }` | render/download a lead photo |
|
||
|
||
---
|
||
|
||
## 7. Validation Rules
|
||
|
||
### 7.1 `crm.lead.create` / `crm.lead.update`
|
||
|
||
| Field | Required | Rule |
|
||
|-------|----------|------|
|
||
| name (`firstName`/`lastName`) | **Yes** (at least one non-empty after trim) | matches the only current UI guard: `` `${first} ${last}`.trim() `` must be non-empty → else error `name_required` |
|
||
| `phones[].number` | No | free-form; if present, strip to digits server-side for storage/dedupe (form already does `phone.replace(/\D/g,"")` in registration) |
|
||
| `phones[].type` | with phone | enum `Mobile\|Home\|Work` |
|
||
| `phones` primary | — | at most one `primary: true`; if none set, mark the first as primary |
|
||
| `emails[].address` | No | RFC-5322-ish email format when present |
|
||
| `property.state` | No | 2-letter US state; default `TX` |
|
||
| `property.zip` | No | 5-digit (or ZIP+4) when present |
|
||
| `property.type` | No | one of `PROPERTY_TYPES` (§8.4) |
|
||
| `source` | No | one of `LEAD_SOURCES` (§8.1) |
|
||
| `referralNote` | Conditional | accept only when `source = 'Referral'` (UI shows it only then) |
|
||
| `canvasserId` | Conditional | resolve to a member; UI surfaces the picker only when `source = 'Door Knock'`, but accept whenever provided |
|
||
| `leadType` | No | see §12 enum conflict — accept the UI's `Residential\|Commercial\|Multi-Family` **and** the data model's `Insurance\|Retail`; store raw, do not hard-reject |
|
||
| `workType` | No | one of `WORK_TYPES` |
|
||
| `tradeType` | No | one of `TRADE_TYPES` |
|
||
| `urgency` | No | enum `Standard\|High\|Emergency`; default `Standard` |
|
||
| `insurance.claimStatus` | No | enum `Not Filed\|Filed\|Approved\|Paid\|Denied` |
|
||
| `priority` | No | accept `Low\|Medium\|High` (form) → normalize to `low\|medium\|high`; default `medium` |
|
||
| `assignment.followUp` | No | valid ISO date; may be null/`"—"` |
|
||
| `assignment.assigneeId` | No | resolve to a member or `null` (Unassigned) |
|
||
|
||
**Business validations:**
|
||
- `code` (`SAL-###`) is server-generated, unique per tenant — never accepted from the client.
|
||
- Duplicate detection (recommended, not in UI): warn (not block) if an active lead exists with the same primary phone **or** same property address within the tenant.
|
||
- All member references (`assigneeId`, `canvasserId`) must belong to the same tenant.
|
||
|
||
### 7.2 Verification commands
|
||
|
||
| Command | Rule |
|
||
|---------|------|
|
||
| `verify` | reject if already `verified` (`already_verified`); require the record exists in tenant; create exactly one Lead (idempotent) |
|
||
| `assign` / `reassign` | `assigneeId` must be a tenant member; `assign` moves `pending → assigned` (or updates assignee); `reassign` sets `in_progress` |
|
||
| `markUnverified` | allowed from any non-terminal state; optional `reason` recorded as activity |
|
||
| `moveToPending` | allowed from `assigned` / `in_progress`; clears/keeps assignee per product choice (UI does not specify — keep assignee, set `status=pending`, `sub_status='Pending Review'`) |
|
||
| `updateStatus` | `status ∈ verification_status`; if `subStatus` omitted, default it from the status (§8.6 mapping) |
|
||
| `note.add` | `text` non-empty, trimmed, reasonable max length (e.g. 5 000 chars) |
|
||
|
||
**Enums must be validated server-side even though the frontend does not enforce them** — the frontend is permissive (free selects), so the backend is the source of truth.
|
||
|
||
---
|
||
|
||
## 8. Reference / Enum Data
|
||
|
||
Exact values, copied from `leads-data.ts` and `verify-data.ts`. Provide these either as DB enums or as a reference-data query (`crm.lead.options` — optional) so the UI selects stay in sync.
|
||
|
||
### 8.1 `LEAD_SOURCES`
|
||
`Door Knock`, `Referral`, `Storm Chase`, `Mailer / Postcard`, `Sign Call`, `Insurance Agent Referral`, `Repeat Customer`, `Social Media`, `Other`
|
||
|
||
### 8.2 `WORK_TYPES`
|
||
`Roof Replacement`, `Roof Repair`, `Inspection`, `Gutter Install`
|
||
|
||
### 8.3 `TRADE_TYPES`
|
||
`Roofing`, `Gutters`, `Siding`, `Windows`
|
||
|
||
### 8.4 `PROPERTY_TYPES`
|
||
`Single Family`, `Multi Family`, `Commercial`
|
||
*(the Full-form Property step also offers `Residential`, `Commercial`, `Multi-Family`, `Industrial` via `PROPERTY_TYPE_OPTS` — accept the superset; see §12)*
|
||
|
||
### 8.5 `CLAIM_STATUSES`
|
||
`Not Filed`, `Filed`, `Approved`, `Paid`, `Denied`
|
||
|
||
### 8.6 Verification statuses → default sub-status label
|
||
|
||
| `status` | default `sub_status` | other observed sub-status labels |
|
||
|----------|----------------------|----------------------------------|
|
||
| `verified` | `Verified` | — |
|
||
| `in_progress` | `Verifying Identity` | `Reviewing Insurance`, `Confirming Ownership`, `Confirming Damage` |
|
||
| `assigned` | `Assigned` | — |
|
||
| `pending` | `Pending Review` | — |
|
||
| `unverified` | `Unverified` | — |
|
||
|
||
### 8.7 Verification sources (`V_SOURCES`)
|
||
`Door Knock`, `Web Form`, `Storm Canvass`, `Referral`, `Call-In`
|
||
*(note: different set from Lead sources §8.1 — keep them as separate reference lists)*
|
||
|
||
### 8.8 Lead statuses / priorities / urgency
|
||
- `lead_status`: `new`, `contacted`, `appointed`, `closed`
|
||
- `lead_priority`: `high`, `medium`, `low` (create form emits title-case `Low`/`Medium`/`High`)
|
||
- `lead_urgency`: `Standard`, `High`, `Emergency`
|
||
- `phone_type`: `Mobile`, `Home`, `Work`
|
||
- `lead_type`: **conflicting** — `Insurance`/`Retail` (data) vs `Residential`/`Commercial`/`Multi-Family` (form). See §12.
|
||
|
||
### 8.9 Seed members (reps / canvassers / verification specialists)
|
||
|
||
Reps (`REPS`, ids are real member codes): `LUP-1040 Cody Tatum`, `LUP-1041 Hannah Reyes`, `LUP-1042 Travis Boone`, `LUP-1043 Shelby Greer`, `LUP-1044 Dalton Pruitt`.
|
||
Verification specialists (`V_ASSIGNEES`): `Wade Hollis`, `Darlene Brooks`, `Roy Schaefer`.
|
||
|
||
---
|
||
|
||
## 9. Backend Services
|
||
|
||
Break the implementation into services mirroring the existing `be-crm` module layout (one bounded context per data-door namespace).
|
||
|
||
| Service | Namespace | Responsibilities |
|
||
|---------|-----------|------------------|
|
||
| **LeadService** | `crm.lead.*` | CRUD + search + stats for leads; owns phones/emails child collections; code generation (`SAL-###`); status transitions; assignment. |
|
||
| **LeadVerificationService** | `crm.leadVerification.*` | Verification queue search/stats; status & sub-status transitions; assign/reassign/pending; note management; code generation (`LD-V-###`). |
|
||
| **LeadPromotionService** (or a method on LeadVerificationService) | part of `crm.leadVerification.verify` | The cross-module promotion: verified verification → new Lead, bidirectional linking, idempotency. Owns the transaction that touches both `leads` and `lead_verifications`. |
|
||
| **LeadActivityService** | activities/history | Append + list `lead_verification_activities` and `lead_status_history`; generates the timeline the UI reads (replaces the client-side `buildActivity` synthesis). |
|
||
| **LeadAssignmentService** | assignment concerns | Resolve member ids for `assignedTo` / `canvasser` / `assignee`; validate tenant membership; (future) round-robin. Can be a thin helper over the existing member/team module rather than a standalone service. |
|
||
| **MediaService (existing — reuse)** | `crm.media.*` | Presign upload/download for site photos. **Do not reimplement** — see media-api.ts. |
|
||
| **Account/AccessService (existing — reuse)** | `crm.account.me` | `leads.manage` authorization for every action here. |
|
||
| **NotificationService** — `[Backend Pending]` | — | The frontend today only toasts locally. No server notification is required for parity, but promotion/verify events are natural triggers if/when the Inbox projection (`crm.inbox.*`) should surface them. Do not build unless requested. |
|
||
|
||
**Layering convention (match existing modules):** Controller/handler (validates action variables, applies auth) → Service (business rules, transitions) → Repository (tenant-scoped data access). DTO projections are shaped for the UI (list vs detail) exactly as the current modules return purpose-built DTOs (e.g. `MemberDTO`, `MailThread`).
|
||
|
||
---
|
||
|
||
## 10. Error Handling
|
||
|
||
Errors propagate to the UI as a thrown `Error`; the SDK hooks expose `error.message` (see `q.error?.message ?? null` throughout the API layer). Permission failures use the SDK's `PermissionError` (OPA). Provide a **stable machine `code` + human `message`**; the UI currently shows the message in a toast/inline state.
|
||
|
||
| Scenario | When | Suggested code | HTTP-equivalent | UI effect |
|
||
|----------|------|----------------|-----------------|-----------|
|
||
| Unauthenticated | no/expired session | `unauthenticated` | 401 | `auth-gate` redirects to `/portal/login` |
|
||
| Forbidden | member lacks `leads.manage` | `forbidden` / `PermissionError` | 403 | nav item hidden; action rejected |
|
||
| Validation — name required | create with empty name | `name_required` | 422 | matches current client guard toast |
|
||
| Validation — bad enum | invalid status/source/type | `invalid_value` | 422 | inline/toast |
|
||
| Validation — bad email/zip/phone | format fails | `invalid_format` | 422 | |
|
||
| Not found | unknown `id` / wrong tenant | `not_found` | 404 | toast; row disappears on refetch |
|
||
| Conflict — already verified | `verify` on a verified record | `already_verified` | 409 | toast |
|
||
| Conflict — invalid transition | disallowed status change | `invalid_state_transition` | 409 | toast |
|
||
| Conflict — duplicate lead | dup phone/address (if enforced) | `duplicate_lead` | 409 | warn (prefer soft-warn, not block) |
|
||
| Conflict — duplicate code | code collision (should be internal) | `duplicate_code` | 409 | internal retry |
|
||
| Assignee invalid | assignee not a tenant member | `invalid_assignee` | 422 | toast |
|
||
| Upload too large | photo > 25 MB | `file_too_large` | 413 | matches media-api guard ("max 25 MB") |
|
||
| Upload failed | presigned PUT fails | `upload_failed` | 502 | toast |
|
||
| Rate / idempotency replay | duplicate command key | (return original result) | 200 | no-op, safe |
|
||
| Server error | unexpected | `internal_error` | 500 | generic toast |
|
||
|
||
**Error envelope (recommended, consistent with a thrown Error carrying structured data):**
|
||
```json
|
||
{ "error": { "code": "already_verified",
|
||
"message": "This lead has already been verified.",
|
||
"details": { "verificationId": "lv_1…" } } }
|
||
```
|
||
|
||
---
|
||
|
||
## 11. Existing Backend Integration (mandatory conventions)
|
||
|
||
The new backend **must** follow the patterns already used by Team, Mail, Inbox, Messenger, Media and Account. Never invent a different architecture.
|
||
|
||
### 11.1 Data door, not REST
|
||
The frontend never calls REST endpoints. It calls **actions** through the AppShell SDK:
|
||
```ts
|
||
// read
|
||
const q = useQuery<Page<LeadCardDTO>>("crm.lead.search", { status, query, page, perPage });
|
||
// write
|
||
await sdk.command("crm.leadVerification.verify", { id, notes });
|
||
```
|
||
`DataClient.query(action, variables)` and `DataClient.command(action, variables)` call the **Shell BFF's cookie-authed `/data` proxy**; the BFF attaches the session token server-side and forwards to `be-crm`. Apps never hold a token, set an `Authorization` header, or know the domain endpoint.
|
||
|
||
### 11.2 Transport path
|
||
```
|
||
browser (SDK) ──► Next rewrite /shell/:path* ──► BFF (BFF_ORIGIN, default http://localhost:4000)/api/:path* ──► be-crm domain API
|
||
```
|
||
(from `next.config.ts` `rewrites()` and `providers.tsx` `bffBaseUrl = "/shell"`). The session is an **HttpOnly cookie**; that is why the same-origin `/shell` prefix is used (never `/api`, to avoid clobbering the local `/api/geo` route).
|
||
|
||
### 11.3 Authentication & authorization
|
||
- Auth is Supabase-backed via the SDK (`appId: "crm-web"`); the BFF exchanges it for a domain session. When `NEXT_PUBLIC_SUPABASE_URL` is unset the app runs in **mock mode** (see §11.6).
|
||
- Authorization is **permission-based** via `crm.account.me` → `{ registered, isMember, roleSlugs, permissions, isSuperadmin }`. Both modules require **`leads.manage`** (already declared in `access.ts` `ALL_CRM_PERMISSIONS` and mapped in `sidebar.tsx` `NAV_PERMISSION`). Enforce it on **every** `crm.lead.*` and `crm.leadVerification.*` action — the frontend gate is UX-only ("be-crm still enforces every action").
|
||
- OPA/IIOS may additionally gate row visibility; keep everything **tenant-scoped**.
|
||
|
||
### 11.4 Response & naming conventions
|
||
- **Actions:** `crm.<entity>.<verb>` dot-namespaced; segments camelCase (e.g. `member.setRoles`, `invitation.create`, `inbox.transition`, `mail.reply`). Use `search`/`list` for reads, imperative verbs for writes.
|
||
- **DTOs:** server returns UI-shaped DTOs (list vs detail projections). Fields are **camelCase**. Timestamps are **ISO-8601 strings**; the client formats relative/pretty (`relTime`). Nullable fields are `null`, not omitted, where the UI reads them.
|
||
- **Collections:** `{ items: T[], meta: { total, page, perPage } }` for paginated sets (Team pattern) — used here for `search`. Bare arrays are acceptable for small always-full lists (Mail/Inbox pattern) but Leads/Verification use the envelope for totals.
|
||
- **Commands** are idempotent (idempotency key auto-attached); write-then-refetch is the client norm (`cmd(...)` then `refetch()`), so commands should return the updated entity to allow optimistic UI too.
|
||
|
||
### 11.5 Media / attachments (reuse exactly)
|
||
Site photos must use the existing two-step flow (from `media-api.ts`):
|
||
1. `sdk.command("crm.media.presignUpload", { mime, sizeBytes })` → `{ objectKey, uploadUrl }`.
|
||
2. Browser `PUT`s the file bytes **directly** to `uploadUrl` (IIOS storage) — be-crm only mints the URL.
|
||
3. Store `{ contentRef: objectKey, mimeType, sizeBytes, filename }` on the lead via `crm.lead.attachment.add`.
|
||
4. Display via `crm.media.presignDownload { contentRef }` → `{ url }`.
|
||
Enforce the **25 MB** cap (`MAX_ATTACHMENT_BYTES = 26_214_400`).
|
||
|
||
### 11.6 Mock-mode parity (important)
|
||
Every existing data-layer file (`team-api`, `mail-api`, `inbox-api`, `messenger-api`, `access`) chooses **mock vs live at module load** via `isShellConfigured()` (`Boolean(process.env.NEXT_PUBLIC_SUPABASE_URL)`). When you wire Leads/Verification to the live door, follow the same shape: create `src/lib/leads-api.ts` and `src/lib/verify-api.ts` exposing one hook per module that returns `{ live, loading, error, …data, …commands, refetch }`, serving the current mock (`LEADS`, `V_LEADS`) when the Shell isn't configured and the live `crm.lead.*` / `crm.leadVerification.*` actions when it is. This keeps the demo working and matches the established convention. *(Frontend wiring task — noted for completeness; the backend itself only needs to implement the live actions.)*
|
||
|
||
### 11.7 DTO / repository / service pattern summary
|
||
- **DTO:** dedicated interfaces per projection (`LeadCardDTO`, `LeadDTO`, `VerificationRowDTO`, `VerificationDTO`) — do not leak raw table rows.
|
||
- **Repository:** always parameterize by `tenantId`; never a query without tenant scope.
|
||
- **Service:** owns transitions, code generation, promotion transaction, activity emission.
|
||
- **Controller/handler:** maps the action name + variables to a service call, validates, applies auth. One handler per action, matching the `crm.<entity>.<verb>` registry the BFF forwards to.
|
||
|
||
---
|
||
|
||
## 12. Gaps, Discrepancies & Backend-Pending Items
|
||
|
||
Explicitly flagged so the backend developer is not surprised.
|
||
|
||
1. **Everything is mock today.** No `crm.lead.*` or `crm.leadVerification.*` action is called anywhere yet. All actions in §6 are new. Frontend wiring (§11.6) is a separate follow-up task.
|
||
|
||
2. **`leadType` enum conflict.** `leads-data.ts` defines `LEAD_TYPES = ["Insurance","Retail"]` and mock rows use `"Insurance"`, but the Full-form Job step's `LEAD_TYPE_OPTS = ["Residential","Commercial","Multi-Family"]`. **Recommendation:** store `lead_type` as free text (do not hard-reject), accept both sets, and raise with product which taxonomy is canonical. **[Needs product decision]**
|
||
|
||
3. **`propertyType` superset.** `PROPERTY_TYPES` (data) = `Single Family / Multi Family / Commercial`; the form offers `Residential / Commercial / Multi-Family / Industrial`. Accept the union.
|
||
|
||
4. **Priority casing.** Create form emits `Low/Medium/High`; list/detail use `low/medium/high`. **Normalize to lowercase** on write; return lowercase.
|
||
|
||
5. **Assignee/canvasser/creator are free-text names in the mock** (`"Jesus Gonzales"`, `"Cody Tatum"`, `"Wade Hollis"`). The backend must model these as **member FKs** and resolve display names in DTOs. The verification specialists (`Wade Hollis`, `Darlene Brooks`, `Roy Schaefer`) are not in the `REPS` list — they must exist as members/records too. **[Seed/link required]**
|
||
|
||
6. **Site photos are placeholders.** `addPhoto()` stores label strings (`"Photo 1"`). Real upload via the media presign flow (§11.5) is **backend-pending** but fully specified.
|
||
|
||
7. **Detail actions are inert.** Leads "Call / Email / Update Status" and Verification "Call / Verify" footer buttons have **no handlers**. `updateStatus`, `verify` etc. are specified in §6 but the buttons must be wired (frontend task).
|
||
|
||
8. **Activity timeline is client-synthesized.** `buildActivity()` fabricates timeline entries when a verification lacks `activity[]`. The backend should persist **real** activities (`lead_verification_activities`) and the client should stop synthesizing once live.
|
||
|
||
9. **No pagination controls in the UI**, yet `TOTAL_LEADS = 35` (only 5 loaded) and the verification footer shows "X of Y". Implement server pagination + `meta.total`; pick a sane default `perPage`. A pager UI is a future frontend task.
|
||
|
||
10. **No edit / delete / archive / bulk / tags-editor / sort UI.** Endpoints for update/archive/delete are included as **optional/pending** — implement `crm.lead.update` (needed for status/assignment) but treat `archive`/`delete`/bulk as **do-not-build-unless-requested**.
|
||
|
||
11. **Verification records are never created from the UI** (like the Inbox, they "arrive"). Provide an intake ingestion path (webhook / internal command) **outside** these two module screens — its exact source is not defined by the frontend. **[Needs definition]**
|
||
|
||
12. **Single-line vs structured address.** Leads store structured address (address/city/state/zip); verifications store a single `address` string (`"2814 Ravenswood Dr, Plano, TX 75023"`). When promoting a verification → lead, parse or carry the single string into `property_address` (best-effort parse; keep the raw string too). **[Parsing rule needed]**
|
||
|
||
---
|
||
|
||
*End of document.*
|