🏠 Overview › ✅ Implementation Tasks ›✅ epic-bufdir-report-period-selection-services-task-007

Register ReportPeriodValidator as Riverpod provider

epic-bufdir-report-period-selection-services-task-007 — Wrap ReportPeriodValidatorImpl in a Riverpod Provider (reportPeriodValidatorProvider) with the PeriodConfigurationRepository injected via ref.watch. Ensure the provider is scoped correctly so that organisation context is read from the active tenant session and not hardcoded. Add provider override stubs for use in widget and BLoC unit tests.

high priority low complexity infrastructure pending infrastructure specialist Tier 4

Acceptance Criteria

A top-level `reportPeriodValidatorProvider` of type `Provider<ReportPeriodValidator>` is defined and accessible from the feature's provider barrel file.
The provider instantiates `ReportPeriodValidatorImpl` with `periodConfigurationRepositoryProvider` injected via `ref.watch`.
The provider does NOT hardcode any orgId — orgId is passed as a parameter to the `validate()` call at the call site, not baked into the provider.
A `mockReportPeriodValidatorProvider` override (returning a `MockReportPeriodValidator` that implements the interface) is exported from a `test/` helper file for use in widget and BLoC tests.
The provider is registered in the correct Riverpod scope — it should be app-scoped (not overridden per widget tree) unless the project convention requires feature-scoped providers.
Existing Riverpod provider tests (if any) continue to pass after this provider is added.
`dart analyze` reports zero errors on the provider file.
The provider file is importable from the BLoC layer without circular dependencies.

Technical Requirements

frameworks
Flutter
Riverpod
Dart
apis
periodConfigurationRepositoryProvider
data models
ReportPeriodValidator
PeriodConfigurationRepository
performance requirements
Provider must be a plain `Provider` (not `FutureProvider` or `StreamProvider`) since the validator object itself is synchronous — only its `validate()` method returns a Future.
security requirements
Do not read tenant/org session state inside the provider factory — keep the provider stateless and pass orgId explicitly at call sites to avoid stale session data in long-lived providers.

Execution Context

Execution Tier
Tier 4

Tier 4 - 323 tasks

Can start after Tier 3 completes

Implementation Notes

Provider definition pattern: `final reportPeriodValidatorProvider = Provider((ref) { final repo = ref.watch(periodConfigurationRepositoryProvider); return ReportPeriodValidatorImpl(repository: repo); });`. Place the provider in `lib/features/bufdir/report_period/application/report_period_providers.dart` alongside other providers in this feature. If the project uses code-generated Riverpod (`@riverpod` annotation), use `@Riverpod(keepAlive: true)` on a function `reportPeriodValidator(Ref ref)` instead. Ensure the mock helper file is placed under `test/` not `lib/` to avoid shipping test code in production builds.

Testing Requirements

Create `test/helpers/report_period_validator_mocks.dart` exporting: (1) a `MockReportPeriodValidator` class implementing `ReportPeriodValidator` with configurable return values, and (2) a `reportPeriodValidatorOverride(ReportPeriodValidator mock)` helper that returns a `Override` for use in `ProviderContainer` and `ProviderScope` in tests. This file is test-infrastructure only — do not import it from `lib/`.

Component
Report Period Validator
service low
Dependencies (1)
Extend ReportPeriodValidatorImpl with the overlap detection rule: query PeriodConfigurationRepository for previously submitted report periods for the given orgId, then check whether the candidate DateTimeRange overlaps any existing period using inclusive-start/exclusive-end interval arithmetic. Return a typed overlapsExistingReport error carrying the conflicting period for display in the UI. epic-bufdir-report-period-selection-services-task-006
Epic Risks (2)
medium impact high prob dependency

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.

medium impact medium prob scope

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.

Quick Links
All Tasks Execution Plan