feat: cash-flow forecast engine — 30/60/90 day projections (#70)

[i010542]

Problem Summary

No forecasting capability existed in FinMind, leaving users unable to anticipate future cash shortfalls or plan ahead based on recurring obligations.

Solution

A pure-TypeScript forecast engine that projects 30, 60, or 90 days of cash flow from recurring expenses and bills — no backend changes required.

Architecture

src/api/cashflow.ts — Pure forecast engine (no React, no side effects):

• generateForecast(recurringExpenses, bills, horizon, fromDate?) → ForecastPoint[]
• aggregateByWeek(points) → weekly bucketed view for 60/90 day charts
• computeSummary(points) → totals, best/worst day

src/pages/CashflowForecast.tsx — React page using react-query:

• Horizon selector (30 / 60 / 90 days) with active state
• 4 summary cards: Total Inflow, Total Outflow, Net Flow, Items Count
• Recharts BarChart — daily for 30d, weekly aggregated for 60/90d
• Scheduled transactions table with Income/Expense badges
• Error state preserves header + reload button (user can retry in-page)

Forecast Logic

Source	Cadence	Handling
RecurringExpense	DAILY / WEEKLY / MONTHLY / YEARLY	Calendar-correct stepping from start_date
RecurringExpense	active: false	Skipped
RecurringExpense	after end_date	Excluded
RecurringExpense	expense_type === 'INCOME'	Treated as inflow
Bill	ONCE / WEEKLY / MONTHLY / YEARLY	Stepped from next_due_date
Bill	paid_at set	Excluded
Bill (past-due, ONCE)	next_due_date < today	Mapped to forecast day 0
Bill (past-due, recurring)	next_due_date < today	Fast-forwarded to first occurrence ≥ today

MONTHLY uses date-fns/addMonths (calendar months, not ×30 days). YEARLY uses addYears. Both anchor on the original start_date to avoid drift.

Acceptance Criteria

• ✅ Forecast updates when expenses or bills change (react-query refetch + reload button)
• ✅ Handles recurring transactions (DAILY/WEEKLY/MONTHLY/YEARLY with calendar-correct stepping)
• ✅ Graph-ready API output (ForecastPoint[] with date/outflow/inflow/netFlow/cumulativeNet/items)

Test Evidence

Test Suites: 10 passed, 10 total
Tests:       44 passed, 44 total
TypeScript:  0 errors

17 new unit tests cover:

• Empty inputs, all cadences (daily/weekly/monthly/yearly)
• Inactive recurring, past-end-date recurring
• ONCE bill, monthly bill, paid bill exclusion
• Income treated as inflow
• Past-due ONCE bill → maps to forecast start
• Past-due recurring bill → fast-forwards to first future occurrence
• MONTHLY month-end anchor (Jan 31 → Feb 29 in 2024)
• Future start_date → no entries before that date
• computeSummary totals, aggregateByWeek bucketing

Files Changed

File	Change
src/api/cashflow.ts	New: forecast engine
src/pages/CashflowForecast.tsx	New: forecast page
src/__tests__/cashflowEngine.test.ts	New: 17 unit tests
src/App.tsx	Add /cashflow protected route
src/components/layout/Navbar.tsx	Add "Cash Flow" nav link

Resolves: #70