# Task D.5.1: Lead Foundation Schema & Compatibility Layer

## Status

Planned

## Objective

Create the foundational schema and compatibility layer required for Lead / Enquiry Domain Separation without breaking the existing CRM workflow.

This task introduces the Lead domain but does not yet migrate business flows.

The objective is to prepare the platform for D.5.2 and later phases while keeping all existing CRM features operational.

---

# Mandatory Review

Review:

* AGENTS.md
* Project Foundations Registry
* Task Catalog
* ADR-0011 Lead / Enquiry Ownership Model
* ADR-0016 Won / Lost Lifecycle Governance
* ADR-0018 Lead / Enquiry Domain Separation
* Task D.3
* Task D.3.1
* Task D.4

---

# Required Skills

## Governance

* AGENTS.md
* Architecture Rules
* Task Contract Template
* Task Review Checklist

## CRM

* Lead / Enquiry Governance
* Won / Lost Governance
* Customer Ownership Governance

## Backend

* Drizzle ORM Pattern
* Service Layer Pattern
* Route Handler Pattern

## Security

* CRM Authorization Foundation

---

# Scope D5.1.1 Create Lead Table

Add:

```txt
crm_leads
```

Initial fields:

```txt
id
organizationId
branchId

code

customerId
contactId

projectName
projectLocation

awarenessId

status
followupStatus
lostReason

outcome

ownerMarketingUserId

createdBy
createdAt
updatedAt
deletedAt
```

---

# Scope D5.1.2 Add Lead Reference to Enquiry

Modify:

```txt
crm_enquiries
```

Add:

```txt
leadId nullable
```

Relationship:

```txt
crm_leads 1
→ N crm_enquiries
```

No business flow changes yet.

---

# Scope D5.1.3 Master Data Foundation

Create categories:

```txt
crm_lead_awareness
crm_lead_status
crm_lead_followup_status
crm_lead_lost_reason
```

Seed:

## crm_lead_awareness

```txt
Google Search / Website
Social Media
Email Marketing
Visit
Exhibition / Event
Brochure / Catalog
Word of Mouth
Corporate Car
Product Label
Re-purchasing
Introducing
BCI
```

## crm_lead_status

```txt
new_job
follow_up
closed_lost
cancel
```

## crm_lead_followup_status

```txt
budget_pending
project_under_review
spec_clarification
site_survey_waiting
drawing_followup
quotation_preparation
waiting_po
```

## crm_lead_lost_reason

```txt
price
delivery_time
sales_person
service
customer
product_quality
other
transfer
```

---

# Scope D5.1.4 Document Sequence Foundation

Register:

```txt
crm_lead
crm_enquiry
```

Document codes:

```txt
Lead:
LD2606-001

Enquiry:
EN2606-001
```

Do not switch existing generation logic yet.

Only prepare configuration.

---

# Scope D5.1.5 Compatibility Layer

Keep existing:

```txt
crm_enquiries.pipeline_stage
```

unchanged.

No route behavior changes.

No dashboard changes.

No report changes.

No migration of existing records.

This task prepares schema only.

---

# Scope D5.1.6 Authorization Preparation

Add placeholders for future Lead permissions:

```txt
crm.lead.read
crm.lead.create
crm.lead.update
crm.lead.assign
crm.lead.delete
```

No enforcement changes yet.

---

# Deliverables

## New

* crm_leads schema
* lead master option categories
* lead document sequence configuration
* ADR-0018 references

---

## Modified

* crm_enquiries
* foundation.seed.ts
* document sequence seed
* CRM permission registry

---

# Explicit Non-Scope

Do NOT:

* create Lead APIs
* create Lead UI
* create Lead assignment workflow
* migrate existing records
* change dashboard
* change reports
* change security behavior
* remove pipeline_stage

Those belong to later D.5 phases.

---

# Verification

Verify:

```txt
npm exec tsc --noEmit
```

Verify:

```txt
crm_leads table exists
```

Verify:

```txt
crm_enquiries.leadId exists
```

Verify:

```txt
lead master options seeded
```

Verify:

```txt
document sequence configuration exists
```

Verify:

```txt
existing CRM workflow remains unchanged
```

---

# Definition of Done

Task is complete when:

* Lead schema exists
* Enquiry can reference Lead
* Lead master data exists
* Lead document sequence exists
* Existing CRM remains fully operational
* No business workflow regression occurs

Result:

Lead Foundation = Established

Compatibility Layer = Established

Ready for D.5.2 Lead APIs & UI