feat: goal-based savings tracking & milestones

app/src/api/savings.ts

@@ -0,0 +1,136 @@
+import axios from "axios";
+
+const BASE = "/savings";
+
+export type GoalStatus = "active" | "completed" | "cancelled";
+
+export interface Milestone {
+  id: number;
+  goal_id: number;
+  name: string;
+  target_amount: string;
+  reached_at: string | null;
+  created_at: string;
+}
+
+export interface SavingsGoal {
+  id: number;
+  user_id: number;
+  name: string;
+  description: string | null;
+  target_amount: string;
+  current_amount: string;
+  currency: string;
+  status: GoalStatus;
+  deadline: string | null;
+  created_at: string;
+  updated_at: string;
+  milestones: Milestone[];
+}
+
+export interface CreateGoalPayload {
+  name: string;
+  target_amount: string;
+  description?: string;
+  currency?: string;
+  deadline?: string;
+}
+
+export interface UpdateGoalPayload {
+  name?: string;
+  description?: string;
+  target_amount?: string;
+  current_amount?: string;
+  currency?: string;
+  status?: GoalStatus;
+  deadline?: string;
+}
+
+export interface CreateMilestonePayload {
+  name: string;
+  target_amount: string;
+}
+
+export interface UpdateMilestonePayload {
+  name?: string;
+  target_amount?: string;
+  reached_at?: string;
+}
+
+// Goals
+
+export const createGoal = (userId: number, payload: CreateGoalPayload) =>
+  axios
+    .post<SavingsGoal>(`${BASE}/goals`, payload, { params: { user_id: userId } })
+    .then((r) => r.data);
+
+export const listGoals = (userId: number) =>
+  axios
+    .get<SavingsGoal[]>(`${BASE}/goals`, { params: { user_id: userId } })
+    .then((r) => r.data);
+
+export const getGoal = (userId: number, goalId: number) =>
+  axios
+    .get<SavingsGoal>(`${BASE}/goals/${goalId}`, { params: { user_id: userId } })
+    .then((r) => r.data);
+
+export const updateGoal = (
+  userId: number,
+  goalId: number,
+  payload: UpdateGoalPayload
+) =>
+  axios
+    .patch<SavingsGoal>(`${BASE}/goals/${goalId}`, payload, {
+      params: { user_id: userId },
+    })
+    .then((r) => r.data);
+
+export const deleteGoal = (userId: number, goalId: number) =>
+  axios
+    .delete(`${BASE}/goals/${goalId}`, { params: { user_id: userId } })
+    .then((r) => r.data);
+
+// Milestones
+
+export const createMilestone = (
+  userId: number,
+  goalId: number,
+  payload: CreateMilestonePayload
+) =>
+  axios
+    .post<Milestone>(`${BASE}/goals/${goalId}/milestones`, payload, {
+      params: { user_id: userId },
+    })
+    .then((r) => r.data);
+
+export const listMilestones = (userId: number, goalId: number) =>
+  axios
+    .get<Milestone[]>(`${BASE}/goals/${goalId}/milestones`, {
+      params: { user_id: userId },
+    })
+    .then((r) => r.data);
+
+export const updateMilestone = (
+  userId: number,
+  goalId: number,
+  milestoneId: number,
+  payload: UpdateMilestonePayload
+) =>
+  axios
+    .patch<Milestone>(
+      `${BASE}/goals/${goalId}/milestones/${milestoneId}`,
+      payload,
+      { params: { user_id: userId } }
+    )
+    .then((r) => r.data);
+
+export const deleteMilestone = (
+  userId: number,
+  goalId: number,
+  milestoneId: number
+) =>
+  axios
+    .delete(`${BASE}/goals/${goalId}/milestones/${milestoneId}`, {
+      params: { user_id: userId },
+    })
+    .then((r) => r.data);

backend/app/models/savings_goal.py

@@ -0,0 +1,45 @@
+from datetime import datetime
+from decimal import Decimal
+from enum import Enum as PyEnum
+
+from sqlalchemy import Column, DateTime, ForeignKey, Integer, Numeric, String, Enum, Text
+from sqlalchemy.orm import relationship
+
+from app.database import Base
+
+
+class GoalStatus(str, PyEnum):
+    active = "active"
+    completed = "completed"
+    cancelled = "cancelled"
+
+
+class SavingsGoal(Base):
+    __tablename__ = "savings_goals"
+
+    id = Column(Integer, primary_key=True, index=True)
+    user_id = Column(Integer, ForeignKey("users.id"), nullable=False, index=True)
+    name = Column(String(255), nullable=False)
+    description = Column(Text, nullable=True)
+    target_amount = Column(Numeric(12, 2), nullable=False)
+    current_amount = Column(Numeric(12, 2), nullable=False, default=Decimal("0.00"))
+    currency = Column(String(3), nullable=False, default="USD")
+    status = Column(Enum(GoalStatus), nullable=False, default=GoalStatus.active)
+    deadline = Column(DateTime, nullable=True)
+    created_at = Column(DateTime, nullable=False, default=datetime.utcnow)
+    updated_at = Column(DateTime, nullable=False, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+    milestones = relationship("SavingsMilestone", back_populates="goal", cascade="all, delete-orphan")
+
+
+class SavingsMilestone(Base):
+    __tablename__ = "savings_milestones"
+
+    id = Column(Integer, primary_key=True, index=True)
+    goal_id = Column(Integer, ForeignKey("savings_goals.id"), nullable=False, index=True)
+    name = Column(String(255), nullable=False)
+    target_amount = Column(Numeric(12, 2), nullable=False)
+    reached_at = Column(DateTime, nullable=True)
+    created_at = Column(DateTime, nullable=False, default=datetime.utcnow)
+
+    goal = relationship("SavingsGoal", back_populates="milestones")

backend/app/routes/savings.py

@@ -0,0 +1,169 @@
+from typing import List
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.orm import Session
+
+from app.database import get_db
+from app.models.savings_goal import SavingsGoal, SavingsMilestone
+from app.schemas.savings_goal import (
+    MilestoneCreate,
+    MilestoneRead,
+    MilestoneUpdate,
+    SavingsGoalCreate,
+    SavingsGoalRead,
+    SavingsGoalUpdate,
+)
+
+router = APIRouter(prefix="/savings", tags=["savings"])
+
+
+# ---------------------------------------------------------------------------
+# Helper
+# ---------------------------------------------------------------------------
+
+def _get_goal_or_404(goal_id: int, user_id: int, db: Session) -> SavingsGoal:
+    goal = (
+        db.query(SavingsGoal)
+        .filter(SavingsGoal.id == goal_id, SavingsGoal.user_id == user_id)
+        .first()
+    )
+    if not goal:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Savings goal not found")
+    return goal
+
+
+def _get_milestone_or_404(milestone_id: int, goal_id: int, db: Session) -> SavingsMilestone:
+    milestone = (
+        db.query(SavingsMilestone)
+        .filter(SavingsMilestone.id == milestone_id, SavingsMilestone.goal_id == goal_id)
+        .first()
+    )
+    if not milestone:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Milestone not found")
+    return milestone
+
+
+# ---------------------------------------------------------------------------
+# Savings Goals
+# ---------------------------------------------------------------------------
+
+@router.post("/goals", response_model=SavingsGoalRead, status_code=status.HTTP_201_CREATED)
+def create_goal(
+    payload: SavingsGoalCreate,
+    user_id: int,
+    db: Session = Depends(get_db),
+):
+    goal = SavingsGoal(**payload.model_dump(), user_id=user_id)
+    db.add(goal)
+    db.commit()
+    db.refresh(goal)
+    return goal
+
+
+@router.get("/goals", response_model=List[SavingsGoalRead])
+def list_goals(
+    user_id: int,
+    db: Session = Depends(get_db),
+):
+    return db.query(SavingsGoal).filter(SavingsGoal.user_id == user_id).all()
+
+
+@router.get("/goals/{goal_id}", response_model=SavingsGoalRead)
+def get_goal(
+    goal_id: int,
+    user_id: int,
+    db: Session = Depends(get_db),
+):
+    return _get_goal_or_404(goal_id, user_id, db)
+
+
+@router.patch("/goals/{goal_id}", response_model=SavingsGoalRead)
+def update_goal(
+    goal_id: int,
+    payload: SavingsGoalUpdate,
+    user_id: int,
+    db: Session = Depends(get_db),
+):
+    goal = _get_goal_or_404(goal_id, user_id, db)
+    for field, value in payload.model_dump(exclude_unset=True).items():
+        setattr(goal, field, value)
+    db.commit()
+    db.refresh(goal)
+    return goal
+
+
+@router.delete("/goals/{goal_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_goal(
+    goal_id: int,
+    user_id: int,
+    db: Session = Depends(get_db),
+):
+    goal = _get_goal_or_404(goal_id, user_id, db)
+    db.delete(goal)
+    db.commit()
+
+
+# ---------------------------------------------------------------------------
+# Milestones
+# ---------------------------------------------------------------------------
+
+@router.post(
+    "/goals/{goal_id}/milestones",
+    response_model=MilestoneRead,
+    status_code=status.HTTP_201_CREATED,
+)
+def create_milestone(
+    goal_id: int,
+    payload: MilestoneCreate,
+    user_id: int,
+    db: Session = Depends(get_db),
+):
+    _get_goal_or_404(goal_id, user_id, db)
+    milestone = SavingsMilestone(**payload.model_dump(), goal_id=goal_id)
+    db.add(milestone)
+    db.commit()
+    db.refresh(milestone)
+    return milestone
+
+
+@router.get("/goals/{goal_id}/milestones", response_model=List[MilestoneRead])
+def list_milestones(
+    goal_id: int,
+    user_id: int,
+    db: Session = Depends(get_db),
+):
+    _get_goal_or_404(goal_id, user_id, db)
+    return db.query(SavingsMilestone).filter(SavingsMilestone.goal_id == goal_id).all()
+
+
+@router.patch("/goals/{goal_id}/milestones/{milestone_id}", response_model=MilestoneRead)
+def update_milestone(
+    goal_id: int,
+    milestone_id: int,
+    payload: MilestoneUpdate,
+    user_id: int,
+    db: Session = Depends(get_db),
+):
+    _get_goal_or_404(goal_id, user_id, db)
+    milestone = _get_milestone_or_404(milestone_id, goal_id, db)
+    for field, value in payload.model_dump(exclude_unset=True).items():
+        setattr(milestone, field, value)
+    db.commit()
+    db.refresh(milestone)
+    return milestone
+
+
+@router.delete(
+    "/goals/{goal_id}/milestones/{milestone_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+)
+def delete_milestone(
+    goal_id: int,
+    milestone_id: int,
+    user_id: int,
+    db: Session = Depends(get_db),
+):
+    _get_goal_or_404(goal_id, user_id, db)
+    milestone = _get_milestone_or_404(milestone_id, goal_id, db)
+    db.delete(milestone)
+    db.commit()