# Task L.2: User Management Integration & CRM Role Assignment Migration

## Objective

Complete the transition from legacy membership-based business roles to CRM role assignments.

After Task L.2:

```txt
membership.businessRole
```

becomes a legacy compatibility field only.

The primary CRM authorization source becomes:

```txt
crm_user_role_assignments
```

User creation, user editing, user visibility, and CRM authorization administration must all operate through CRM role assignments.

---

# Background

Task L introduced:

```txt
crmRoleProfiles
resolved CRM access
role management
permission matrix
```

Task L.1 introduced:

```txt
crm_user_role_assignments
multi-role users
scope union
permission union
```

Current gap:

```txt
User Create
User Edit
Organization Membership UI
```

still centers around:

```txt
membership.businessRole
```

instead of CRM role assignments.

---

# Scope L2.1 User Form Refactor

Update:

```txt
src/features/users/components/user-form-sheet.tsx
```

Remove CRM dependency on:

```txt
membership.businessRole
```

Replace with:

```txt
CRM Role Assignments
```

New section:

```txt
CRM Roles
```

Display:

```txt
Role Profile
Branch Scope
Product Scope
Primary
Active
```

Support:

```txt
Add Role
Edit Role
Remove Role
Set Primary
```

---

# Scope L2.2 User Detail Page

Add CRM authorization panel.

Display:

```txt
Primary CRM Role

Assigned CRM Roles

Effective Permissions

Effective Branch Scope

Effective Product Scope

Approval Authority
```

Show resolved access result from:

```txt
resolveCrmAccess()
```

This becomes the troubleshooting screen for administrators.

---

# Scope L2.3 User Create Flow

When creating user:

Do not require:

```txt
businessRole
```

Instead:

```txt
Organization Membership
+
Optional CRM Role Assignments
```

Supported:

```txt
Create User
Assign CRM Roles
Assign Branch Scope
Assign Product Scope
```

during creation.

---

# Scope L2.4 User Edit Flow

Allow:

```txt
Add CRM Role
Remove CRM Role
Deactivate CRM Role
Change Scope
Change Primary Role
```

directly from user management.

No navigation to CRM Settings required.

---

# Scope L2.5 User Listing

Enhance user table.

Add columns:

```txt
Primary CRM Role
CRM Role Count
Branch Scope Summary
Product Scope Summary
```

Examples:

```txt
Sales Manager
3 Roles
Bangkok + Rayong
Crane + Solar
```

---

# Scope L2.6 Effective Access Preview

Add:

```txt
Preview Effective Access
```

Dialog or drawer.

Display:

```txt
Resolved Permissions
Resolved Ownership Scope
Resolved Branch Scope
Resolved Product Scope
Resolved Approval Authority
```

This is for administrator verification.

---

# Scope L2.7 Membership Cleanup

Keep:

```txt
membership.businessRole
```

for compatibility.

Behavior:

```txt
If CRM assignments exist
→ ignore businessRole

If CRM assignments do not exist
→ fallback businessRole
```

Add warning:

```txt
Legacy Role
Deprecated
```

in admin screens.

---

# Scope L2.8 Migration Utility

Add:

```txt
scripts/migrate-membership-business-roles.ts
```

Purpose:

Convert:

```txt
membership.businessRole
```

into:

```txt
crm_user_role_assignments
```

Features:

```txt
Dry Run
Execute
Report
Rollback Snapshot
```

Output:

```txt
Migrated Users
Skipped Users
Unknown Roles
Duplicate Assignments
```

---

# Scope L2.9 Permission Updates

Add permissions:

```txt
crm.user_role_assignment.read
crm.user_role_assignment.create
crm.user_role_assignment.update
crm.user_role_assignment.delete
crm.user_role_assignment.manage
```

Default:

```txt
system_admin
crm_admin
```

Optional:

```txt
department_manager (read only)
top_manager (read only)
```

---

# Scope L2.10 Audit

Entity:

```txt
crm_user_role_assignment
```

Actions:

```txt
create
update
delete
activate
deactivate
set_primary
migrate
```

Also audit:

```txt
effective_access_preview
```

for troubleshooting history.

---

# Scope L2.11 Verification

Scenario A

```txt
User:
Sales
+
Sales Manager
```

Expected:

```txt
Role Count = 2
Primary = Sales Manager
Permissions = Union
```

---

Scenario B

```txt
User:
Marketing
+
Sales Support
```

Expected:

```txt
Lead Access
Quotation Support Access
No Approval Access
```

---

Scenario C

```txt
User:
CRM Admin
+
Department Manager
```

Expected:

```txt
Settings Access
Approval Access
Analytics Access
```

---

Scenario D

Legacy User

```txt
membership.businessRole = sales
```

No CRM assignment.

Expected:

```txt
Still works
Warning shown
Migration available
```

---

# Documentation

Create:

```txt
docs/implementation/task-l2-user-management-integration.md
```

Update:

```txt
docs/implementation/technical-debt.md
```

Document:

```txt
businessRole deprecation
migration strategy
effective access preview
CRM role assignment lifecycle
```

---

# Explicit Non-Scope

Do NOT implement:

```txt
Keycloak synchronization
Role request workflow
Approval delegation
Temporary permissions
Organization hierarchy
External identity mapping
```

---

# Deliverables

1. User Form CRM Role Integration
2. User Detail CRM Access Panel
3. Effective Access Preview
4. CRM Role Assignment Management
5. Migration Utility
6. Membership Deprecation Path
7. Audit Coverage
8. Verification Matrix

---

# Definition of Done

Task L.2 is complete when:

* user creation supports CRM role assignments
* user editing supports CRM role assignments
* effective access preview exists
* user list shows CRM role summary
* migration utility exists
* businessRole is no longer the primary CRM authorization source
* compatibility fallback remains functional
* audits are recorded
* verification scenarios pass