task-l.1

docs/adr/0014-crm-multi-role-user-assignment.md

@@ -0,0 +1,72 @@
+# ADR 0014: CRM Multi-Role User Assignment
+
+## Status
+
+Accepted
+
+## Context
+
+Task L introduced CRM role profiles and resolved CRM access, but authorization still depended on a single `memberships.businessRole` value per organization membership.
+
+That model is too restrictive for real CRM operations because one user may need multiple CRM responsibilities inside the same organization, such as:
+
+- `sales` + `sales_manager`
+- `crm_admin` + `department_manager`
+- `marketing` + `sales_support`
+
+We need to keep `memberships` as organization access while moving CRM authorization into its own persistent model.
+
+## Decision
+
+We adopt:
+
+- `memberships` as organization/workspace access
+- `crm_user_role_assignments` as CRM authorization
+
+One user can have many CRM role assignments per organization.
+
+Each assignment stores:
+
+- `roleProfileId`
+- branch scope mode and branch IDs
+- product-type scope mode and product-type IDs
+- primary/display flag
+- active/inactive lifecycle
+
+Effective CRM access is resolved from:
+
+1. membership role
+2. all active CRM role assignments
+3. all assigned CRM role profile permissions
+4. direct membership permissions
+
+Rules:
+
+- permissions are the union of all active role-profile permissions plus membership permissions
+- branch scope is the union of active assignment scopes unless any active assignment grants `all`
+- product-type scope is the union of active assignment scopes unless any active assignment grants `all`
+- approval authority uses the highest active authority among assigned roles
+- primary role is display-only and does not limit the permission union
+- `memberships.businessRole` remains temporarily as a compatibility fallback only when no active CRM role assignment exists
+
+## Consequences
+
+### Positive
+
+- supports realistic multi-role CRM operation
+- separates organization access from CRM-specific authorization
+- allows per-role scope assignment per user
+- keeps rollout compatible with existing membership data through lazy backfill
+
+### Negative
+
+- resolver complexity increases
+- old `memberships.businessRole` semantics must be maintained during transition
+- UI and audit coverage must handle assignment lifecycle, not just role-profile maintenance
+
+## Migration Strategy
+
+- create `crm_user_role_assignments`
+- backfill one primary assignment from `memberships.businessRole` when possible
+- treat `memberships.businessRole` as deprecated for CRM authorization after Task L.1
+- keep the column until user-management and downstream integrations fully move to assignment-based CRM access