🏠 Overview › ✅ Implementation Tasks ›✅ epic-bufdir-report-preview-ui-components-task-006

Define validation summary banner data model and issue list model

epic-bufdir-report-preview-ui-components-task-006 — Define BufdirValidationSummaryData model containing total error count, total warning count, and a list of BufdirValidationIssue items (each with field identifier, section title, issue message, severity). This model drives the BufdirValidationSummaryBanner visibility and content.

high priority low complexity frontend pending frontend specialist Tier 1

Acceptance Criteria

BufdirValidationSummaryData is an immutable Dart class with fields: int errorCount, int warningCount, List<BufdirValidationIssue> issues
BufdirValidationIssue is an immutable Dart class with fields: String fieldIdentifier, String sectionTitle, String issueMessage, BufdirValidationSeverity severity
BufdirValidationSeverity is an enum with values: error, warning
Both classes implement copyWith, ==, hashCode, and toString
BufdirValidationSummaryData.isEmpty getter returns true when errorCount == 0 and warningCount == 0
BufdirValidationSummaryData.fromIssues factory constructor derives errorCount and warningCount automatically from the issues list
All fields in BufdirValidationIssue are non-nullable; no optional fields left unguarded
Classes are placed in the bufdir/models/ directory and exported from the feature barrel file
Unit tests confirm that fromIssues correctly aggregates counts for mixed severity lists
Unit tests confirm isEmpty returns false when at least one error or warning is present

Technical Requirements

frameworks
Flutter
Riverpod
data models
bufdir_export_audit_log
bufdir_column_schema
performance requirements
Model instantiation must be O(n) in issue list length — no nested loops during construction
Immutable models enable Riverpod equality checks without custom comparators
security requirements
No PII stored in validation models — field identifiers are structural keys only, not user data
Models must not reference raw database row content directly

Execution Context

Execution Tier
Tier 1

Tier 1 - 540 tasks

Can start after Tier 0 completes

Implementation Notes

Use @immutable annotation and freeze-style patterns (manual or with freezed package if already in project dependencies — do not add new dependencies without approval). The fromIssues factory is the primary construction path; the default constructor is for deserialization only. Keep models in a dedicated models/ subdirectory under the bufdir feature folder to avoid coupling with the widget layer. The fieldIdentifier should match the column key used in BufdirColumnSchema.column_mappings so that focus navigation can resolve the correct widget.

Testing Requirements

Write pure Dart unit tests (no widget tree required). Cover: (1) fromIssues with empty list yields isEmpty == true; (2) fromIssues with mixed severities yields correct errorCount and warningCount; (3) copyWith produces a new instance with only the specified field changed; (4) equality check: two instances with identical fields are equal; (5) BufdirValidationSeverity enum exhaustiveness — ensure switch coverage. Minimum 90% line coverage for both model classes.

Component
Validation Summary Banner
ui low
Dependencies (1)
Define the Dart data model for BufdirFieldRowData including label, value, validationState enum (normal, warning, anomaly), tooltip text, and field identifier. This model will be consumed by BufdirFieldRowWidget and produced by BufdirPreviewService. Ensure the model is immutable and equatable. epic-bufdir-report-preview-ui-components-task-001
Epic Risks (2)
high impact medium prob technical

Implementing the tap-to-scroll-and-focus behavior from the validation banner to a specific field row in a long scrollable list is complex in Flutter. If focus management is incorrectly implemented, VoiceOver users who navigate to the banner and select an issue will not be moved to the relevant field row, breaking the accessibility workflow and violating WCAG 2.4.3 (Focus Order).

Mitigation & Contingency

Mitigation: Use BufdirAccessibilityUtils focus management utilities (built in the foundation epic) with explicit GlobalKey-based scroll anchors on each field row. Test with a real iOS device running VoiceOver during widget development, not only in the Flutter accessibility inspector.

Contingency: If programmatic scroll-to-focus cannot be reliably achieved before the TestFlight deadline, fall back to a navigation approach where tapping a banner issue opens a modal detail sheet for that field row rather than scrolling in place, and file a follow-up ticket for the inline scroll implementation.

medium impact low prob technical

The validation summary banner must reactively update its issue count as underlying aggregated data changes (e.g., if the coordinator has navigated away and data was refreshed). If the banner's Riverpod provider is not correctly scoped, it may display stale issue counts or fail to disappear when all issues are resolved, eroding coordinator trust in the validation system.

Mitigation & Contingency

Mitigation: Drive the banner exclusively from the same Riverpod provider that powers the full preview model — do not maintain a separate local state for issue counts. Write a widget test that simulates a data refresh mid-review and asserts the banner updates within one frame.

Contingency: If stale state reaches production, add a manual refresh button to the banner as a short-term workaround while the provider scoping is corrected in the next release cycle.

Quick Links
All Tasks Execution Plan