Org Hierarchy Service: Cache Invalidation and Search
epic-admin-portal-core-services-task-003 — Add cache invalidation on hierarchy changes, short-TTL refresh policy, and node search by name/code within the cached tree. Expose a searchNodes() method returning ranked matches for the navigator component's search field.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 2 - 518 tasks
Can start after Tier 1 completes
Implementation Notes
For diacritic normalisation, implement a simple Dart extension String.normalise() that replaces Norwegian characters (ø→o, æ→ae, å→a, Ø→O, Æ→AE, Å→A) before lowercasing. Do NOT pull in a full Unicode normalisation library — the character set is known and bounded. Search ranking: use a scoring function (3 = exact code, 2 = name prefix, 1 = name contains) and sort descending. For debouncing in the UI layer, use a 300ms debounce in the Riverpod notifier watching the search field — this is a UI concern and should not be implemented inside OrgHierarchyService itself.
Cache invalidation trigger: wire invalidateCache() to Supabase Realtime subscriptions on the organisations table so that admin-side org edits propagate to all connected clients within seconds. This Realtime subscription setup is part of this task.
Testing Requirements
Unit tests (flutter_test): cover all match types and ranking order. Test Norwegian character normalisation with ø→o, æ→ae, å→a equivalences. Test cache invalidation: after invalidateCache(), the next getTree() call must fetch from Supabase (mock the client and assert call count). Test TTL expiry: inject a mock clock, advance past TTL, assert stale entry triggers a re-fetch.
No integration tests required beyond what task-001/002 already cover.
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).