alla-allaos-fullstack/docs/implementation/task-l2-user-management-integration.md

Task L.2: User Management Integration

Summary

Task L.2 moves user-management flows onto CRM role assignments so memberships.businessRole is no longer the primary CRM authorization source.

Implemented

• Refactored user create/edit payloads to use:
  • memberships
  • crmRoleAssignments
• Updated user-management server utilities to:
  • sync CRM role assignments during create/edit
  • compute legacy membership.businessRole as a compatibility mirror from the primary assignment
  • build user response models with CRM role summaries and resolved access summaries
• Updated user listing to show:
  • primary CRM role
  • CRM role count
  • branch scope summary
  • product scope summary
• Updated user form sheet to manage CRM role assignments directly:
  • add role
  • remove role
  • set primary
  • branch/product scope editing
  • effective access preview inside the sheet
• Added user effective-access preview endpoint with audit logging
• Added CRM role-assignment reference endpoint for user-management forms
• Added migration utility:
  • scripts/migrate-membership-business-roles.ts

Compatibility

• memberships.businessRole still exists and is still populated
• when CRM assignments exist, resolved CRM authorization uses them as the primary source
• when no assignments exist, fallback remains functional and is surfaced in admin UI as legacy fallback

Verification

• Run: npx tsc --noEmit

Notes

• User management now acts as the primary operational screen for CRM role assignment, so admins do not need to leave the user workflow to adjust CRM authorization.
• The sheet-based effective access preview also serves as the administrator troubleshooting panel for mixed-role users.