# 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 ```