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