Define metadata JSONB schema and field contract
epic-activity-type-configuration-foundation-task-006 — Document and enforce the JSONB metadata schema for activity types, covering fields such as requires_expense, requires_receipt, bufdir_category, honorarium_eligible, and any org-specific flags. Create Dart model classes for the metadata structure to ensure type-safe deserialization from the database JSONB column.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 2 - 518 tasks
Can start after Tier 1 completes
Implementation Notes
Place in lib/domain/activity_type/activity_type_metadata.dart. The key design decision is how to handle unknown org-specific flags: a Map
static const String kRequiresExpense = 'requires_expense') to avoid magic string bugs when other code constructs metadata maps. For the schema version, store it as metadata['schema_version'] in the JSONB — increment when adding required new fields. Document the bufdirCategory values as an enum or set of constants: categories come from Bufdir's reporting specification and must match exactly for automated export (see section 1.4 of the requirements). The catch-all extensionFields approach means ActivityTypeMetadataResolver (task-007) can still access org-specific flags via resolver.extensionFlag('hlf_requires_sign_off') without requiring schema changes.
Testing Requirements
Unit tests with flutter_test: (1) fromJson with all known fields present — assert each field deserialises correctly; (2) fromJson with empty JSON object — assert all boolean flags default to false and nullable strings to null; (3) fromJson with unknown extra fields — assert they are stored in extensionFields and no exception is thrown; (4) toJson round-trip — serialise and re-parse, assert equality; (5) fromJson with null metadata column value (null passed from database) — assert a valid default ActivityTypeMetadata is returned (all booleans false); (6) schemaVersion field — assert it defaults to 1 when absent. Property-based testing with dart_test random generators is a bonus but not required.
The JSONB metadata column has no enforced schema at the database level. If the Dart model and the stored JSON diverge (e.g., a field is renamed or a new required flag is added without a migration), the metadata resolver will silently return null or throw at parse time, breaking conditional wizard logic for all organisations.
Mitigation & Contingency
Mitigation: Define a versioned Dart Freezed model for ActivityTypeMetadata and add a Supabase check constraint or trigger that validates the JSONB structure on write. Document the canonical metadata schema in a shared constants file and require schema review for any metadata field additions.
Contingency: Implement a lenient parse path in ActivityTypeMetadataResolver that returns safe defaults for missing fields and logs a structured warning to Supabase edge logs, allowing the app to degrade gracefully rather than crash.
If RLS policies on the activity_types table are misconfigured, a coordinator from one organisation could read or mutate activity types belonging to another organisation, violating data isolation guarantees required by all three client organisations.
Mitigation & Contingency
Mitigation: Write integration tests against the Supabase local emulator that explicitly assert cross-org isolation: a token scoped to org A must receive zero rows when querying org B activity types, and upsert attempts must return permission-denied errors.
Contingency: Apply an emergency RLS policy patch via Supabase dashboard without a code deploy. Audit all activity_type rows for cross-org contamination and restore from backup if any data leakage is confirmed.
If the cache invalidation call in ActivityTypeService is not reliably triggered after an admin creates, edits, or archives an activity type, peer mentors on the same device will see stale data in the registration wizard until the next app restart, leading to confusion and potential misregistrations.
Mitigation & Contingency
Mitigation: Enforce a strict pattern: ActivityTypeService always calls cacheProvider.invalidate() inside the same try block as the successful Supabase mutation, before returning to the caller. Write a widget test that verifies the cache notifier emits an updated list after a service mutation.
Contingency: Add a background Supabase Realtime subscription on the activity_types table that triggers cache invalidation automatically, providing an independent safety net independent of the service call path.