Define abstract repository interface for metrics
epic-bufdir-data-aggregation-data-layer-task-005 — Define the abstract Dart interface (abstract class) for the Bufdir Metrics Repository. The interface must declare all methods: fetchRawActivities, fetchRawEvents, fetchRawContacts, fetchParticipantCount, fetchGeographicDistribution, saveMetricSnapshot, getMetricSnapshot, and deleteMetricSnapshot. This interface is what all service-layer tests will mock, so it must be stable before any consumers are written.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 1 - 540 tasks
Can start after Tier 0 completes
Implementation Notes
Place the abstract class in the `domain/repositories/` layer (not `data/`), following clean architecture conventions — the domain layer defines the contract, the data layer implements it. Method signatures should use `DateTimeRange` from `dart:ui` or a project-defined equivalent rather than raw `DateTime` start/end pairs, to make the period boundary unambiguous. For `saveMetricSnapshot` and `deleteMetricSnapshot`, use `String snapshotId` as the identifier rather than a full model object for `delete`. For `getMetricSnapshot`, return `Future
When generating the mock with Mockito's `@GenerateMocks`, add `@GenerateMocks([BufdirMetricsRepository])` to the test file and run `dart run build_runner build` — or hand-write the mock using `mocktail`'s `class MockBufdirMetricsRepository extends Mock implements BufdirMetricsRepository {}` pattern, which requires no code generation. This interface is the single most important artifact produced by the data layer epic — its stability directly determines the velocity of all service-layer development and testing that follows.
Testing Requirements
A single canary unit test file (`test/features/bufdir/domain/bufdir_metrics_repository_test.dart`) must: (1) Instantiate `MockBufdirMetricsRepository` (or the hand-written mock) and verify it compiles without error. (2) Stub one method (e.g., `fetchRawActivities`) and assert the stub returns the configured value — confirming the mock framework integration is working correctly. (3) Verify that calling an unstubbed method on the mock throws a `MissingStubError` (Mockito) or equivalent, confirming strict mock behavior is enforced. This canary test is intentionally minimal — its purpose is to validate that the interface and mock are valid Dart before service-layer tests are written against them.
Coverage target: canary test only; implementation tests belong in later tasks.
Supabase RPC functions return JSON with PostgreSQL numeric types (bigint, numeric) that do not map cleanly to Dart int/double. Silent truncation or JSON parsing errors could corrupt participant counts in the final Bufdir submission without any runtime exception.
Mitigation & Contingency
Mitigation: Define explicit Dart fromJson factories for all RPC result models with type-safe parsing and assertion checks. Add a contract test that compares raw RPC JSON output against expected Dart model values using a known seed dataset.
Contingency: If type mismatches are found in production metrics, expose a validation endpoint in BufdirMetricsRepository that re-fetches and compares raw RPC output against the persisted snapshot, flagging any discrepancies before export proceeds.
Persisted metric snapshots can become stale if additional activities are registered after the snapshot is saved but before the export is finalized. Coordinators might unknowingly export data that does not reflect the latest activity registrations.
Mitigation & Contingency
Mitigation: Store a snapshot_generated_at timestamp and a record_count_at_generation field in the snapshot. When the coordinator views cached results, compare the current activity count for the period against the snapshot value and display a 'Data updated since last aggregation — re-run?' warning if counts differ.
Contingency: Add a mandatory staleness check before the export confirmation dialog can proceed: if the snapshot is more than 24 hours old or the record count has changed, require the coordinator to re-run aggregation before the export button is enabled.