User account management BLoC state
epic-admin-portal-user-management-task-004 — Implement the BLoC managing all state for the User Account Management Screen: paginated user list, active filter state, loading/error/empty states, inline operation feedback (role assignment, activation toggle), and invitation flow state. Integrate with the data layer and composable filter query builder.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 3 - 413 tasks
Can start after Tier 2 completes
Implementation Notes
Use sealed classes for both Event and State in Dart 3 — this gives exhaustive switch coverage and compile-time safety. Keep the BLoC thin: it orchestrates events and delegates all async work to the service layer. Do not put Supabase queries inside the BLoC. Optimistic updates work well here because role and status changes are low-risk reversals — apply the change to the in-memory UserSummary immediately, then await the service call and revert if it fails.
For operationStatus, model it as a discriminated union: Idle | InProgress(userId) | Success(userId, message) | Failure(userId, message) — this allows the UI to show per-row spinners and feedback without a separate state tree. The invitation flow state can be a simple sub-state field (InvitationIdle | InvitationInProgress | InvitationSuccess | InvitationFailure) on UserManagementLoaded.
Testing Requirements
Use bloc_test for all event-to-state transitions. Required test cases: initial load success, initial load failure, filter change resets pagination, load next page appends, load next page while already loading is a no-op, role assignment optimistic update then success confirm, role assignment optimistic update then server error reverts, activation toggle optimistic update then revert on error, pull-to-refresh resets list, invitation sent success, invitation sent failure. Mock UserManagementService with mockito or manual fakes. Do not use real Supabase in BLoC tests.
Minimum 85% branch coverage.
Displaying NHF users with membership in up to 5 local chapters in a flat list view without duplicating entries requires a non-trivial aggregation query. Incorrect query design could result in duplicated user rows or missing chapter affiliations, confusing admins and causing incorrect role assignments.
Mitigation & Contingency
Mitigation: Design the user list query to GROUP BY user_id and aggregate chapter affiliations as an array field. Use AdminRepository's typed models to surface this aggregated structure to the UI. Validate with a test dataset containing users in 5 chapters.
Contingency: If aggregation query complexity proves too high for real-time filtering, implement a separate multi-chapter affiliation fetch triggered only when a specific user row is expanded, reducing query complexity for the base list.
Composable multi-dimensional filters (role + chapter + status + certification state) applied server-side against an org with 2,000+ users may produce slow queries, particularly when filtering by certification state requires joining an additional table.
Mitigation & Contingency
Mitigation: Ensure the relevant filter columns (role, status, chapter_id, certification_expiry) are indexed in Supabase. Use cursor-based pagination rather than OFFSET to maintain consistent performance at high page numbers. Profile filter query combinations against a large dataset during development.
Contingency: If multi-filter performance degrades in production, introduce a denormalised search index table updated on user status changes, allowing the list query to filter from a single table.
Deactivating a user account that has ongoing activity assignments, open expense claims, or active chapter affiliations may leave orphaned records or break downstream workflows if the deactivation does not trigger correct cascade handling.
Mitigation & Contingency
Mitigation: Define and document the expected state of each dependent record type on user deactivation before implementing the toggle. Implement deactivation as a UserManagementService operation that checks for and warns about open dependencies before persisting. Write integration tests covering each dependency type.
Contingency: If orphaned record issues are discovered post-launch, provide an admin-accessible reconciliation view that surfaces users with inconsistent dependency states and allows manual resolution without requiring a code deploy.