lead menu

nquiry menu

docs/adr/0011-lead-enquiry-ownership-model.md

@@ -0,0 +1,131 @@
+# 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.