Implement OrgHierarchyAccessResolver for scope eligibility
epic-bufdir-report-export-orchestration-task-002 — Implement the access-resolution logic that queries the authenticated user's role and org-unit membership to determine which ExportScope values they are authorised to select. Must call the organisation hierarchy resolver and return an ordered list of permitted scopes. Throw an UnauthorisedExportScopeException if the user has no export rights at all.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 1 - 540 tasks
Can start after Tier 0 completes
Implementation Notes
Check the existing role-based access control patterns in the codebase (auth and RBAC may already have utility methods for role lookup — reuse these rather than writing new Supabase queries). If the project already has a UserRole enum, use it directly rather than duplicating values. Consider implementing resolvePermittedScopes via a Supabase RPC (stored function) to keep the scope-eligibility rules server-side and auditable — this is preferable if the Supabase project already uses RPCs for other access checks. The exception hierarchy should extend a base AppException class if one exists in the project.
Place the resolver in lib/features/bufdir_export/services/org_hierarchy_access_resolver.dart.
Testing Requirements
Write unit tests using flutter_test with Mockito or mocktail to mock the Supabase client. Test all role → scope mappings as separate test cases. Test the UnauthorisedExportScopeException is thrown (not just a generic exception) for peer_mentor. Test that Supabase errors are wrapped in ExportAccessResolutionException.
Write one integration test using the Supabase test database that seeds a user for each role and calls the real implementation — verify the returned scope list matches expectations. Aim for 100% branch coverage on the role-to-scope mapping logic.
The scope selector must accurately reflect each coordinator's access rights within the org hierarchy. If a coordinator can select a scope broader than their authorised access, the edge function's RLS enforcement must catch the attempt — but a permissive RLS policy or a bug in the scope resolver could allow unauthorised data to be exported.
Mitigation & Contingency
Mitigation: Implement permission enforcement at two independent layers: (1) the scope selector only renders options permitted by the user's role record, and (2) the edge function re-validates the requested scope against the user's JWT claims before executing any queries. Write integration tests that attempt to invoke the edge function with a scope beyond the user's permissions and assert rejection.
Contingency: If a permission bypass is discovered post-launch, immediately disable the export feature via the org-level feature flag while the fix is deployed. Review all audit records for exports that may have included out-of-scope data and notify affected organisations.
The export workflow has 7+ discrete states (idle, scope selected, period selected, preview loading, preview ready, confirming, exporting, complete, failed) and several conditional transitions. An incomplete BLoC state machine could allow duplicate submissions, stale preview data to be confirmed, or error states to be unrecoverable without a restart.
Mitigation & Contingency
Mitigation: Model the state machine explicitly as a sealed class hierarchy before coding. Review the state diagram against all user story acceptance criteria. Write bloc unit tests for every valid and invalid state transition, including the happy path and all documented error states.
Contingency: If the BLoC grows too complex to test reliably, decompose it into two cooperating blocs: one for configuration (scope + period selection) and one for execution (preview + confirm + export), linked by a coordinator object.