Period Comparison Diff View
Component Detail
Description
Optional side-by-side or inline diff panel that shows each numeric field's value for the current reporting period alongside the corresponding value from the same period in the prior year. Helps repeat reporters quickly spot unexpected drops or omissions. Toggled by the coordinator from the preview screen header.
bufdir-period-diff-view
Summaries
The Period Comparison Diff View delivers a powerful quality assurance capability for experienced coordinators who submit annual Bufdir reports repeatedly. By placing last year's figures directly alongside the current period's values, the tool makes it immediately obvious when a number has dropped unexpectedly or a field has been left blank that was populated previously. This catches errors that raw validation rules cannot — such as a genuine but surprising 40% drop in activity numbers — before the report is submitted to authorities. Identifying these anomalies internally prevents the embarrassment and administrative burden of post-submission corrections or requests for explanation from Bufdir, protecting the organisation's reporting credibility and reducing staff stress during submission periods.
This medium-complexity component depends on both the Bufdir Preview Repository and the Bufdir Preview Service, so it sits later in the dependency chain and cannot be developed in isolation. The primary delivery risk is the availability of prior-period data: if historical report data is not yet structured in the database, this component cannot be meaningfully tested end to end. Confirm with the data team early whether prior-period records exist in the test environment. Development scope includes on-demand data loading (must not block the main preview render), configurable delta threshold logic, side-by-side or inline layout toggle, and UI for the diff overlay toggle in the preview header.
Schedule integration testing with real multi-period data sets to validate the delta highlighting logic against actual reporting variance patterns.
Implemented as an optional overlay panel within the preview screen, toggled by `toggleDiffMode()` which updates a local or provider-managed boolean flag controlling rendering. `loadPriorPeriodData(periodId)` makes an async call through `BufdirPreviewRepository` to fetch the prior year's aggregated field values, storing them in local state; use a `FutureBuilder` or `AsyncValue` pattern so the main preview remains interactive during loading. `getDeltaForField(fieldKey)` computes the absolute or percentage difference between current and prior values, applying the configurable threshold to determine highlight state. `isDiffAvailable()` guards the toggle button — disable it if no prior-period record exists.
The diff layout can be implemented as a parallel column injected into each `BufdirFieldRowWidget` via an optional `priorValue` parameter, keeping the field row widget reusable without structural changes. Ensure threshold configuration is read from a central config source rather than hardcoded.
Responsibilities
- Render prior-period values beside current values for each field
- Highlight fields where delta exceeds a configurable threshold
- Load prior-period data on demand without blocking preview render
- Allow toggling the diff overlay on and off
Interfaces
build(BuildContext)
toggleDiffMode()
loadPriorPeriodData(periodId)
getDeltaForField(fieldKey)
isDiffAvailable()
Relationships
Dependencies (2)
Components this component depends on