135 lines
4.5 KiB
Markdown
135 lines
4.5 KiB
Markdown
# Task D.5: Lead / Enquiry Domain Separation
|
|
|
|
## Status
|
|
|
|
In progress
|
|
|
|
## Objective
|
|
|
|
Replace the current single-record lead/enquiry persistence model with a split domain model that preserves marketing leads independently from sales enquiries.
|
|
|
|
## Review Summary
|
|
|
|
Reviewed before implementation:
|
|
|
|
- `AGENTS.md`
|
|
- `docs/standards/task-contract-template.md`
|
|
- `docs/standards/task-review-checklist.md`
|
|
- `docs/standards/task-catalog.md`
|
|
- `docs/standards/project-foundations.md`
|
|
- `docs/adr/0011-lead-enquiry-ownership-model.md`
|
|
- `docs/adr/0016-won-lost-lifecycle-governance.md`
|
|
- `docs/implementation/task-d3-lead-enquiry-ownership-refinement.md`
|
|
- `docs/implementation/task-d31-leads-enquiries-navigation-separation.md`
|
|
- `docs/implementation/task-d4-won-lost-lifecycle-governance.md`
|
|
- `docs/implementation/task-k2-pipeline-reports.md`
|
|
- `docs/security/crm-authorization-boundaries.md`
|
|
- `src/db/schema.ts`
|
|
- `src/features/crm/enquiries/server/service.ts`
|
|
|
|
## Historical Findings
|
|
|
|
### Current production truth
|
|
|
|
The current production CRM still follows ADR-0011:
|
|
|
|
- `crm_enquiries` is the single source of truth
|
|
- `pipeline_stage` distinguishes `lead`, `enquiry`, `closed_won`, `closed_lost`
|
|
- assigning a lead mutates the same record into an enquiry
|
|
- lead workspace and enquiry workspace are only UX separation
|
|
|
|
### Why D.5 is different
|
|
|
|
Task D.5 explicitly requires:
|
|
|
|
- dedicated `crm_leads`
|
|
- `crm_enquiries.lead_id`
|
|
- `1 Lead -> N Enquiries`
|
|
- direct sales enquiries with nullable `lead_id`
|
|
- dashboard/report split by entity rather than `pipeline_stage`
|
|
|
|
This is not an incremental extension of ADR-0011. It is a domain replacement.
|
|
|
|
## Governance Decision
|
|
|
|
Because Task D.5 conflicts with an accepted ADR, the first implementation step is to add a replacement ADR:
|
|
|
|
- `docs/adr/0018-lead-enquiry-domain-separation.md`
|
|
|
|
This task should not continue with schema or API changes while ADR-0011 remains the only source of truth for this area.
|
|
|
|
## Reuse Constraints
|
|
|
|
The split-domain refactor must still reuse existing foundations rather than rebuilding CRM from scratch:
|
|
|
|
- Audit Foundation for migration and lifecycle actions
|
|
- Master Data Foundation for lead awareness/status/follow-up/lost-reason options
|
|
- Document Sequence Foundation for lead and enquiry code generation
|
|
- Authorization Foundation for visibility and scope rules
|
|
- Dashboard Foundation for KPI composition
|
|
- Reporting Foundation for dataset and export contracts
|
|
- Won / Lost Governance Foundation for enquiry outcome transitions
|
|
|
|
## Phase Plan
|
|
|
|
### Phase 0
|
|
|
|
- freeze ADR-0018
|
|
- document the conflict with ADR-0011
|
|
- define migration boundaries
|
|
|
|
### Phase 1
|
|
|
|
- add `crm_leads`
|
|
- add `crm_enquiries.lead_id`
|
|
- add lead master option categories
|
|
- add lead document sequence type
|
|
|
|
### Phase 2
|
|
|
|
- create dedicated lead services and `/api/crm/leads/**`
|
|
- keep enquiry services focused on sales execution
|
|
- migrate assignment flow from `pipeline_stage` mutation to `lead -> create enquiry`
|
|
|
|
### Phase 3
|
|
|
|
- update dashboard datasets to separate lead/enquiry sources
|
|
- update report datasets and exports to separate lead/enquiry sources
|
|
- preserve quotation, approval, PDF, and pricing foundations
|
|
|
|
### Phase 4
|
|
|
|
- migrate legacy rows from `crm_enquiries.pipeline_stage`
|
|
- preserve follow-ups, project-party relations, attachments, quotations, and audit history
|
|
- remove single-record assumptions from surviving UI and server code
|
|
|
|
## Initial Risks
|
|
|
|
- this task affects schema, services, APIs, dashboard, reports, permissions, and migration logic at once
|
|
- existing lead reports and dashboard KPIs currently depend on `pipeline_stage`
|
|
- current enquiry services bundle lead creation defaults, assignment conversion, and won/lost logic together
|
|
- authorization rules for marketing monitoring are currently described against the shared enquiry table
|
|
|
|
## Deliverables Started
|
|
|
|
- added `docs/adr/0018-lead-enquiry-domain-separation.md`
|
|
- added `docs/implementation/task-d5-lead-enquiry-domain-separation.md`
|
|
|
|
## Next Implementation Slice
|
|
|
|
The next safe code slice is:
|
|
|
|
1. add schema support for `crm_leads` and `crm_enquiries.lead_id`
|
|
2. seed new lead option categories and document sequence configuration
|
|
3. keep existing enquiry routes live while introducing lead-specific route contracts
|
|
|
|
## Verification Target
|
|
|
|
When code phases begin, verification must include:
|
|
|
|
- `npm exec tsc --noEmit`
|
|
- migration validation for existing `crm_enquiries`
|
|
- direct sales enquiry creation with `leadId = null`
|
|
- lead assignment creating enquiries without deleting the lead
|
|
- outcome synchronization from enquiry results back to lead outcome
|