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

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