User Management Service: Pause, Deactivation, and Certification Side-Effects
epic-admin-portal-core-services-task-007 — Add downstream side-effect handling to UserManagementService: automatically remove paused mentors from chapter public listings when certification expires, trigger coordinator notifications on status changes, and coordinate with certification expiry checker. Implement as a transactional side-effect pipeline.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 3 - 413 tasks
Can start after Tier 2 completes
Implementation Notes
Model the side-effect pipeline as a sequence of SideEffectHandler objects registered in an ordered list — this makes future additions (e.g., gamification badge removal) a single-line registration rather than a conditional chain. Use Supabase's `BEGIN/COMMIT` for the core status + listing update in a single RPC call; fire notification dispatch AFTER the transaction commits to avoid holding the transaction open during FCM I/O. For certification expiry coordination, expose a `processCertificationExpiry(userId)` method that internally calls the same `_applyPauseSideEffects` private method — no code duplication. Use Dart's `Result
Avoid cascading deletes in the DB schema; perform explicit soft-deletes or status updates so audit trails remain intact.
Testing Requirements
Unit tests: mock OrgHierarchyService and NotificationDispatcher, verify side-effect pipeline invokes each step in the correct order and passes correct arguments for pause, deactivation, and cert-expiry scenarios. Test idempotency by calling the same transition twice and asserting no duplicate DB writes. Integration tests: use a Supabase local dev instance; trigger a certification expiry and assert the chapter_listings row is deleted, a notification record is inserted, and the audit_log entry is correct. Failure tests: simulate notification dispatch throwing an exception and assert the status update row persists while the failure is recorded.
Regression test: confirm sibling org nodes are unaffected. Target 90%+ branch coverage on the pipeline state machine.
OrgHierarchyNavigator rendering NHF's full 1,400-chapter tree in a single widget may cause Flutter frame-rate drops below 60 fps on mid-range devices, making the navigator unusable for NHF national admins.
Mitigation & Contingency
Mitigation: Implement lazy expansion: only load immediate children on node expand rather than the full tree upfront. Use virtual scrolling for long sibling lists. Test with a synthetic 1,400-node dataset on a low-end Android device during development.
Contingency: If lazy expansion is insufficient, replace the tree widget with a paginated drill-down navigator (select level → select child) that avoids rendering more than 50 nodes at a time.
Bufdir may update their required export column structure or file format during or after development. If the AdminExportService hardcodes the current Bufdir schema, any format change requires a code release rather than a config update.
Mitigation & Contingency
Mitigation: Drive the Bufdir column mapping from a configuration repository rather than hardcoded constants. Abstract column definitions into a named schema config so that format changes require only a config update and re-deployment without service logic changes.
Contingency: If Bufdir format changes post-launch, release a config update within one sprint. If the change is structural (new required sections), scope a targeted service update and communicate timeline to partner organisations.
Role transition side-effects in UserManagementService (e.g., certification expiry removing mentor from chapter listing, pause triggering coordinator notification) may interact with external services like HLF's website sync. Incomplete side-effect handling could leave the system in an inconsistent state.
Mitigation & Contingency
Mitigation: Model side-effects as explicit domain events published after the primary state change is persisted. Implement event handlers as idempotent operations so re-processing is safe. Write integration tests that assert all side-effects fire correctly for each role transition type.
Contingency: If a side-effect fails after the primary change is persisted, log the failure with full context and trigger a manual reconciliation alert to the on-call team. Provide an admin-accessible re-trigger action for failed side-effects.
If AdminStatisticsService cache TTL is set too long, org_admin may see significantly stale KPI values (e.g., a mentor newly paused an hour ago still appears as active), undermining trust in the dashboard.
Mitigation & Contingency
Mitigation: Default cache TTL to 5 minutes with a manual refresh action on the dashboard. Implement cache invalidation triggered by UserManagementService write operations that affect counted entities.
Contingency: If staleness causes org admin complaints post-launch, reduce TTL to 60 seconds and introduce a real-time Supabase subscription for high-impact counters (paused mentors, expiring certifications).