Release 4 Dev 2 Handoff: Dashboard Freshness

Routes

• GET /api/v1/intelligence/dashboard
• GET /api/v1/intelligence/dashboard/summary
• Permission: intelligence:analytics:view
• Query params on /dashboard/summary:
  • start_date: optional YYYY-MM-DD; defaults to current month start.
  • end_date: optional YYYY-MM-DD; defaults to now.
• Response envelope: standard FI { "data": ..., "meta": ... }.

Contract Addition

The existing dashboard payload now includes:

• freshness: ordered source freshness records for analytics_overall, analytics_categories, budget, budget_alerts, cashflow_snapshot, cashflow_alerts, and analytics_trends.
• degraded: true when any freshness source is stale or missing.
• degraded_reasons: machine-readable strings in <source>:<state> form.

Each freshness record includes:

• source
• state: fresh, stale, or missing
• observed_count
• latest_at when available
• age_seconds when available

Sources are considered stale after 72 hours.

Empty And Degraded States

• Empty tenants still return a successful dashboard response with zero-value summary fields.
• Missing source facts are surfaced through freshness[].state="missing" instead of requiring the frontend to infer data quality from empty arrays or null snapshots.
• Stale source facts are surfaced through freshness[].state="stale" and included in degraded_reasons.

Frontend Notes

• Existing cards can continue reading the previous dashboard fields unchanged.
• Show data-quality warnings from freshness and degraded_reasons.
• Treat degraded=true as a partial-data state, not a failed request.