alla-allaos-fullstack/plans/task-c.1.md

Task C.1: Customer Ownership & Contact Sharing Governance

Objective

Complete the Customer and Contact domain by introducing:

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:

Which Sales owns this customer?

The system currently knows:

Customer
Contacts
Lead
Enquiry
Quotation

but does not know:

Customer Owner

or

Who can access shared contacts?

---

Frozen Business Rules

Customer Owner

Each customer may have:

1 Primary Owner

Definition:

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:

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:

Customer = SCG

System checks:

SCG.ownerUserId

If found:

Assign Sales
→ pre-selected owner

Marketing can still override.

---

Scope C1.1 Customer Owner Model

Add fields:

crm_customers

ownerUserId
ownerAssignedAt
ownerAssignedBy

Purpose:

Primary Customer Owner

Rules:

• nullable
• one owner at a time
• organization scoped

---

Scope C1.2 Customer Owner History

Add:

crm_customer_owner_history

Fields:

id
customerId

oldOwnerUserId
newOwnerUserId

changedBy
changedAt

remark

Purpose:

Audit ownership changes

---

Scope C1.3 Customer Ownership UI

Customer Detail:

Add section:

Customer Owner

Display:

Owner
Assigned Date
Assigned By

Actions:

Assign Owner
Change Owner
Clear Owner

Permissions:

crm.customer.owner.manage

required.

---

Scope C1.4 Customer List Enhancements

Add columns:

Owner
Owner Assigned At

Filters:

Customer Owner

Optional:

My Customers

quick filter.

---

Scope C1.5 Lead Assignment Integration

When creating Lead:

If:

Customer has Owner

then:

Assigned Sales

auto-populates.

Display:

Suggested Sales Owner

Marketing may override.

Audit:

lead owner suggestion used
lead owner suggestion overridden

---

Scope C1.6 Contact Sharing Model

Add:

crm_contact_shares

Fields:

id
contactId

sharedToUserId

sharedByUserId
sharedAt

isActive

remark

Constraints:

contactId + sharedToUserId

unique.

---

Scope C1.7 Contact Sharing Service

Add:

Share Contact
Unshare Contact
List Shares

Rules:

User may access contact if:

Creator
OR
Shared User
OR
Customer Owner
OR
CRM Admin

---

Scope C1.8 Contact Sharing UI

Contact Detail:

Add:

Shared With

Section.

Actions:

Share
Remove Share

Display:

User
Shared By
Shared At
Remark

---

Scope C1.9 Customer Owner Visibility Rules

Customer Owner automatically gains visibility to:

Customer
Contacts
Related Leads
Related Enquiries
Related Quotations

subject to CRM authorization.

Customer Owner does NOT automatically gain:

Approval Authority
CRM Admin Access

---

Scope C1.10 CRM Access Resolver Integration

Update:

resolveCrmAccess()

Support:

Customer Owner Access
Contact Share Access

Additional helpers:

canAccessCustomer()
canAccessContact()

Rules centralized.

---

Scope C1.11 Permissions

Add:

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:

crm_admin
sales_manager

Optional:

sales

depending on organization policy.

---

Scope C1.12 Security Enforcement

Update:

Customers
Contacts
Leads
Enquiries

to recognize:

Customer Owner
Shared Contact User

visibility.

No UI-only enforcement.

Server-side required.

---

Scope C1.13 Audit Logging

Entity Types:

crm_customer_owner
crm_contact_share

Actions:

assign_owner
change_owner
clear_owner

share
unshare

Payload:

customerId
contactId

oldOwner
newOwner

sharedUser

---

Scope C1.14 Verification Matrix

Marketing

Expected:

See Customer Owner
Use Suggested Sales

Cannot:

Manage Customer Owner

---

Sales Owner

Expected:

See Owned Customers
See Related Contacts

---

Shared User

Expected:

See Shared Contact

Cannot:

See Unshared Contact

---

CRM Admin

Expected:

Full Visibility

---

Owner Change

Expected:

History Created
Audit Created

---

Documentation

Create:

docs/adr/0015-customer-ownership-contact-sharing.md
docs/implementation/task-c1-customer-ownership-contact-sharing-governance.md

Document:

Customer Owner lifecycle
Contact Sharing lifecycle
Lead Assignment suggestion flow
Visibility model
Ownership model

---

Explicit Non-Scope

Do NOT implement:

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:

Customer Domain = COMPLETE
Contact Domain = COMPLETE
Lead Assignment Accuracy = IMPROVED
CRM Core = FUNCTIONALLY COMPLETE