Implement BufdirPreviewService preview assembly
epic-bufdir-report-preview-core-logic-task-008 — Implement BufdirPreviewService.assemblePreview(periodId, orgId). The method must: (1) fetch aggregated data via BufdirPreviewRepository, (2) pass raw aggregated data through BufdirReportStructureMapper to produce an ordered section model, (3) fetch prior-period data for anomaly context, (4) invoke BufdirFieldValidationService.validate() with current and prior models, (5) embed the ValidationResult into a BufdirPreviewModel, and (6) return the fully-decorated model. All three dependencies are injected via constructor for testability.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 3 - 413 tasks
Can start after Tier 2 completes
Implementation Notes
Use Future.wait([repository.fetchAggregatedData(periodId, orgId), repository.fetchPriorPeriodData(periodId, orgId)]) to parallelise the two network calls — do not await them sequentially. Wrap the prior-period fetch result in a nullable type so the absence of prior data is a first-class state, not an exception. BufdirReportStructureMapper.map() should receive only the current-period data; prior-period data is passed separately to the validation service. The ValidationResult should be embedded as a field on BufdirPreviewModel (not a side-effect).
Follow the repository pattern: the service must not construct any Supabase clients or queries — all data access goes through the injected repository. Register BufdirPreviewService as a Riverpod Provider (not StateNotifier at this stage — session state is handled in task-009).
Testing Requirements
Write unit tests using flutter_test with mockito or mocktail mocks for all three injected dependencies. Cover: (1) happy path returns correct BufdirPreviewModel shape, (2) repository error propagation, (3) prior-period unavailable path skips anomaly comparisons, (4) section ordering matches mapper output, (5) validate() is called with both current and prior models. Verify Future.wait parallelism by asserting both repository calls are initiated before either resolves. Use fake async to control timing.
Aim for 90%+ branch coverage on assemblePreview.
The exact minimum threshold values required by Bufdir guidelines (e.g., minimum participant counts per section) may not be formally documented in machine-readable form. If thresholds must be researched or negotiated during implementation, the validation service will be delayed and may launch with incomplete rules, reducing its effectiveness.
Mitigation & Contingency
Mitigation: Compile threshold rules from the Bufdir reporting guidelines PDF before sprint start. Store rules in a separate configuration file (not hardcoded in the service class) so they can be updated without a service rewrite. Treat unknown thresholds as 'no minimum' to avoid false errors.
Contingency: Launch with completeness and anomaly validation only, shipping threshold compliance rules as a follow-on config update once rules are confirmed with Bufdir. Flag this as a known limitation in the coordinator help text.
BufdirPreviewService coordinates three async operations (fetch aggregated data, map structure, run validation). Race conditions or partial failures in this chain could produce an inconsistent preview model — e.g., a model with field values but no validation results — which would silently mislead coordinators into thinking the report is clean.
Mitigation & Contingency
Mitigation: Model the orchestration as a single BLoC/Cubit state machine with explicit states (Loading, Loaded, Error) and ensure validation is always run atomically after mapping, never in parallel. Write integration tests that simulate network failure at each step of the chain.
Contingency: If a partial failure state reaches production, detect it via the missing validation summary field in the preview model and show a full-screen error state rather than an incomplete preview, prompting the coordinator to retry.