task-d.5

task-d.5.1

docs/implementation/task-d5-lead-enquiry-domain-separation.md

@@ -0,0 +1,134 @@
+# 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