Define typed Dart models for UnitAssignment
epic-organizational-hierarchy-management-foundation-task-006 — Create typed Dart model classes for UnitAssignment including all junction table fields (id, userId, unitId, isPrimary, assignedAt, assignedBy, revokedAt). Include fromJson/toJson, copyWith, equality operators. Add UnitAssignmentStatus enum for active/revoked states used throughout the assignment lifecycle.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 2 - 518 tasks
Can start after Tier 1 completes
Implementation Notes
This is a straightforward value object — keep it simple and consistent with the OrganizationUnit model written in the preceding task. The status computed getter is the only non-trivial piece: it derives UnitAssignmentStatus from revokedAt rather than storing it as a separate field, which keeps the model in sync with the database without redundancy. For copyWith with nullable fields like revokedAt, use the sentinel pattern (a private object) to distinguish 'not provided' from 'explicitly set to null' — this is a common Dart challenge. Example: define a static const _absent = Object() and use it as the default for revokedAt in copyWith.
Follow the same DateTime parsing approach as OrganizationUnit (DateTime.parse for ISO 8601 strings from Supabase). Place this model in the same package/directory as UnitAssignmentRepository to keep the data layer cohesive.
Testing Requirements
Write unit tests using flutter_test. Test file: test/models/unit_assignment_test.dart. Scenarios: (1) fromJson with all fields including revokedAt populated. (2) fromJson with revokedAt = null.
(3) status getter returns active when revokedAt is null. (4) status getter returns revoked when revokedAt is set. (5) toJson produces correct snake_case keys. (6) copyWith with revokedAt override produces updated instance, original unchanged.
(7) Two UnitAssignment instances with same id are ==. (8) UnitAssignmentStatus.fromString with unknown value throws ArgumentError. Target 100% branch coverage on model logic.
Recursive CTE queries for large hierarchies (1,400+ nodes) may exceed Supabase query timeouts or produce unacceptably slow responses, degrading tree load time beyond the 1-second target.
Mitigation & Contingency
Mitigation: Implement Supabase RPC functions for subtree fetches rather than client-side recursive calls. Use materialized path or closure table as a supplemental index for depth-first traversal. Benchmark with realistic NHF data volumes during development.
Contingency: Fall back to a pre-computed flat unit list stored in the hierarchy cache with client-side tree reconstruction, trading freshness for speed. Add a background refresh job to keep the cache warm.
Concurrent writes from multiple admin sessions could cause cache staleness, leading to stale tree views and incorrect ancestor path computations that corrupt aggregation results.
Mitigation & Contingency
Mitigation: Use optimistic versioning on cache entries with a short TTL (5 minutes) as a safety net. Subscribe to Supabase Realtime on the organization_units table to push invalidation events to all connected clients.
Contingency: Provide a manual 'Refresh Hierarchy' action in the admin portal that forces a full cache bust, and display a staleness warning banner when the cache age exceeds the TTL.
Persisting the flat unit list to local storage may expose organization structure data if the device is compromised or the storage is not properly encrypted, violating data protection requirements.
Mitigation & Contingency
Mitigation: Use flutter_secure_storage (AES-256 backed by Keychain/Keystore) for the local unit list cache rather than SharedPreferences. Include only unit IDs, names, and types — no member PII.
Contingency: Disable local-storage persistence entirely and rely on in-memory cache only. Accept the trade-off of no offline hierarchy access for the security guarantee.