task-d.5.2.1

plans/task-d.5.2.md

@@ -0,0 +1,489 @@
+# Task D.5.2: Lead Domain Service & API Foundation
+
+## Status
+
+Planned
+
+## Objective
+
+Build the production Lead service layer and API foundation on top of the existing D.5.1 Lead Foundation.
+
+This task introduces Lead as a first-class CRM domain without changing assignment workflows, dashboard datasets, reports, or legacy enquiry behavior.
+
+The objective is to:
+
+* establish Lead service architecture
+* establish Lead API contracts
+* establish Lead security boundaries
+* establish Lead follow-up lifecycle handling
+* prepare D.5.3 Lead Assignment → Create Enquiry
+
+---
+
+## Mandatory Review
+
+Review before implementation:
+
+* `AGENTS.md`
+* `docs/standards/project-foundations.md`
+* `docs/standards/task-catalog.md`
+* `docs/adr/0018-lead-enquiry-domain-separation.md`
+* `docs/implementation/task-d5-lead-enquiry-domain-separation.md`
+* `docs/implementation/task-d51-lead-foundation-stabilization-output-completion.md`
+* Customer Ownership Foundation
+* Authorization Foundation
+* Audit Foundation
+* Master Option Foundation
+* Document Sequence Foundation
+
+---
+
+## Foundation Rules
+
+The following already exist and must be reused:
+
+```txt
+crm_leads
+crm_enquiries.lead_id
+
+crm_lead_awareness
+crm_lead_status
+crm_lead_followup_status
+crm_lead_lost_reason
+
+crm_lead document sequence
+crm_enquiry document sequence
+```
+
+Do not recreate:
+
+```txt
+tables
+migrations
+seed categories
+document sequence configuration
+```
+
+---
+
+## Scope D5.2.1 Lead Service Layer
+
+Create:
+
+```txt
+src/features/crm/leads/server/service.ts
+```
+
+Required operations:
+
+```txt
+listLeads()
+getLeadById()
+createLead()
+updateLead()
+deleteLead()
+```
+
+Rules:
+
+* Use `crm_leads` as the Lead source of truth
+* No direct DB access from route handlers
+* Keep legacy enquiry behavior unchanged
+* Do not create enquiry from lead in this task
+
+Reuse:
+
+```txt
+Customer Foundation
+Audit Foundation
+Authorization Foundation
+Document Sequence Foundation
+Master Option Foundation
+```
+
+---
+
+## Scope D5.2.2 Lead DTO Contracts
+
+Create:
+
+```txt
+src/features/crm/leads/types.ts
+```
+
+Request contracts:
+
+```txt
+CreateLeadInput
+UpdateLeadInput
+LeadListFilters
+CreateLeadFollowupInput
+```
+
+Response contracts:
+
+```txt
+LeadSummary
+LeadDetail
+LeadListResponse
+LeadFollowupSummary
+```
+
+Lead Detail must include:
+
+```txt
+suggestedSalesOwnerId
+```
+
+when customer owner exists.
+
+Important:
+
+```txt
+Do not auto assign.
+Do not create enquiry.
+This is suggestion only.
+```
+
+---
+
+## Scope D5.2.3 Lead Code Generation
+
+Use existing document sequence foundation.
+
+Document type:
+
+```txt
+crm_lead
+```
+
+Expected format:
+
+```txt
+LD2606-001
+```
+
+No custom numbering logic allowed.
+
+---
+
+## Scope D5.2.4 Lead API Routes
+
+Create:
+
+```txt
+GET    /api/crm/leads
+POST   /api/crm/leads
+
+GET    /api/crm/leads/[id]
+PATCH  /api/crm/leads/[id]
+DELETE /api/crm/leads/[id]
+```
+
+Routes must call:
+
+```txt
+Lead Service Layer
+```
+
+Route handlers must not query Drizzle directly.
+
+---
+
+## Scope D5.2.5 Lead Follow-up Foundation
+
+Create:
+
+```txt
+GET  /api/crm/leads/[id]/followups
+POST /api/crm/leads/[id]/followups
+```
+
+Rules:
+
+* Reuse existing CRM follow-up pattern
+* Do not create a second follow-up architecture
+* Use lead follow-up status from master options
+* Keep follow-up scoped to organization and CRM access
+
+---
+
+## Scope D5.2.6 Lead Security
+
+Reuse:
+
+```txt
+resolveCrmMembershipAccess()
+```
+
+Visibility:
+
+Marketing:
+
+```txt
+own leads
+```
+
+Managers:
+
+```txt
+team scope
+```
+
+Admins:
+
+```txt
+organization scope
+```
+
+Rules:
+
+* Do not check role strings directly
+* Use resolved CRM access
+* Enforce security in service layer
+* UI visibility alone is not enough
+
+---
+
+## Scope D5.2.7 Customer Ownership Integration
+
+When customer owner exists:
+
+```txt
+customer.ownerUserId
+```
+
+Return:
+
+```txt
+suggestedSalesOwnerId
+```
+
+in Lead Detail.
+
+Important:
+
+* Do not auto assign
+* Do not create enquiry
+* Do not update `crm_enquiries`
+* This is suggestion only
+
+---
+
+## Scope D5.2.8 Master Option Integration
+
+Lead APIs must expose options through existing master-option infrastructure:
+
+```txt
+awareness
+status
+followupStatus
+lostReason
+```
+
+Use categories:
+
+```txt
+crm_lead_awareness
+crm_lead_status
+crm_lead_followup_status
+crm_lead_lost_reason
+```
+
+Rules:
+
+* No hardcoded labels
+* Option values must come from foundation master options
+* Keep inactive options hidden from normal API responses unless explicitly requested
+
+---
+
+## Scope D5.2.9 Audit Logging
+
+Reuse:
+
+```txt
+auditCreate()
+auditUpdate()
+auditDelete()
+auditAction()
+```
+
+Required audit actions:
+
+```txt
+create_lead
+update_lead
+delete_lead
+view_lead
+create_lead_followup
+```
+
+Rules:
+
+* Audit every mutation
+* Audit lead detail view if existing audit convention supports view logging
+* Do not introduce a separate audit pattern
+
+---
+
+## Scope D5.2.10 Legacy Compatibility
+
+Keep current system operational.
+
+Current legacy behavior:
+
+```txt
+crm_enquiries.pipeline_stage
+```
+
+must remain untouched.
+
+Do not:
+
+```txt
+change enquiry services
+change assignment flow
+change dashboard
+change reports
+change won/lost synchronization
+```
+
+Those belong to later D.5 phases.
+
+---
+
+## Deliverables
+
+New:
+
+```txt
+src/features/crm/leads/**
+```
+
+New APIs:
+
+```txt
+/api/crm/leads
+/api/crm/leads/[id]
+/api/crm/leads/[id]/followups
+```
+
+Documentation:
+
+```txt
+docs/implementation/task-d52-lead-domain-service-api-foundation.md
+```
+
+---
+
+## Expected Outputs
+
+Lead Service:
+
+```txt
+CRUD operational
+```
+
+Lead API:
+
+```txt
+CRUD operational
+```
+
+Lead Follow-up:
+
+```txt
+API operational
+```
+
+Security:
+
+```txt
+resolved CRM access enforced
+```
+
+Audit:
+
+```txt
+lead actions recorded
+```
+
+Legacy CRM:
+
+```txt
+unchanged
+```
+
+---
+
+## Explicit Non-Scope
+
+Do not:
+
+* create Lead UI
+* create Lead assignment flow
+* create Lead → Enquiry conversion
+* create Enquiry from Lead
+* update dashboard
+* update reports
+* migrate legacy data
+* remove `pipeline_stage`
+* change existing enquiry APIs
+* change quotation conversion behavior
+
+These belong to:
+
+```txt
+D.5.3+
+```
+
+---
+
+## Verification
+
+Run:
+
+```txt
+npm exec tsc --noEmit
+```
+
+Verify:
+
+```txt
+Create Lead
+Update Lead
+Delete Lead
+View Lead
+List Lead
+Lead code generation
+Lead follow-up creation
+Lead follow-up listing
+Audit logging
+Current Enquiry APIs still function
+Current Dashboard still functions
+Current Reports still function
+```
+
+---
+
+## Definition of Done
+
+Task is complete when:
+
+* Lead service layer exists
+* Lead CRUD APIs exist
+* Lead follow-up APIs exist
+* Lead security uses resolved CRM access
+* Lead code generation uses sequence foundation
+* Lead master options use foundation categories
+* Audit logging exists
+* Existing CRM functionality remains unchanged
+
+Result:
+
+```txt
+Lead Domain Service = Established
+Lead API Foundation = Established
+Ready for D.5.3 Lead Assignment → Create Enquiry
+```