# ADR 0018: Lead / Enquiry Domain Separation

## Status

Proposed

## Context

ADR-0011 froze the current CRM lifecycle around a single persisted entity:

- `crm_enquiries` stores both marketing-owned leads and sales-owned enquiries
- `pipeline_stage` acts as the discriminator
- navigation separation exists, but domain separation does not

That model was an intentional stabilization step for Tasks D.3 and D.3.1. It reduced UX ambiguity without forcing a schema split during the first production rollout.

Task D.5 introduces a stronger business requirement:

- Marketing owns `Lead` as a dedicated entity
- Sales owns `Enquiry` as a dedicated entity
- one lead may create many enquiries
- sales may also create enquiries directly without a lead
- marketing outcome must be derived from sales execution, not manually controlled

The current single-record model now creates structural ambiguity in at least these areas:

1. Assignment currently mutates one record from `lead -> enquiry`, which destroys the original lead as a stable marketing record.
2. A true `1 Lead -> N Enquiries` relationship cannot be represented cleanly while the lead itself is also the enquiry record.
3. Dashboard and report logic still infer lead analytics from `crm_enquiries.pipeline_stage`, which couples marketing and sales datasets.
4. Outcome synchronization for marketing is harder to reason about because the source marketing entity does not exist independently.

## Decision

We will replace the single-record lead/enquiry persistence model with a split domain model:

- `crm_leads` becomes the dedicated marketing-owned lead table
- `crm_enquiries` remains the dedicated sales-owned enquiry table
- `crm_enquiries.lead_id` becomes nullable to support:
  - lead-origin enquiries
  - direct sales enquiries with `lead_id = null`

### Lifecycle

The target business flow is:

```txt
Lead
-> Enquiry
-> Quotation
-> Won / Lost
```

### Relationship rules

- `crm_leads 1 -> N crm_enquiries`
- `crm_enquiries 1 -> N crm_quotations`
- `crm_quotations` remains the owning record for quotation revisions and child resources

### Ownership rules

- marketing owns lead creation and lead follow-up
- sales owns enquiry creation, enquiry follow-up, quotation generation, and won/lost execution
- managers and admins retain cross-workspace monitoring based on resolved CRM access

### Outcome rules

- lead outcome is derived, never manually updated
- when any linked enquiry becomes won, the lead outcome becomes `won`
- when all linked enquiries are lost, the lead outcome becomes `lost`
- otherwise the lead outcome remains `open`

### Sequence rules

- lead codes use a dedicated lead document sequence
- enquiry codes keep a separate enquiry document sequence

### Reporting and dashboard rules

- lead KPI and lead reports read from `crm_leads`
- enquiry KPI and enquiry reports read from `crm_enquiries`
- no report should continue to treat `pipeline_stage` as the marketing/sales entity boundary after migration

## Consequences

### Positive

- aligns persistence with the real marketing-to-sales handoff
- supports true `1 Lead -> N Enquiries`
- preserves lead identity after assignment
- simplifies marketing analytics and awareness-source reporting
- makes direct sales enquiries first-class without overloading lead semantics

### Tradeoffs

- supersedes a previously accepted ADR and requires broad migration across services, reports, dashboard, and permissions
- requires data migration from existing `crm_enquiries.pipeline_stage`
- increases temporary compatibility complexity during rollout

## Migration Strategy

The migration should be delivered in explicit phases:

1. Introduce ADR and governance freeze for split-domain direction.
2. Add schema and seed support for `crm_leads`, `lead_id`, and lead master options.
3. Introduce lead services and lead APIs without deleting enquiry flows.
4. Migrate dashboard and reports to separated datasets.
5. Remove old single-record assumptions from shared enquiry services and UI.

## Supersedes

This ADR is intended to supersede the following sections of ADR-0011 once implemented:

- `Single record model`
- `Pipeline stage model` as the lead/enquiry persistence boundary
- `Navigation Separation` as the primary separation mechanism

Until implementation is complete, ADR-0011 remains the description of current production behavior, while this ADR defines the approved target direction for Task D.5.