# Task D.5.2: Lead Domain Service & API Foundation

## Status

Planned

## Objective

Build the production Lead service layer and API foundation on top of the existing D.5.1 Lead Foundation.

This task introduces Lead as a first-class CRM domain without changing assignment workflows, dashboard datasets, reports, or legacy enquiry behavior.

The objective is to:

* establish Lead service architecture
* establish Lead API contracts
* establish Lead security boundaries
* establish Lead follow-up lifecycle handling
* prepare D.5.3 Lead Assignment → Create Enquiry

---

## Mandatory Review

Review before implementation:

* `AGENTS.md`
* `docs/standards/project-foundations.md`
* `docs/standards/task-catalog.md`
* `docs/adr/0018-lead-enquiry-domain-separation.md`
* `docs/implementation/task-d5-lead-enquiry-domain-separation.md`
* `docs/implementation/task-d51-lead-foundation-stabilization-output-completion.md`
* Customer Ownership Foundation
* Authorization Foundation
* Audit Foundation
* Master Option Foundation
* Document Sequence Foundation

---

## Foundation Rules

The following already exist and must be reused:

```txt
crm_leads
crm_enquiries.lead_id

crm_lead_awareness
crm_lead_status
crm_lead_followup_status
crm_lead_lost_reason

crm_lead document sequence
crm_enquiry document sequence
```

Do not recreate:

```txt
tables
migrations
seed categories
document sequence configuration
```

---

## Scope D5.2.1 Lead Service Layer

Create:

```txt
src/features/crm/leads/server/service.ts
```

Required operations:

```txt
listLeads()
getLeadById()
createLead()
updateLead()
deleteLead()
```

Rules:

* Use `crm_leads` as the Lead source of truth
* No direct DB access from route handlers
* Keep legacy enquiry behavior unchanged
* Do not create enquiry from lead in this task

Reuse:

```txt
Customer Foundation
Audit Foundation
Authorization Foundation
Document Sequence Foundation
Master Option Foundation
```

---

## Scope D5.2.2 Lead DTO Contracts

Create:

```txt
src/features/crm/leads/types.ts
```

Request contracts:

```txt
CreateLeadInput
UpdateLeadInput
LeadListFilters
CreateLeadFollowupInput
```

Response contracts:

```txt
LeadSummary
LeadDetail
LeadListResponse
LeadFollowupSummary
```

Lead Detail must include:

```txt
suggestedSalesOwnerId
```

when customer owner exists.

Important:

```txt
Do not auto assign.
Do not create enquiry.
This is suggestion only.
```

---

## Scope D5.2.3 Lead Code Generation

Use existing document sequence foundation.

Document type:

```txt
crm_lead
```

Expected format:

```txt
LD2606-001
```

No custom numbering logic allowed.

---

## Scope D5.2.4 Lead API Routes

Create:

```txt
GET    /api/crm/leads
POST   /api/crm/leads

GET    /api/crm/leads/[id]
PATCH  /api/crm/leads/[id]
DELETE /api/crm/leads/[id]
```

Routes must call:

```txt
Lead Service Layer
```

Route handlers must not query Drizzle directly.

---

## Scope D5.2.5 Lead Follow-up Foundation

Create:

```txt
GET  /api/crm/leads/[id]/followups
POST /api/crm/leads/[id]/followups
```

Rules:

* Reuse existing CRM follow-up pattern
* Do not create a second follow-up architecture
* Use lead follow-up status from master options
* Keep follow-up scoped to organization and CRM access

---

## Scope D5.2.6 Lead Security

Reuse:

```txt
resolveCrmMembershipAccess()
```

Visibility:

Marketing:

```txt
own leads
```

Managers:

```txt
team scope
```

Admins:

```txt
organization scope
```

Rules:

* Do not check role strings directly
* Use resolved CRM access
* Enforce security in service layer
* UI visibility alone is not enough

---

## Scope D5.2.7 Customer Ownership Integration

When customer owner exists:

```txt
customer.ownerUserId
```

Return:

```txt
suggestedSalesOwnerId
```

in Lead Detail.

Important:

* Do not auto assign
* Do not create enquiry
* Do not update `crm_enquiries`
* This is suggestion only

---

## Scope D5.2.8 Master Option Integration

Lead APIs must expose options through existing master-option infrastructure:

```txt
awareness
status
followupStatus
lostReason
```

Use categories:

```txt
crm_lead_awareness
crm_lead_status
crm_lead_followup_status
crm_lead_lost_reason
```

Rules:

* No hardcoded labels
* Option values must come from foundation master options
* Keep inactive options hidden from normal API responses unless explicitly requested

---

## Scope D5.2.9 Audit Logging

Reuse:

```txt
auditCreate()
auditUpdate()
auditDelete()
auditAction()
```

Required audit actions:

```txt
create_lead
update_lead
delete_lead
view_lead
create_lead_followup
```

Rules:

* Audit every mutation
* Audit lead detail view if existing audit convention supports view logging
* Do not introduce a separate audit pattern

---

## Scope D5.2.10 Legacy Compatibility

Keep current system operational.

Current legacy behavior:

```txt
crm_enquiries.pipeline_stage
```

must remain untouched.

Do not:

```txt
change enquiry services
change assignment flow
change dashboard
change reports
change won/lost synchronization
```

Those belong to later D.5 phases.

---

## Deliverables

New:

```txt
src/features/crm/leads/**
```

New APIs:

```txt
/api/crm/leads
/api/crm/leads/[id]
/api/crm/leads/[id]/followups
```

Documentation:

```txt
docs/implementation/task-d52-lead-domain-service-api-foundation.md
```

---

## Expected Outputs

Lead Service:

```txt
CRUD operational
```

Lead API:

```txt
CRUD operational
```

Lead Follow-up:

```txt
API operational
```

Security:

```txt
resolved CRM access enforced
```

Audit:

```txt
lead actions recorded
```

Legacy CRM:

```txt
unchanged
```

---

## Explicit Non-Scope

Do not:

* create Lead UI
* create Lead assignment flow
* create Lead → Enquiry conversion
* create Enquiry from Lead
* update dashboard
* update reports
* migrate legacy data
* remove `pipeline_stage`
* change existing enquiry APIs
* change quotation conversion behavior

These belong to:

```txt
D.5.3+
```

---

## Verification

Run:

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

Verify:

```txt
Create Lead
Update Lead
Delete Lead
View Lead
List Lead
Lead code generation
Lead follow-up creation
Lead follow-up listing
Audit logging
Current Enquiry APIs still function
Current Dashboard still functions
Current Reports still function
```

---

## Definition of Done

Task is complete when:

* Lead service layer exists
* Lead CRUD APIs exist
* Lead follow-up APIs exist
* Lead security uses resolved CRM access
* Lead code generation uses sequence foundation
* Lead master options use foundation categories
* Audit logging exists
* Existing CRM functionality remains unchanged

Result:

```txt
Lead Domain Service = Established
Lead API Foundation = Established
Ready for D.5.3 Lead Assignment → Create Enquiry
```