Define Stats Data Models and Interfaces
epic-coordinator-statistics-dashboard-core-logic-task-001 — Define all Dart data model classes and repository/service interfaces for the statistics domain: StatsFilter, KpiCardViewModel, BarChartSeriesViewModel, DonutSegmentViewModel, CoordinatorStatsViewModel, PersonalStatsViewModel, and ContributionData. These typed contracts decouple layers and are prerequisites for all other tasks in this epic.
Acceptance Criteria
Technical Requirements
Implementation Notes
Use Dart's built-in `==` and `hashCode` via `Object` or the `equatable` package if already in the project dependencies — do not introduce new packages without team approval. Prefer sealed classes over abstract classes for StatsScope so the compiler enforces exhaustive pattern matching in switch expressions (Dart 3+). Keep ViewModels flat — avoid nested ViewModels more than two levels deep to simplify BLoC state diffing. Use `const` constructors wherever possible.
The color fields in KpiCardViewModel and DonutSegmentViewModel should reference design token identifiers (e.g., `AppColors.accent`) not raw strings, so enforce this via a custom typedef or enum rather than plain String if the design token system supports it. Align field naming with the existing codebase conventions (camelCase, no Hungarian notation).
Testing Requirements
Write unit tests using flutter_test for every model class: verify fromJson/toJson round-trips, equality checks (two instances with same data are equal), and copyWith correctness. Test that StatsScope sealed class exhaustive switching compiles without warnings. Test that CoordinatorStatsViewModel and PersonalStatsViewModel correctly aggregate their child ViewModels. No mocking required for this task — pure data class tests only.
Target 100% line coverage for all model files.
fl_chart's default colour palette may not meet WCAG 2.2 AA contrast requirements when rendered on the app's dark or light backgrounds. If segment colours are insufficient, the donut chart will fail accessibility audits, which is a compliance blocker for all three organisations.
Mitigation & Contingency
Mitigation: Define all chart colours in the design token system with pre-validated contrast ratios. Run the contrast-ratio-validator against every chart colour during the adapter's unit tests. Use the contrast-safe-color-palette as the source palette.
Contingency: If a colour fails validation, replace with the nearest compliant token. If activity types exceed the available token set, implement a deterministic hashing algorithm that maps activity type IDs to compliant colours.
StatsBloc subscribing to the activity registration stream creates a long-lived subscription. If the subscription is not disposed correctly when the dashboard is closed, it will cause a stream leak and potentially trigger re-fetches on a disposed BLoC, resulting in uncaught errors in production.
Mitigation & Contingency
Mitigation: Implement subscription disposal in the BLoC's close() override. Write a widget test that navigates away from the dashboard and asserts no BLoC events are emitted after disposal.
Contingency: If leaks are detected in QA, add a mounted check guard before emitting states from async callbacks, and audit all other BLoC stream subscriptions in the codebase for the same pattern.
PersonalStatsService's Phase 4 gamification data structure is designed against an assumed future schema. If the Phase 4 Spotify Wrapped feature defines a different data contract when it is developed, the structure built now will require a breaking change and migration.
Mitigation & Contingency
Mitigation: Document the contribution data structure with explicit field semantics and versioning comments. Keep the Phase 4 fields as optional/nullable so they do not break existing consumers if the schema evolves.
Contingency: If the Phase 4 schema diverges significantly, the personal stats data can be re-mapped in a thin adapter layer without changing PersonalStatsService's core implementation.