490 lines
6.6 KiB
Markdown
490 lines
6.6 KiB
Markdown
# 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
|
|
```
|