132 lines
3.5 KiB
Markdown
132 lines
3.5 KiB
Markdown
# 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.
|