# finance-tracker

**Repository Path**: lxxin1121/finance-tracker

## Basic Information

- **Project Name**: finance-tracker
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-23
- **Last Updated**: 2026-07-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Finance Tracker - 个人财务追踪器

> 微型全栈项目，基于 FastAPI + SQLAlchemy + Jinja2

## 项目介绍

Finance Tracker 是一个个人财务追踪 Web 应用，支持支出和收入的添加、筛选查看、分类汇总统计、预算管理、统计看板和 CSV 导出。

## 技术架构

- **后端框架**: Python 3.11 + FastAPI
- **Web 服务器**: Uvicorn
- **ORM / 数据库**: SQLAlchemy 2.0 + SQLite
- **数据校验与配置**: Pydantic + pydantic-settings
- **前端渲染**: Jinja2 模板引擎 + HTML + 原生 CSS + JavaScript
- **测试**: pytest + httpx（19 项测试全部通过）
- **环境管理**: Conda / venv

## 项目结构

```
finance-tracker/
├── src/
│   ├── __init__.py
│   ├── main.py              # FastAPI 应用入口 + 全局异常处理
│   ├── config.py             # 配置项（pydantic-settings）
│   ├── database.py           # 数据库引擎与会话
│   ├── models.py             # Expense 数据模型
│   ├── income_models.py      # Income 收入数据模型
│   ├── budget_models.py      # MonthlyBudget 预算模型
│   ├── schemas.py            # Pydantic 数据校验（Field 约束）
│   ├── constants.py          # 支出/收入类别常量 + 转换函数
│   ├── add_routes.py         # 添加支出路由
│   ├── budget_routes.py      # 预算管理路由
│   ├── dashboard_routes.py   # 分类汇总 + 财务统计看板路由
│   ├── export_routes.py      # CSV 导出路由
│   ├── income_routes.py      # 收入管理路由（添加/列表/编辑/删除）
│   ├── manage_routes.py      # 支出管理路由（列表/筛选/编辑/删除）
│   ├── routes.py             # 路由兼容层
│   └── template_config.py    # 模板渲染配置
├── templates/
│   ├── base.html             # 基础布局（统一导航栏 + 页脚）
│   ├── index.html            # 首页 - 支出列表
│   ├── add.html              # 添加支出
│   ├── income_add.html       # 添加收入
│   ├── income_list.html      # 收入列表
│   ├── income_edit.html      # 编辑收入
│   ├── summary.html          # 分类汇总
│   ├── budget.html           # 预算管理
│   ├── dashboard.html        # 财务统计看板（支出+收入+结余）
│   ├── edit.html             # 编辑支出
│   ├── export.html           # 导出数据
│   └── error.html            # 通用错误页面
├── static/
│   ├── style.css             # 全局样式文件
│   └── dashboard.css         # 统计看板样式
├── tests/                    # 测试文件（conftest + 9 个测试模块）
├── requirements.txt          # Python 依赖
└── environment.yml           # Conda 环境配置
```

## 接口文档

| 接口 | 方法 | 说明 |
|------|------|------|
| `/` | GET | 首页 - 支出列表 |
| `/expenses/add` | GET | 添加支出页面 |
| `/expenses` | POST | 提交新支出 |
| `/expenses/summary` | GET | 分类汇总页面 |
| `/expenses/filter` | POST | 筛选支出 |
| `/expenses/{id}/edit` | GET | 编辑支出页面 |
| `/expenses/{id}/edit` | POST | 更新支出 |
| `/expenses/{id}/delete` | POST | 删除支出 |
| `/income/add` | GET | 添加收入页面 |
| `/income/add` | POST | 提交新收入 |
| `/income` | GET | 收入列表 |
| `/income/{id}/edit` | GET | 编辑收入页面 |
| `/income/{id}/edit` | POST | 更新收入 |
| `/income/{id}/delete` | POST | 删除收入 |
| `/budget` | GET | 预算管理页面 |
| `/budget` | POST | 设置/更新月度预算 |
| `/dashboard` | GET | 财务统计看板页面 |
| `/export` | GET | 导出数据页面 |
| `/export.csv` | GET | 下载 CSV 文件 |
| `/health` | GET | 健康检查 |

## 快速开始

### 方式一：本地运行（venv）

```bash
# 克隆项目
git clone https://gitee.com/lxxin1121/finance-tracker.git
cd finance-tracker

# 创建虚拟环境
python -m venv venv
venv\Scripts\activate          # Windows
# source venv/bin/activate      # macOS/Linux

# 安装依赖
pip install -r requirements.txt

# 启动服务
uvicorn src.main:app --reload --host 0.0.0.0 --port 8000
```

浏览器访问 http://localhost:8000 或 http://127.0.0.1:8000

### 方式二：Conda 运行

```bash
conda create -n finance-tracker python=3.11
conda activate finance-tracker
pip install -r requirements.txt
uvicorn src.main:app --reload --host 0.0.0.0 --port 8000
```

### 运行测试

```bash
pytest -v
```

## 核心功能

- **添加支出**：录入金额、类别（9 类）、描述、日期
- **筛选支出**：按类别 / 日期范围过滤
- **分类汇总**：按类别统计总金额
- **统计看板**：可视化展示支出和收入分类占比，显示总收入、总支出、结余
- **预算管理**：设定月度预算，自动计算已支出和剩余金额，超支预警
- **支出管理**：编辑和删除支出记录
- **收入记录**：录入收入金额、类别（5 类）、描述、日期
- **收入分类**：工资 / 奖金 / 投资收益 / 兼职 / 其他
- **CSV 导出**：支持按类别和日期范围筛选导出

## 健壮性设计

### 数据校验
- 金额必须大于 0（Pydantic Field 约束 + 路由级 isfinite 校验）
- 类别不能为空（min_length=1 + 路由级 strip 校验）
- 日期格式必须为 YYYY-MM-DD（路由级 strptime 校验）
- 月份格式必须为 YYYY-MM（预算路由级校验）
- 预算金额必须大于 0（路由级校验）
- 筛选时开始日期不晚于结束日期（路由级校验）

### 异常处理
- 所有路由均包含 try...except
- 数据库操作失败自动 rollback
- 返回 JSON 友好错误提示，不暴露堆栈信息
- 全局 RequestValidationError 处理器（422 错误）
- 模板渲染降级处理（模板缺失时返回 JSON 提示）

## 支出类别

| 中文 | 英文 Key |
|------|----------|
| 餐饮 | food |
| 交通 | transport |
| 购物 | shopping |
| 娱乐 | entertainment |
| 水电 | utilities |
| 居住 | housing |
| 医疗 | healthcare |
| 教育 | education |
| 其他 | other |

> 类别支持中英文自动转换，用户输入中文自动存储为英文 Key

## 收入类别

| 中文 | 英文 Key |
|------|----------|
| 工资 | salary |
| 奖金 | bonus |
| 投资收益 | investment |
| 兼职 | parttime |
| 其他 | other_income |

> 类别支持中英文自动转换，用户输入中文自动存储为英文 Key

## AI 协作记录

见 `AI_COLLABORATION.md`

## 开发团队

见项目分工表