5.5 KiB
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:
membership.businessRole
becomes a legacy compatibility field only.
The primary CRM authorization source becomes:
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:
crmRoleProfiles
resolved CRM access
role management
permission matrix
Task L.1 introduced:
crm_user_role_assignments
multi-role users
scope union
permission union
Current gap:
User Create
User Edit
Organization Membership UI
still centers around:
membership.businessRole
instead of CRM role assignments.
Scope L2.1 User Form Refactor
Update:
src/features/users/components/user-form-sheet.tsx
Remove CRM dependency on:
membership.businessRole
Replace with:
CRM Role Assignments
New section:
CRM Roles
Display:
Role Profile
Branch Scope
Product Scope
Primary
Active
Support:
Add Role
Edit Role
Remove Role
Set Primary
Scope L2.2 User Detail Page
Add CRM authorization panel.
Display:
Primary CRM Role
Assigned CRM Roles
Effective Permissions
Effective Branch Scope
Effective Product Scope
Approval Authority
Show resolved access result from:
resolveCrmAccess()
This becomes the troubleshooting screen for administrators.
Scope L2.3 User Create Flow
When creating user:
Do not require:
businessRole
Instead:
Organization Membership
+
Optional CRM Role Assignments
Supported:
Create User
Assign CRM Roles
Assign Branch Scope
Assign Product Scope
during creation.
Scope L2.4 User Edit Flow
Allow:
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:
Primary CRM Role
CRM Role Count
Branch Scope Summary
Product Scope Summary
Examples:
Sales Manager
3 Roles
Bangkok + Rayong
Crane + Solar
Scope L2.6 Effective Access Preview
Add:
Preview Effective Access
Dialog or drawer.
Display:
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:
membership.businessRole
for compatibility.
Behavior:
If CRM assignments exist
→ ignore businessRole
If CRM assignments do not exist
→ fallback businessRole
Add warning:
Legacy Role
Deprecated
in admin screens.
Scope L2.8 Migration Utility
Add:
scripts/migrate-membership-business-roles.ts
Purpose:
Convert:
membership.businessRole
into:
crm_user_role_assignments
Features:
Dry Run
Execute
Report
Rollback Snapshot
Output:
Migrated Users
Skipped Users
Unknown Roles
Duplicate Assignments
Scope L2.9 Permission Updates
Add permissions:
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:
system_admin
crm_admin
Optional:
department_manager (read only)
top_manager (read only)
Scope L2.10 Audit
Entity:
crm_user_role_assignment
Actions:
create
update
delete
activate
deactivate
set_primary
migrate
Also audit:
effective_access_preview
for troubleshooting history.
Scope L2.11 Verification
Scenario A
User:
Sales
+
Sales Manager
Expected:
Role Count = 2
Primary = Sales Manager
Permissions = Union
Scenario B
User:
Marketing
+
Sales Support
Expected:
Lead Access
Quotation Support Access
No Approval Access
Scenario C
User:
CRM Admin
+
Department Manager
Expected:
Settings Access
Approval Access
Analytics Access
Scenario D
Legacy User
membership.businessRole = sales
No CRM assignment.
Expected:
Still works
Warning shown
Migration available
Documentation
Create:
docs/implementation/task-l2-user-management-integration.md
Update:
docs/implementation/technical-debt.md
Document:
businessRole deprecation
migration strategy
effective access preview
CRM role assignment lifecycle
Explicit Non-Scope
Do NOT implement:
Keycloak synchronization
Role request workflow
Approval delegation
Temporary permissions
Organization hierarchy
External identity mapping
Deliverables
- User Form CRM Role Integration
- User Detail CRM Access Panel
- Effective Access Preview
- CRM Role Assignment Management
- Migration Utility
- Membership Deprecation Path
- Audit Coverage
- 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