Implement Statistics Cache Manager
epic-coordinator-statistics-dashboard-core-logic-task-002 — Build the StatsCacheManager class that stores aggregated statistics results keyed by scope+filter combinations with a 15-minute TTL. Provide get, set, invalidate, and invalidateAll operations. Cache entries must serialize to/from JSON for potential persistence and must be invalidatable by activity registration events to support the auto-refresh use case.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 1 - 540 tasks
Can start after Tier 0 completes
Implementation Notes
Inject the current time via a `DateTime Function() nowFn` constructor parameter defaulting to `DateTime.now` — this makes TTL logic fully testable without real delays. Store entries as `_CacheEntry
For LRU eviction, a simple `LinkedHashMap` with insertion-order tracking is sufficient. The invalidateAll hook should be called from the BLoC or service layer whenever a proxy_activity registration event is emitted — wire this up in the CoordinatorStatsBloc, not inside the cache manager itself, to preserve single responsibility.
Testing Requirements
Unit test with flutter_test: (1) Store a value and retrieve within TTL — expect the original value returned. (2) Store a value and simulate TTL expiry by injecting a mock clock that returns now + 16 minutes — expect null. (3) Call invalidate on a stored key — expect null on subsequent get. (4) Call invalidateAll with three entries — expect all return null.
(5) Verify key determinism: construct two identical StatsFilter objects and assert their cache keys are equal. (6) Verify JSON round-trip: serialize a stored entry and deserialize it back — assert equality. Use a fake/mock DateTime provider injected via constructor to enable time-travel in tests without real sleeps.
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.