task-l.2

plans/task-l.2.md

@@ -0,0 +1,512 @@
+# 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