feat: goal-based savings tracking & milestones (fixes #133)

[DrGalio]

Summary

Implements a full goal-based savings tracking system with contribution logging and milestone detection — addressing Issue #133 ($250 bounty).

What's Built

Models (models.py)

• SavingsGoal: name, target_amount, current_amount, currency, deadline, category, status (ACTIVE/COMPLETED/PAUSED)
• SavingsContribution: individual contributions with amount, note, date — linked to goal with cascade delete
• SavingsGoalStatus enum for type-safe status values

API Endpoints (routes/savings.py)

Endpoint	Description
GET /savings/goals	List goals with progress %, remaining, milestones reached. Filter by ?status=
POST /savings/goals	Create goal (name, target_amount, currency, deadline, category)
GET /savings/goals/:id	Goal detail with full contribution history
PATCH /savings/goals/:id	Update name, target, deadline, category, or status
DELETE /savings/goals/:id	Delete goal + all contributions (cascade)
POST /savings/goals/:id/contribute	Add contribution — auto-updates current_amount and status
GET /savings/goals/:id/milestones	Milestone tracker: which of 25/50/75/100% reached + next milestone + amount needed

Key Features

• Auto-completion: Goal status automatically flips to COMPLETED when current_amount >= target_amount
• Milestone tracking: Returns which thresholds (25%, 50%, 75%, 100%) have been reached, plus the next upcoming milestone and how much is needed to reach it
• Progress analytics: Every goal response includes progress_pct, remaining, and milestones_reached
• Over-saving allowed: Contributions can exceed the target (progress_pct can go above 100%)
• User isolation: All endpoints are scoped to the authenticated user — other users cannot see or contribute to your goals

Database

• savings_goals and savings_contributions tables with proper indexes
• Migration file for existing deployments: migrations/002_savings_goals.sql
• Auto-migration via _ensure_schema_compatibility() — zero-downtime deploy

Tests (tests/test_savings.py)

20 tests covering:

• Goal CRUD (create, list, get, update, delete)
• Input validation (missing name, zero/negative target)
• Contributions (single, multiple accumulate correctly, exceed target)
• Auto-completion at 100%
• Milestones endpoint (partial progress, all reached)
• Auth enforcement (401 for unauthenticated)
• User isolation (other users cannot see or contribute to your goals)

OpenAPI

• Full documentation for all 7 endpoints
• SavingsGoal, SavingsGoalDetail, NewSavingsGoal, UpdateSavingsGoal, NewContribution schemas
• New Savings tag

Acceptance Criteria

• ✅ Production-ready implementation
• ✅ Includes tests (20 tests, full CRUD + milestones + auth + isolation)
• ✅ Documentation updated (OpenAPI, inline docstrings, this PR)

Example Flow

# Create a goal
POST /savings/goals {"name": "Vacation", "target_amount": 1000}
# → { progress_pct: 0, milestones_reached: [] }

# Add contributions
POST /savings/goals/1/contribute {"amount": 250}
# → { progress_pct: 25, milestones_reached: [25] }

POST /savings/goals/1/contribute {"amount": 500}
# → { progress_pct: 75, milestones_reached: [25, 50, 75] }

# Check milestones
GET /savings/goals/1/milestones
# → { next_milestone: 100, amount_to_next: 250 }

# Final push
POST /savings/goals/1/contribute {"amount": 250}
# → { status: "COMPLETED", progress_pct: 100, milestones_reached: [25, 50, 75, 100] }

Files Changed

packages/backend/app/models.py                    — SavingsGoal + SavingsContribution models
packages/backend/app/routes/savings.py             — 7 savings endpoints (NEW)
packages/backend/app/routes/__init__.py            — register savings blueprint
packages/backend/app/__init__.py                   — auto-migration for savings tables
packages/backend/app/db/schema.sql                 — savings_goals + savings_contributions
packages/backend/app/db/migrations/002_savings_goals.sql — migration (NEW)
packages/backend/app/openapi.yaml                  — 7 endpoints + 5 schemas
packages/backend/tests/test_savings.py             — 20 tests (NEW)

8 files changed, 967 insertions