# 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