task-c.1

docs/adr/0015-customer-ownership-contact-sharing.md

@@ -0,0 +1,78 @@
+# ADR 0015: Customer Ownership and Contact Sharing
+
+## Status
+
+Accepted
+
+## Context
+
+The CRM customer domain already supported customer masters, contacts, leads/enquiries, and quotations, but it still lacked two production behaviors:
+
+- a first-class primary owner for each customer
+- a persistent sharing model for customer contacts
+
+That gap caused two operational problems:
+
+- Marketing could not reliably suggest the right sales owner when creating a lead.
+- Contact visibility depended on creator/admin fallbacks instead of explicit business governance.
+
+## Decision
+
+We introduce two persistent governance models.
+
+### 1. Customer owner
+
+`crm_customers` now stores:
+
+- `owner_user_id`
+- `owner_assigned_at`
+- `owner_assigned_by`
+
+Ownership changes are recorded in `crm_customer_owner_history`.
+
+Rules:
+
+- one primary owner at a time
+- owner is organization-scoped
+- owner changes are auditable
+- customer owner gains visibility to the customer and related CRM work, subject to CRM scope rules
+
+### 2. Contact sharing
+
+`crm_contact_shares` becomes the production source of truth for persistent contact sharing.
+
+Rules:
+
+- creator keeps access
+- explicitly shared users gain access
+- customer owner gains access
+- CRM admin and broader organization/team scopes keep access
+- removing a share revokes access by deactivating the share row
+
+### 3. Lead assignment suggestion
+
+Lead/enquiry creation now accepts an optional assignee suggestion.
+
+When a selected customer has an owner:
+
+- the form pre-selects that owner as the suggested sales owner
+- users may override before submit
+- the create route records whether the suggestion was used or overridden
+
+## Consequences
+
+Positive:
+
+- customer responsibility is now explicit and historical
+- contact access is governed by durable business state instead of demo-only behavior
+- lead routing is more accurate at creation time
+
+Tradeoffs:
+
+- visibility logic across customer/contact/enquiry flows becomes more stateful
+- team-scope remains approximate until a first-class team graph exists
+
+## Notes
+
+- This ADR does not introduce multiple primary owners, temporary shares, or territory management.
+- Customer owner does not imply approval authority.