Implement PeriodRecordCountService with async Riverpod provider
epic-bufdir-report-period-selection-services-task-003 — Implement PeriodRecordCountService that accepts a DateTimeRange and orgId, queries the BufdirAggregationRepository asynchronously for the activity record count within the range, and exposes a boolean isFuturePeriod flag by comparing the range end date against DateTime.now(). Register as a Riverpod AsyncNotifierProvider (periodRecordCountServiceProvider) so callers can await the count.
Acceptance Criteria
Technical Requirements
Implementation Notes
Use AsyncNotifierProvider.family so the provider is keyed by (DateTimeRange, orgId) and Riverpod automatically disposes stale queries when the key changes (user selects a different period). Implement PeriodRecordCountParams as a data class with == and hashCode based on both fields — required for the family key to work correctly. Inject a nowFn: DateTime Function() parameter into the notifier or service for testable isFuturePeriod logic. Do not cache the count in the service layer — Riverpod's provider caching handles invalidation when the family key changes.
Expose isFuturePeriod as a pure synchronous method on the service class (not in the Notifier state) since it only depends on the range and current time, not async data. This keeps the UI free from having to await a boolean.
Testing Requirements
Unit tests with mocked BufdirAggregationRepository using Riverpod ProviderContainer overrides. Test cases: (1) repository returns 42 for a past period → provider emits AsyncData(42), (2) range.end is tomorrow → isFuturePeriod == true and count query still executes, (3) repository throws SocketException → provider emits AsyncError with the exception, (4) range.end == DateTime.now() boundary → isFuturePeriod == false (not strictly after), (5) empty organisation (zero records) → AsyncData(0). Use a fake clock (injected nowFn) for isFuturePeriod determinism. Verify AsyncLoading is emitted before AsyncData in the provider lifecycle using a listener or container.listen().
Detecting overlap with previously submitted reports requires querying a report history table that may not yet exist or may not have a reliable submitted_at / period_end field, making the validator dependent on an incomplete upstream feature (Bufdir Report History & Audit Log).
Mitigation & Contingency
Mitigation: Define the minimum interface (a single repository method: getSubmittedPeriods(orgId) → List<DateTimeRange>) as an abstract class in this epic. Implement a stub that returns an empty list until the history feature is available, so the validator compiles and passes tests without a real data source.
Contingency: If the history feature is delayed beyond this feature's delivery window, ship the validator with the stub returning an empty list (overlap check disabled) and surface a feature-flag-controlled warning banner explaining that overlap detection will be enabled in a future update.
Bufdir's structural requirements for reporting periods (complete calendar months, grant-year span restrictions) may be ambiguous or subject to change, causing the validator to enforce rules that are incorrect or overly restrictive for some organisations.
Mitigation & Contingency
Mitigation: Document the specific Bufdir rules being enforced in the validator's source code as named constants with references to the relevant Bufdir guidelines. Review the rules with at least one coordinator representative before implementation is finalised.
Contingency: Expose a per-org configuration flag (strict_bufdir_validation: bool) in the period configuration repository so that rule enforcement can be relaxed for specific organisations without a code deployment.