task-d5.5.1

plans/task-d.5.5.1.md

@@ -0,0 +1,470 @@
+# Task D.5.5.1: Force Rename Enquiry Domain to Opportunity
+
+## Status
+
+Breaking Change (Development Only)
+
+## Objective
+
+Perform a full domain rename from **Enquiry** to **Opportunity** across the CRM codebase.
+
+This task intentionally introduces breaking changes and requires a full database reset.
+
+The goal is to eliminate future ambiguity between:
+
+```txt
+Sales Opportunity
+```
+
+and the future business document:
+
+```txt
+Sales Enquiry
+```
+
+After this task:
+
+```txt
+Lead
+    ↓
+Opportunity
+    ↓
+Quotation
+```
+
+becomes the official CRM domain model.
+
+---
+
+# Preconditions
+
+This task assumes:
+
+* Development environment only
+* Existing data may be discarded
+* Database will be dropped
+* Migration history may be regenerated
+* Seed data will be recreated
+
+No production migration compatibility is required.
+
+---
+
+# Mandatory Review
+
+Review:
+
+* AGENTS.md
+* Project Foundations Registry
+* Task Catalog
+* ADR-0018 Lead / Enquiry Domain Separation
+* Task D.5.1 – D.5.5
+* CRM Authorization Boundaries
+* Database schema
+* Navigation configuration
+* Route structure
+
+---
+
+# Scope D5.5.1.1 Database Rename
+
+Rename tables:
+
+```txt
+crm_enquiries
+→ crm_opportunities
+
+crm_enquiry_followups
+→ crm_opportunity_followups
+
+crm_enquiry_customers
+→ crm_opportunity_customers
+```
+
+Rename foreign keys accordingly.
+
+Rename indexes and constraints to use the new naming convention.
+
+Keep:
+
+```txt
+crm_leads
+crm_quotations
+```
+
+unchanged.
+
+---
+
+# Scope D5.5.1.2 Schema Refactor
+
+Update:
+
+```txt
+src/db/schema.ts
+```
+
+Rename:
+
+```txt
+enquiries
+→ opportunities
+```
+
+Rename:
+
+```txt
+enquiryRelations
+→ opportunityRelations
+```
+
+Rename every Drizzle export to Opportunity terminology.
+
+---
+
+# Scope D5.5.1.3 Domain Refactor
+
+Rename feature module:
+
+```txt
+src/features/crm/enquiries
+```
+
+to
+
+```txt
+src/features/crm/opportunities
+```
+
+Rename:
+
+```txt
+service.ts
+types.ts
+schemas
+components
+hooks
+queries
+mutations
+```
+
+to Opportunity terminology.
+
+No legacy aliases remain.
+
+---
+
+# Scope D5.5.1.4 API Refactor
+
+Replace:
+
+```txt
+/api/crm/enquiries
+```
+
+with
+
+```txt
+/api/crm/opportunities
+```
+
+Routes:
+
+```txt
+GET
+POST
+PATCH
+DELETE
+followups
+assign
+```
+
+must all use Opportunity.
+
+Do not leave compatibility aliases.
+
+---
+
+# Scope D5.5.1.5 App Route Refactor
+
+Rename:
+
+```txt
+/ dashboard / crm / enquiries
+```
+
+to
+
+```txt
+/ dashboard / crm / opportunities
+```
+
+Update navigation accordingly.
+
+---
+
+# Scope D5.5.1.6 Type Refactor
+
+Rename:
+
+```txt
+EnquirySummary
+→ OpportunitySummary
+
+EnquiryDetail
+→ OpportunityDetail
+
+CreateEnquiryInput
+→ CreateOpportunityInput
+
+UpdateEnquiryInput
+→ UpdateOpportunityInput
+```
+
+Apply consistently across server and client.
+
+---
+
+# Scope D5.5.1.7 Permission Refactor
+
+Rename permissions:
+
+```txt
+crm.enquiry.read
+crm.enquiry.create
+crm.enquiry.update
+crm.enquiry.delete
+crm.enquiry.assign
+crm.enquiry.followup.*
+```
+
+to
+
+```txt
+crm.opportunity.read
+crm.opportunity.create
+crm.opportunity.update
+crm.opportunity.delete
+crm.opportunity.assign
+crm.opportunity.followup.*
+```
+
+Update seed/configuration if permissions are managed in code.
+
+---
+
+# Scope D5.5.1.8 Document Sequence
+
+Rename:
+
+```txt
+crm_enquiry
+```
+
+to
+
+```txt
+crm_opportunity
+```
+
+Document code format remains unchanged unless business requires a new prefix.
+
+Update sequence configuration and seed.
+
+---
+
+# Scope D5.5.1.9 Audit Refactor
+
+Rename audit entity:
+
+```txt
+crm_enquiry
+```
+
+to
+
+```txt
+crm_opportunity
+```
+
+Rename audit actions:
+
+```txt
+create_enquiry
+update_enquiry
+delete_enquiry
+assign_enquiry
+```
+
+to
+
+```txt
+create_opportunity
+update_opportunity
+delete_opportunity
+assign_opportunity
+```
+
+---
+
+# Scope D5.5.1.10 UI Refactor
+
+Rename all user-facing wording:
+
+```txt
+Enquiry
+```
+
+to
+
+```txt
+Opportunity
+```
+
+except historical documentation.
+
+Update:
+
+* page titles
+* dialogs
+* breadcrumbs
+* badges
+* table headers
+* empty states
+* permission messages
+
+---
+
+# Scope D5.5.1.11 Documentation
+
+Update:
+
+* ADR references
+* task documentation
+* architecture diagrams
+* implementation notes
+
+Replace "Enquiry" with "Opportunity" where referring to the sales execution domain.
+
+Keep historical notes where necessary.
+
+---
+
+# Database Reset
+
+This task requires:
+
+```txt
+Drop Database Schema
+
+Run Fresh Migration
+
+Run Seed
+```
+
+Old migration history does not need compatibility.
+
+---
+
+# Deliverables
+
+Updated:
+
+```txt
+src/db/schema.ts
+
+src/features/crm/opportunities/**
+
+src/app/api/crm/opportunities/**
+
+src/app/dashboard/crm/opportunities/**
+```
+
+Updated documentation:
+
+```txt
+ADR
+Task documents
+Architecture documents
+```
+
+---
+
+# Explicit Non-Scope
+
+Do not:
+
+* change Lead domain
+* change Quotation domain
+* change Approval workflow
+* change Dashboard
+* change Reports
+* implement Won/Lost lifecycle
+* introduce Sales Enquiry document
+
+Those belong to later tasks.
+
+---
+
+# Verification
+
+Run:
+
+```txt
+npm exec tsc --noEmit
+npm run lint
+npm run build
+```
+
+Verify:
+
+```txt
+Opportunity CRUD
+Opportunity Assignment
+Lead → Opportunity
+Opportunity → Quotation
+Follow-up
+Permissions
+Navigation
+Document Sequence
+Audit Logging
+```
+
+Verify no remaining references:
+
+```txt
+crm_enquiries
+/api/crm/enquiries
+features/crm/enquiries
+EnquiryDetail
+EnquirySummary
+crm.enquiry.*
+```
+
+except historical documentation.
+
+---
+
+# Definition of Done
+
+Task is complete when:
+
+* Opportunity becomes the official CRM sales domain
+* Database uses `crm_opportunities`
+* API uses `/api/crm/opportunities`
+* Feature module uses `opportunities`
+* UI uses Opportunity terminology
+* Permission namespace uses `crm.opportunity.*`
+* Audit uses Opportunity terminology
+* Fresh migration and seed complete successfully
+* No active application code depends on the old Enquiry domain
+
+Result:
+
+```txt
+Lead Domain = Established
+Opportunity Domain = Established
+Quotation Domain = Unchanged
+
+Ready for D.5.6 Opportunity Lifecycle
+```