Implement ReportSchemaCache with TTL eviction
epic-structured-post-session-report-foundation-task-004 — Implement an in-memory ReportSchemaCache class that stores parsed report field schemas keyed by org_id. Support configurable TTL (default 15 minutes), automatic eviction of stale entries, and thread-safe access via Dart isolate-safe patterns. Expose get, set, invalidate, and invalidateAll methods. Schema entries should include field definitions, validation rules, and display order.
Acceptance Criteria
Technical Requirements
Implementation Notes
To make TTL tests deterministic, accept an optional DateTime Function() nowProvider parameter in the constructor defaulting to () => DateTime.now(). This allows tests to inject a controlled clock. Keep the cache as a simple class — do not reach for a third-party cache library. A lazy eviction strategy (evict on get) is sufficient; a background timer for proactive eviction is unnecessary complexity for the current scale.
Place the cache class in a dedicated file under the appropriate layer (e.g., src/processing/ or the infrastructure layer of the feature). The FieldConfig and FieldConfigSchema types defined here will be shared with OrgFieldConfigLoader (task-005), so define them in a shared types file rather than inside the cache file to avoid circular imports.
Testing Requirements
Write unit tests using flutter_test (no Flutter widget test environment needed — plain Dart test). Cover: (1) empty cache returns null for any key, (2) set then get within TTL returns schema, (3) set then get after TTL returns null and entry is removed, (4) invalidate removes specific key without affecting others, (5) invalidateAll removes all keys, (6) custom TTL duration is respected, (7) overwriting an existing key resets its TTL timestamp, (8) FieldConfig and FieldConfigSchema fromJson/toJson round-trip if serialization is added. Use fake DateTime injection (pass a clock function or DateTime provider) to make TTL tests deterministic without sleeping.
Supabase RLS policies for multi-org report access may be more complex than anticipated — coordinators need cross-peer-mentor access within their org but not across orgs, and draft reports should be invisible to coordinators until submitted. Misconfigured RLS could expose sensitive health data or block legitimate access.
Mitigation & Contingency
Mitigation: Define and test RLS policies in isolation before writing repository code. Create a dedicated SQL migration file with policy definitions and an automated integration test suite that verifies each role's access boundaries using real Supabase auth tokens.
Contingency: If RLS proves too complex to express declaratively, implement application-level access control in the repository layer with explicit org and role checks, and add a security audit task before the feature goes to production.
The org field config JSON stored in Supabase may lack a stable, versioned schema contract. If different organisations have drifted to different field-definition formats, org-field-config-loader will fail silently or crash, breaking form rendering for those orgs.
Mitigation & Contingency
Mitigation: Define a canonical JSON Schema for field config and validate all existing org configs against it before implementation begins. Store a schema version field in every config record and handle version migrations explicitly in the loader.
Contingency: If existing configs are too heterogeneous, implement a config normalisation pass in org-field-config-loader that coerces known variants to the canonical format, logging warnings for fields that cannot be normalised so operations can fix them in the admin console.
TTL-based schema cache invalidation may cause peer mentors to use stale field definitions for up to the TTL window after an admin updates the org config, potentially collecting data against outdated field structures.
Mitigation & Contingency
Mitigation: Set a conservative TTL (e.g. 15 minutes) and expose a manual cache-bust mechanism triggered on app foreground-resume. Document the maximum staleness window in the admin console so org admins know to plan config changes outside active reporting windows.
Contingency: If stale schema causes a data quality incident, add a Supabase Realtime subscription to the org config table that invalidates the cache immediately on any config update.