Release 4 Dev 2 Handoff: Dashboard Freshness

Routes

• GET /api/project-finance/project/{id}/dashboard
• GET /api/project-finance/portfolio/dashboard

No route, query parameter, or migration was added. Both existing dashboard read models now include additive freshness metadata.

Contract Addition

Both dashboard responses now include:

• freshness: ordered source freshness records.
• degraded: true when any 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.

Project Dashboard Sources

• project_finance
• team_members
• milestones

Portfolio Dashboard Sources

• portfolio_projects

Empty And Degraded States

• Empty portfolio dashboards still return 200 OK with zero-value portfolio totals.
• Empty or unavailable source facts are surfaced as freshness[].state="missing".
• Stale source facts are surfaced as freshness[].state="stale".
• degraded=true should be displayed as a partial-data warning, not as a failed request.

Frontend Notes

• Existing dashboard fields are unchanged.
• Dashboard freshness can be rendered from freshness.
• degraded_reasons is intended for diagnostics and assertions, not primary user copy.