task-d.5

task-d.5.1

plans/task-d.5.1.md

@@ -0,0 +1,349 @@
+# Task D.5.1: Lead Foundation Schema & Compatibility Layer
+
+## Status
+
+Planned
+
+## Objective
+
+Create the foundational schema and compatibility layer required for Lead / Enquiry Domain Separation without breaking the existing CRM workflow.
+
+This task introduces the Lead domain but does not yet migrate business flows.
+
+The objective is to prepare the platform for D.5.2 and later phases while keeping all existing CRM features operational.
+
+---
+
+# Mandatory Review
+
+Review:
+
+* AGENTS.md
+* Project Foundations Registry
+* Task Catalog
+* ADR-0011 Lead / Enquiry Ownership Model
+* ADR-0016 Won / Lost Lifecycle Governance
+* ADR-0018 Lead / Enquiry Domain Separation
+* Task D.3
+* Task D.3.1
+* Task D.4
+
+---
+
+# Required Skills
+
+## Governance
+
+* AGENTS.md
+* Architecture Rules
+* Task Contract Template
+* Task Review Checklist
+
+## CRM
+
+* Lead / Enquiry Governance
+* Won / Lost Governance
+* Customer Ownership Governance
+
+## Backend
+
+* Drizzle ORM Pattern
+* Service Layer Pattern
+* Route Handler Pattern
+
+## Security
+
+* CRM Authorization Foundation
+
+---
+
+# Scope D5.1.1 Create Lead Table
+
+Add:
+
+```txt
+crm_leads
+```
+
+Initial fields:
+
+```txt
+id
+organizationId
+branchId
+
+code
+
+customerId
+contactId
+
+projectName
+projectLocation
+
+awarenessId
+
+status
+followupStatus
+lostReason
+
+outcome
+
+ownerMarketingUserId
+
+createdBy
+createdAt
+updatedAt
+deletedAt
+```
+
+---
+
+# Scope D5.1.2 Add Lead Reference to Enquiry
+
+Modify:
+
+```txt
+crm_enquiries
+```
+
+Add:
+
+```txt
+leadId nullable
+```
+
+Relationship:
+
+```txt
+crm_leads 1
+→ N crm_enquiries
+```
+
+No business flow changes yet.
+
+---
+
+# Scope D5.1.3 Master Data Foundation
+
+Create categories:
+
+```txt
+crm_lead_awareness
+crm_lead_status
+crm_lead_followup_status
+crm_lead_lost_reason
+```
+
+Seed:
+
+## crm_lead_awareness
+
+```txt
+Google Search / Website
+Social Media
+Email Marketing
+Visit
+Exhibition / Event
+Brochure / Catalog
+Word of Mouth
+Corporate Car
+Product Label
+Re-purchasing
+Introducing
+BCI
+```
+
+## crm_lead_status
+
+```txt
+new_job
+follow_up
+closed_lost
+cancel
+```
+
+## crm_lead_followup_status
+
+```txt
+budget_pending
+project_under_review
+spec_clarification
+site_survey_waiting
+drawing_followup
+quotation_preparation
+waiting_po
+```
+
+## crm_lead_lost_reason
+
+```txt
+price
+delivery_time
+sales_person
+service
+customer
+product_quality
+other
+transfer
+```
+
+---
+
+# Scope D5.1.4 Document Sequence Foundation
+
+Register:
+
+```txt
+crm_lead
+crm_enquiry
+```
+
+Document codes:
+
+```txt
+Lead:
+LD2606-001
+
+Enquiry:
+EN2606-001
+```
+
+Do not switch existing generation logic yet.
+
+Only prepare configuration.
+
+---
+
+# Scope D5.1.5 Compatibility Layer
+
+Keep existing:
+
+```txt
+crm_enquiries.pipeline_stage
+```
+
+unchanged.
+
+No route behavior changes.
+
+No dashboard changes.
+
+No report changes.
+
+No migration of existing records.
+
+This task prepares schema only.
+
+---
+
+# Scope D5.1.6 Authorization Preparation
+
+Add placeholders for future Lead permissions:
+
+```txt
+crm.lead.read
+crm.lead.create
+crm.lead.update
+crm.lead.assign
+crm.lead.delete
+```
+
+No enforcement changes yet.
+
+---
+
+# Deliverables
+
+## New
+
+* crm_leads schema
+* lead master option categories
+* lead document sequence configuration
+* ADR-0018 references
+
+---
+
+## Modified
+
+* crm_enquiries
+* foundation.seed.ts
+* document sequence seed
+* CRM permission registry
+
+---
+
+# Explicit Non-Scope
+
+Do NOT:
+
+* create Lead APIs
+* create Lead UI
+* create Lead assignment workflow
+* migrate existing records
+* change dashboard
+* change reports
+* change security behavior
+* remove pipeline_stage
+
+Those belong to later D.5 phases.
+
+---
+
+# Verification
+
+Verify:
+
+```txt
+npm exec tsc --noEmit
+```
+
+Verify:
+
+```txt
+crm_leads table exists
+```
+
+Verify:
+
+```txt
+crm_enquiries.leadId exists
+```
+
+Verify:
+
+```txt
+lead master options seeded
+```
+
+Verify:
+
+```txt
+document sequence configuration exists
+```
+
+Verify:
+
+```txt
+existing CRM workflow remains unchanged
+```
+
+---
+
+# Definition of Done
+
+Task is complete when:
+
+* Lead schema exists
+* Enquiry can reference Lead
+* Lead master data exists
+* Lead document sequence exists
+* Existing CRM remains fully operational
+* No business workflow regression occurs
+
+Result:
+
+Lead Foundation = Established
+
+Compatibility Layer = Established
+
+Ready for D.5.2 Lead APIs & UI