# 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