task-l.2

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

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

docs/implementation/technical-debt.md

@@ -378,6 +378,18 @@ Future:
 - update user-management flows to assign CRM roles through assignment rows instead of membership payloads
 - remove the deprecated column only after all CRM modules and admin flows have migrated
 
+## After Task L.2
+
+### Legacy compatibility mirror on membership.businessRole
+
+Current:
+User management now writes CRM role assignments directly, but `memberships.businessRole` is still mirrored from the primary CRM role for compatibility with remaining legacy seams.
+
+Future:
+
+- remove mirror writes once every consumer fully resolves CRM access from `crm_user_role_assignments`
+- delete the column only after migration tooling, admin screens, and downstream integrations no longer depend on it
+
 ### Global project-party filter coverage
 
 Task J adds a global `Project Party Role` filter in the dashboard UI, but the strongest enforcement today is in revenue analytics and export sections.