feat: Smart weekly financial digest with trends & insights

[chengyixu]

Summary

Implements a comprehensive weekly financial digest feature that generates smart summaries with spending breakdowns, week-over-week trend analysis, daily patterns, and actionable insights — all without requiring an LLM.

/claim #121

What's Included

Backend (GET /digest/weekly)

• Weekly summary: Total income, expenses, net savings, transaction count
• Week-over-week comparison: Percentage changes for income, expenses, and savings vs the previous week
• Category breakdown: Per-category spending with share percentages and transaction counts
• Daily spending pattern: Monday-through-Sunday breakdown showing spending per day
• Trend analysis: Automatic UP/DOWN/FLAT/NEW/GONE classification per category with descriptions
• Upcoming bills: Bills due in the 7 days following the digest period, with autopay status
• Smart insights engine (no LLM required):
  • Savings rate health (positive/neutral/warning)
  • Spending spike detection (>50% increase)
  • Category anomaly detection (3x+ spending in a category)
  • Dominant category warnings (>50% share)
  • Peak spending day identification
  • No-spend day recognition
  • Upcoming bill alerts (non-autopay bills due soon)
• Query parameters: ?week=YYYY-Wnn for specific weeks, ?currency=EUR for currency filtering
• Redis caching: 10-minute TTL for performance

Frontend (/digest page)

• Week navigation with prev/next buttons
• 4 summary cards: Income, Expenses, Net Savings, Upcoming Bills
• Daily spending bar chart with progress bars
• Category breakdown with percentage indicators
• Trend cards with UP/DOWN/FLAT/NEW/GONE badges
• Color-coded insight cards (green=positive, amber=warning, blue=neutral)
• Upcoming bills list with autopay badges
• Fully responsive layout

Tests (16 test cases)

Test	What it verifies
test_digest_requires_auth	401 without JWT
test_digest_empty_state	Valid response with zero data
test_digest_with_income_and_expenses	Correct income/expense/savings totals
test_digest_category_breakdown	Share percentages and transaction counts
test_digest_daily_spending_pattern	Per-day amounts, correct day names
test_digest_week_over_week	Percentage change calculations
test_digest_trend_analysis	UP/DOWN/FLAT/NEW/GONE directions
test_digest_insights_savings_rate	Savings rate insight generation
test_digest_insights_spending_spike	Spike detection (>50% increase)
test_digest_insights_no_spend_days	No-spend day recognition
test_digest_upcoming_bills	Bills integration in digest
test_digest_currency_filter	Currency-specific filtering
test_digest_specific_week	ISO week parameter support
test_digest_invalid_week_format	400 for bad format
test_digest_week_out_of_range	400 for week > 53
test_digest_response_shape	Full schema validation

Documentation

• OpenAPI 3.0 spec updated with full schema definition and examples for /digest/weekly
• Digest tag added to API documentation

Files Changed

File	Change
packages/backend/app/services/digest.py	New — Digest service with all analytics logic
packages/backend/app/routes/digest.py	New — REST endpoint with caching and validation
packages/backend/app/routes/__init__.py	Register digest blueprint
packages/backend/tests/test_digest.py	New — 16 comprehensive test cases
packages/backend/app/openapi.yaml	Full schema for digest endpoint
app/src/api/digest.ts	New — TypeScript API client with types
app/src/pages/Digest.tsx	New — Full digest page component
app/src/App.tsx	Add /digest route
app/src/components/layout/Navbar.tsx	Add Digest to navigation

Test plan

• All 16 new digest tests pass in CI
• All 22 existing tests continue to pass (zero regressions)
• GET /digest/weekly returns valid digest with test data
• GET /digest/weekly?week=2026-W13 returns correct week data
• GET /digest/weekly?currency=USD filters by currency
• GET /digest/weekly?week=bad returns 400
• Frontend digest page renders with week navigation
• Insights are generated without any LLM dependency

🤖 Generated with Claude Code