Release 3 Dev 2 Handoff: Working Capital

Route

• GET /api/v1/intelligence/working-capital/summary
• Permission: intelligence:cashflow:view
• Query params:
  • start_date: optional YYYY-MM-DD; defaults to today.
  • end_date: optional YYYY-MM-DD; defaults to three months after start_date.
  • entity_id: optional UUID filter.
• Response envelope: standard FI { "data": ..., "meta": ... }.

Data Contract

data includes:

• receivables and payables: AR/AP aging summaries with total_open, due_in_window, open_item_count, ordered aging buckets, currency, and source freshness.
• expected_cash_flow: inflow_amount, outflow_amount, net_amount, currency, and source.
• cash_conversion_cycle: DSO/DPO where AR/AP throughput exists; available=false with unavailable_reasons until inventory-day facts exist.
• forecast_variance: latest forecast-accuracy variance when available; otherwise available=false.
• freshness: source freshness records for receivable, payable, cashflow_predictions, and forecast_accuracy.
• degraded and degraded_reasons: currently used for mixed-currency aggregation without FX conversion.

Empty And Degraded States

• No AR/AP facts: aging summaries return zero totals and empty-count buckets.
• No AR/AP facts but cashflow predictions exist: expected_cash_flow.source is cashflow_predictions.
• No forecast accuracy: forecast_variance.available=false.
• Mixed currencies: totals are still returned, but degraded=true because no FX conversion is applied.

Event Inputs

The Kafka consumer now persists service-owned facts from:

• accounting.ar.updated: receivable facts from Core Ledger AR invoices.
• accounting.ap.updated: payable facts from Core Ledger AP bills.

Both paths upsert into working_capital_items by (tenant_id, source_kind, source_id).

Frontend Notes

• Show AR/AP cards directly from receivables and payables.
• Show expected cash flow from expected_cash_flow; surface source in tooltips.
• Treat cash_conversion_cycle.available=false as a partial-data state, not an error.
• Surface stale or missing freshness rows as data-quality warnings.

Release 1 Deferred Closure Check

• infranotes-front has no direct /api/planning/* calls in planning pages, but the shared FI planning utility clients still use legacyPlanningPath for calendar, reminder, and recurrence helpers.
• Budget, goal, planned-expense, scenario, and cashflow legacy paths have canonical replacements listed in docs/RELEASE_0_CANONICAL_API.md.
• Calendar, reminder, and recurrence helpers have no FI v1 canonical replacement yet; adding those routes would be a separate public API contract decision, not part of the Release 3 working-capital read surface.