Expose HierarchyStructureValidator to admin portal
epic-organizational-hierarchy-management-core-services-task-010 — Wire HierarchyStructureValidator so it is callable directly from the admin portal UI layer without going through HierarchyService. This allows the UI to display pre-flight validation errors inline (e.g., red warning before the user submits a reparent). Expose a validate() method returning structured ValidationResult objects.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 3 - 413 tasks
Can start after Tier 2 completes
Implementation Notes
Inject HierarchyStructureValidator as a dependency into the admin portal's ReparentNodeCubit (or equivalent BLoC) rather than calling it from the widget tree directly — this keeps validation logic testable without Flutter widget setup. Use a StreamTransformer with debounceTime(Duration(milliseconds: 300)) on the reparent-target input stream before piping to validate(). For the NHF multi-chapter check, query contact_chapter grouped by contact_id filtered to peer mentors in the affected subtree; this is the most expensive check and should be guarded behind a feature flag per organisation. Return ValidationResult as an immutable value object (use freezed or manual const constructor) so BLoC states can be compared with == for efficient rebuilds.
Do not throw exceptions from validate() — always return a ValidationResult, even for internal errors, so the UI layer has a single response type to handle.
Testing Requirements
Unit tests (flutter_test): validate() with valid reparent returns isValid=true and empty errors list; circular reference detection returns CIRCULAR_REFERENCE error code; max-depth exceeded returns MAX_DEPTH_EXCEEDED; cross-organisation reparent returns CROSS_ORGANISATION_VIOLATION. Widget tests: inline error banner renders when BLoC state contains ValidationResult with errors; submit button is disabled in error state; warning banner renders 'Proceed anyway' button; debounce prevents validate() being called more than once per 300ms burst. Integration test: full reparent flow triggers validation, user sees error, corrects input, error clears, submit becomes enabled. Target 90% line coverage on HierarchyStructureValidator class.
Injecting all unit assignment IDs into JWT claims for users assigned to many units (up to 5 for NHF peer mentors, many more for national coordinators) may exceed JWT size limits, causing authentication failures.
Mitigation & Contingency
Mitigation: Store unit IDs in a Supabase session variable or a dedicated Postgres function rather than embedding them directly in the JWT payload. Use set_config('app.unit_ids', ...) within RLS helper functions querying the assignments table at policy evaluation time.
Contingency: Fall back to querying the unit_assignments table directly within RLS policies using the authenticated user ID, accepting a small per-query overhead in exchange for removing the JWT size constraint.
Rendering 1,400+ nodes in a recursive Flutter tree widget may cause jank or memory pressure on lower-end devices used by field peer mentors, degrading the admin experience.
Mitigation & Contingency
Mitigation: Implement lazy tree expansion — only the root level is rendered on initial load. Child nodes are rendered on demand when the parent is expanded. Use const constructors and ListView.builder for all node lists to minimize rebuild scope.
Contingency: Add a search/filter bar that scopes the visible tree to matching nodes, reducing the visible node count. Provide a 'flat list' fallback view for administrators who prefer searching over browsing the tree.
Requirements for what constitutes a valid hierarchy structure may expand during NHF sign-off (e.g., mandatory coordinator assignments per chapter, minimum member counts per region), requiring repeated validator redesign.
Mitigation & Contingency
Mitigation: Design the validator as a pluggable rule engine where each check is a discrete, independently testable function. New rules can be added without changing the core validation orchestration. Surface all rules in a configuration table per organization.
Contingency: Defer non-blocking validation rules to warning-level feedback rather than hard blocks, allowing structural changes to proceed while flagging potential issues for admin review.
Deploying RLS policy migrations to a shared Supabase project used by multiple organizations simultaneously could lock tables or interrupt active sessions, causing downtime during production migration.
Mitigation & Contingency
Mitigation: Write all RLS policies as CREATE POLICY IF NOT EXISTS statements. Schedule migrations during off-peak hours. Use Supabase's migration preview environment to validate policies against production data shapes before applying.
Contingency: Prepare rollback migration scripts for every RLS policy. If a migration causes issues, execute the rollback immediately and re-test the policy logic in staging before reattempting.