Implement Report Schema Cache
epic-structured-post-session-report-form-engine-task-002 — Build a local cache layer for org-specific report schemas fetched from Supabase. Use Hive or shared_preferences to persist schema JSON keyed by org ID and schema version. Include cache invalidation logic triggered by version mismatch or TTL expiry, ensuring offline schema availability for peer mentors in low-connectivity environments.
Acceptance Criteria
Technical Requirements
Implementation Notes
Prefer Hive over shared_preferences for structured JSON storage — Hive supports typed boxes and is faster for larger objects. Define a HiveObject subclass ReportSchemaCacheEntry { orgId, schemaVersion, schemaJson, cachedAt } with a @HiveType adapter generated via build_runner. Implement the stale-while-revalidate pattern by returning the cached value immediately in a synchronous path and scheduling a Future (unawaited) for the background refresh — use a Riverpod FutureProvider or a simple Isolate-free async function. The Connectivity package (connectivity_plus) can check network status before attempting a fetch.
The bufdir_column_schema entity is structurally similar to org report schemas — align cache entry fields with that model's version and column_mappings fields for consistency. This cache is critical for Blindeforbundet's offline home-visit reporting use case.
Testing Requirements
Unit tests: (1) cache miss triggers Supabase fetch and writes result to cache; (2) cache hit within TTL returns cached value without network call; (3) stale entry (beyond TTL) returns stale value and triggers background refresh; (4) version mismatch invalidates cache and re-fetches; (5) offline + no cache throws OfflineWithNoCacheException; (6) offline + stale cache returns stale value with CacheResult.stale flag; (7) logout clears org cache. Mock the Supabase client and use an in-memory Hive box (HiveAesCipher not required for tests). Verify LRU eviction triggers when max entries exceeded.
Dynamically rendered form fields built from runtime JSON schema are significantly harder to make accessible than statically declared widgets — Flutter's Semantics tree must be correct for every possible field type and every validation state. Failures here block the entire feature for Blindeforbundet's visually impaired peer mentors.
Mitigation & Contingency
Mitigation: Define WCAG 2.2 AA semantics requirements for each field type before implementation and write widget tests using Flutter's SemanticsController for every type. Include a real-device VoiceOver test session in the acceptance gate for this epic before marking it done.
Contingency: If dynamic semantics prove too difficult to get right generically, implement field-type-specific Semantics wrappers (one per supported field type) instead of a single generic renderer, accepting slightly more code duplication in exchange for reliable accessibility.
The report-form-orchestrator must manage a complex state machine — schema loading, draft persistence, per-field validation, submission retries, and error recovery — across multiple async operations. Incorrect state transitions could result in lost user data, double submissions, or UI freezes.
Mitigation & Contingency
Mitigation: Define all Bloc states and events explicitly as sealed classes before writing any logic. Use a state machine diagram reviewed by the team before implementation. Write exhaustive Bloc unit tests covering every state transition, including concurrent events and network interruption mid-submission.
Contingency: If Bloc complexity becomes unmanageable, extract draft persistence into a separate DraftManagerCubit and keep report-form-orchestrator focused solely on the submit workflow. The additional granularity makes each component independently testable.
Organisations may require field types beyond the five currently specified (text, multiline, checkbox group, radio, date). If a new type is discovered during pilot testing, the dynamic-field-renderer must be extended, potentially requiring changes across multiple layers.
Mitigation & Contingency
Mitigation: Design dynamic-field-renderer as a registry of field-type renderers with a clear extension point. Document the pattern for adding a new field type so that it can be done in one file without touching existing renderers.
Contingency: If an unhandled field type is encountered at runtime, dynamic-field-renderer renders a labelled plain-text fallback widget and logs a warning so the missing type is surfaced in monitoring, preventing a crash while making the gap visible.