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

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