# ADR 0011: Lead and Enquiry Ownership Model

## Status

Accepted

## Context

The CRM module originally used a mixed terminology model where:

- `Lead` meant an unassigned enquiry
- `Opportunity` meant an assigned enquiry

That model no longer matched the business process. The business now distinguishes ownership by function:

- `Lead` is marketing-owned
- `Enquiry` is sales-owned

The system must preserve the single-source-of-truth table `crm_enquiries` while refining lifecycle, permissions, monitoring visibility, and KPI semantics.

## Decision

### 1. Single record model

- `crm_enquiries` remains the single source of truth
- no `crm_leads` table is introduced
- no split lead form or split enquiry API is introduced

### 2. Pipeline stage model

`crm_enquiries.pipeline_stage` is the lifecycle discriminator with allowed values:

- `lead`
- `enquiry`
- `closed_won`
- `closed_lost`

### 3. Ownership model

- `lead` is marketing-owned
- `enquiry` is sales-owned
- assignment converts a lead into an enquiry

### 4. Assignment behavior

On assign:

- `assignedToUserId` is set
- `assignedAt` is set
- `assignedBy` is set
- `pipelineStage` becomes `enquiry`

On reassign:

- assignee metadata is updated
- `pipelineStage` remains `enquiry`

### 5. Create behavior

- marketing-created records default to `pipelineStage = lead`
- sales-created records default to `pipelineStage = enquiry`

### 6. Closure behavior

- lost or cancelled enquiry status resolves to `pipelineStage = closed_lost`
- accepted or lost/rejected quotation outcomes may synchronize the linked enquiry to:
  - `closed_won`
  - `closed_lost`

### 7. Visibility policy

Marketing can monitor:

- leads
- enquiries
- follow-ups
- status
- pipeline stage
- enquiry owner
- won/lost result

Marketing cannot access:

- quotation pricing
- quotation items
- cost, discount, or margin views
- approval analytics or approval workflow data

Sales scope remains ownership-based:

- `sales` and `sales_support` are limited server-side to enquiries they created or are assigned to
- managers and admins retain wider organization visibility

### 8. KPI terminology

User-facing dashboard terminology replaces `Opportunity` with `Enquiry`.

Count definitions:

- `Lead Count` = `pipelineStage = lead`
- `Enquiry Count` = `pipelineStage = enquiry`
- `Won Count` = `pipelineStage = closed_won`
- `Lost Count` = `pipelineStage = closed_lost`

### 9. Navigation Separation

- `Lead` and `Enquiry` are separate UX workspaces
- `Lead` and `Enquiry` are not separate domain entities
- both workspaces continue to use the same `crm_enquiries` records
- `pipelineStage` determines whether a record appears in the Leads or Enquiries workspace
- the navigation split reduces user confusion without duplicating schema, API, or service layers

## Consequences

### Positive

- matches the real business handoff from marketing to sales
- keeps backward-compatible storage in `crm_enquiries`
- removes ambiguous `opportunity` wording from user-facing CRM surfaces
- gives marketing monitoring visibility without exposing commercial data
- enforces own-or-assigned visibility server-side for sales roles

### Tradeoffs

- lifecycle still depends partly on status mapping and quotation outcome synchronization
- the model does not yet include dedicated timestamps such as `closedWonAt` or `closedLostAt`
- reporting still relies on current-state lifecycle fields rather than effective-dated snapshots

## Supersedes

This ADR supersedes the opportunity terminology frozen in `docs/implementation/task-j0-kpi-definition-freeze.md` for user-facing CRM ownership and KPI language.