task-c.1

plans/task-c.1.md

@@ -0,0 +1,653 @@
+# Task C.1: Customer Ownership & Contact Sharing Governance
+
+## Objective
+
+Complete the Customer and Contact domain by introducing:
+
+```txt
+Customer Owner
+Contact Sharing
+Ownership Governance
+```
+
+This closes the final gap in CRM customer management and improves Lead assignment accuracy.
+
+---
+
+# Business Motivation
+
+Current problem:
+
+Marketing creates a Lead and must manually determine:
+
+```txt
+Which Sales owns this customer?
+```
+
+The system currently knows:
+
+```txt
+Customer
+Contacts
+Lead
+Enquiry
+Quotation
+```
+
+but does not know:
+
+```txt
+Customer Owner
+```
+
+or
+
+```txt
+Who can access shared contacts?
+```
+
+---
+
+# Frozen Business Rules
+
+## Customer Owner
+
+Each customer may have:
+
+```txt
+1 Primary Owner
+```
+
+Definition:
+
+```txt
+Primary Sales responsible for the customer relationship.
+```
+
+Rules:
+
+* Owner must be an active CRM user
+* Owner should normally be:
+
+  * sales
+  * sales_manager
+* Customer owner may change
+* Owner history must be retained
+* Customer owner is organization-scoped
+
+---
+
+## Contact Sharing
+
+Contacts remain owned by a creator.
+
+However:
+
+```txt
+Contact
+ ├─ Owner
+ ├─ Shared User A
+ ├─ Shared User B
+ └─ CRM Admin
+```
+
+may all access the same contact.
+
+Rules:
+
+* creator retains access
+* shared users gain access
+* CRM Admin retains access
+* removing a share revokes access
+* sharing is persistent until revoked
+
+---
+
+## Lead Assignment Suggestion
+
+When Marketing creates a Lead:
+
+```txt
+Customer = SCG
+```
+
+System checks:
+
+```txt
+SCG.ownerUserId
+```
+
+If found:
+
+```txt
+Assign Sales
+→ pre-selected owner
+```
+
+Marketing can still override.
+
+---
+
+# Scope C1.1 Customer Owner Model
+
+Add fields:
+
+```txt
+crm_customers
+
+ownerUserId
+ownerAssignedAt
+ownerAssignedBy
+```
+
+Purpose:
+
+```txt
+Primary Customer Owner
+```
+
+Rules:
+
+* nullable
+* one owner at a time
+* organization scoped
+
+---
+
+# Scope C1.2 Customer Owner History
+
+Add:
+
+```txt
+crm_customer_owner_history
+```
+
+Fields:
+
+```txt
+id
+customerId
+
+oldOwnerUserId
+newOwnerUserId
+
+changedBy
+changedAt
+
+remark
+```
+
+Purpose:
+
+```txt
+Audit ownership changes
+```
+
+---
+
+# Scope C1.3 Customer Ownership UI
+
+Customer Detail:
+
+Add section:
+
+```txt
+Customer Owner
+```
+
+Display:
+
+```txt
+Owner
+Assigned Date
+Assigned By
+```
+
+Actions:
+
+```txt
+Assign Owner
+Change Owner
+Clear Owner
+```
+
+Permissions:
+
+```txt
+crm.customer.owner.manage
+```
+
+required.
+
+---
+
+# Scope C1.4 Customer List Enhancements
+
+Add columns:
+
+```txt
+Owner
+Owner Assigned At
+```
+
+Filters:
+
+```txt
+Customer Owner
+```
+
+Optional:
+
+```txt
+My Customers
+```
+
+quick filter.
+
+---
+
+# Scope C1.5 Lead Assignment Integration
+
+When creating Lead:
+
+If:
+
+```txt
+Customer has Owner
+```
+
+then:
+
+```txt
+Assigned Sales
+```
+
+auto-populates.
+
+Display:
+
+```txt
+Suggested Sales Owner
+```
+
+Marketing may override.
+
+Audit:
+
+```txt
+lead owner suggestion used
+lead owner suggestion overridden
+```
+
+---
+
+# Scope C1.6 Contact Sharing Model
+
+Add:
+
+```txt
+crm_contact_shares
+```
+
+Fields:
+
+```txt
+id
+contactId
+
+sharedToUserId
+
+sharedByUserId
+sharedAt
+
+isActive
+
+remark
+```
+
+Constraints:
+
+```txt
+contactId + sharedToUserId
+```
+
+unique.
+
+---
+
+# Scope C1.7 Contact Sharing Service
+
+Add:
+
+```txt
+Share Contact
+Unshare Contact
+List Shares
+```
+
+Rules:
+
+User may access contact if:
+
+```txt
+Creator
+OR
+Shared User
+OR
+Customer Owner
+OR
+CRM Admin
+```
+
+---
+
+# Scope C1.8 Contact Sharing UI
+
+Contact Detail:
+
+Add:
+
+```txt
+Shared With
+```
+
+Section.
+
+Actions:
+
+```txt
+Share
+Remove Share
+```
+
+Display:
+
+```txt
+User
+Shared By
+Shared At
+Remark
+```
+
+---
+
+# Scope C1.9 Customer Owner Visibility Rules
+
+Customer Owner automatically gains visibility to:
+
+```txt
+Customer
+Contacts
+Related Leads
+Related Enquiries
+Related Quotations
+```
+
+subject to CRM authorization.
+
+Customer Owner does NOT automatically gain:
+
+```txt
+Approval Authority
+CRM Admin Access
+```
+
+---
+
+# Scope C1.10 CRM Access Resolver Integration
+
+Update:
+
+```txt
+resolveCrmAccess()
+```
+
+Support:
+
+```txt
+Customer Owner Access
+Contact Share Access
+```
+
+Additional helpers:
+
+```txt
+canAccessCustomer()
+canAccessContact()
+```
+
+Rules centralized.
+
+---
+
+# Scope C1.11 Permissions
+
+Add:
+
+```txt
+crm.customer.owner.read
+crm.customer.owner.manage
+
+crm.contact.share.read
+crm.contact.share.create
+crm.contact.share.delete
+crm.contact.share.manage
+```
+
+Default:
+
+```txt
+crm_admin
+sales_manager
+```
+
+Optional:
+
+```txt
+sales
+```
+
+depending on organization policy.
+
+---
+
+# Scope C1.12 Security Enforcement
+
+Update:
+
+```txt
+Customers
+Contacts
+Leads
+Enquiries
+```
+
+to recognize:
+
+```txt
+Customer Owner
+Shared Contact User
+```
+
+visibility.
+
+No UI-only enforcement.
+
+Server-side required.
+
+---
+
+# Scope C1.13 Audit Logging
+
+Entity Types:
+
+```txt
+crm_customer_owner
+crm_contact_share
+```
+
+Actions:
+
+```txt
+assign_owner
+change_owner
+clear_owner
+
+share
+unshare
+```
+
+Payload:
+
+```txt
+customerId
+contactId
+
+oldOwner
+newOwner
+
+sharedUser
+```
+
+---
+
+# Scope C1.14 Verification Matrix
+
+## Marketing
+
+Expected:
+
+```txt
+See Customer Owner
+Use Suggested Sales
+```
+
+Cannot:
+
+```txt
+Manage Customer Owner
+```
+
+---
+
+## Sales Owner
+
+Expected:
+
+```txt
+See Owned Customers
+See Related Contacts
+```
+
+---
+
+## Shared User
+
+Expected:
+
+```txt
+See Shared Contact
+```
+
+Cannot:
+
+```txt
+See Unshared Contact
+```
+
+---
+
+## CRM Admin
+
+Expected:
+
+```txt
+Full Visibility
+```
+
+---
+
+## Owner Change
+
+Expected:
+
+```txt
+History Created
+Audit Created
+```
+
+---
+
+# Documentation
+
+Create:
+
+```txt
+docs/adr/0015-customer-ownership-contact-sharing.md
+docs/implementation/task-c1-customer-ownership-contact-sharing-governance.md
+```
+
+Document:
+
+```txt
+Customer Owner lifecycle
+Contact Sharing lifecycle
+Lead Assignment suggestion flow
+Visibility model
+Ownership model
+```
+
+---
+
+# Explicit Non-Scope
+
+Do NOT implement:
+
+```txt
+Customer ownership percentages
+Multiple primary owners
+Temporary shares
+External customer portal
+Account hierarchy
+Territory management
+```
+
+---
+
+# Deliverables
+
+1. Customer Owner Model
+2. Owner History
+3. Owner Management UI
+4. Lead Assignment Suggestion
+5. Contact Sharing Model
+6. Contact Sharing UI
+7. Resolver Integration
+8. Security Enforcement
+9. Audit Logging
+10. Governance Documentation
+
+---
+
+# Definition of Done
+
+Task C.1 is complete when:
+
+* customer owner exists
+* owner history exists
+* lead assignment can suggest owner
+* contacts can be shared
+* shared contacts persist
+* customer owner gains visibility
+* access resolver supports sharing
+* audits are recorded
+* verification matrix passes
+
+Result:
+
+```txt
+Customer Domain = COMPLETE
+Contact Domain = COMPLETE
+Lead Assignment Accuracy = IMPROVED
+CRM Core = FUNCTIONALLY COMPLETE
+```