4. 实战项目启动-家庭账本

来源：TraeCode

第四章 实战项目启动——搭建「家庭账本」

从本章开始，我们用一个贯穿后续所有章节的项目来学习。

4.1 项目背景与需求

项目名称：家庭账本（Family Ledger）

目标：一个命令行记账小工具，用 Python 编写，支持：

1. 记录每一笔收支（金额、分类、备注、日期）
2. 按分类统计支出占比
3. 生成月度收支报表
4. 数据存到本地 SQLite 数据库

为什么选这个项目？

• 贴近生活，做完真能用。
• 涵盖文件读写、数据库、数据处理、测试、Git 等核心知识点。
• 复杂度适中，能持续加功能，适合逐步学习。

4.2 用 CLI 创建项目骨架

第 1 步：创建项目目录并初始化 Git

# macOS / Linux / WSL2
mkdir -p ~/projects/family-ledger && cd ~/projects/family-ledger
git init -b main

# Windows PowerShell
New-Item -ItemType Directory -Force -Path projects\family-ledger
cd projects\family-ledger
git init -b main

Git 在所有操作系统的命令一致。如果你还没装 Git：macOS 装完 Xcode Command Line Tools 就有（xcode-select --install）；Linux 用 sudo apt install -y git；Windows 去 git-scm.com 下载安装。

第 2 步：启动 CLI，让它帮你设计目录结构

traecli

在输入框发送：

我要用 Python 做一个命令行家庭记账工具，叫 family-ledger。
功能包括：记录收支、按分类统计、月度报表、数据存 SQLite。
请帮我设计项目目录结构，并说明每个文件/目录的职责。

CLI 会给出一个结构方案，比如：

family-ledger/
├── src/
│   ├── __init__.py
│   ├── models.py        # 数据模型
│   ├── storage.py       # SQLite 存储层
│   ├── ledger.py        # 记账核心逻辑
│   ├── stats.py         # 分类统计
│   ├── report.py        # 月度报表
│   └── cli_app.py       # 命令行入口
├── tests/               # 单元测试
├── data/                # 数据库文件存放
├── requirements.txt     # 依赖
├── README.md            # 项目说明
└── .gitignore           # Git 忽略规则

4.3 养成开发规范

好习惯从第一天开始。我们先把规范文件建好。

第 1 步：创建 .gitignore

让 CLI 帮你生成：

帮我生成一个适合 Python 项目的 .gitignore，要忽略虚拟环境、__pycache__、SQLite 数据库文件等。

CLI 会创建文件。重点确认这几行在 .gitignore 里（数据文件不入版本库）：

__pycache__/
*.pyc
.venv/
venv/
data/*.db
data/*.sqlite

第 2 步：写 README.md

帮我写一个 README.md，介绍 family-ledger 是什么、有什么功能、如何安装运行。

第 3 步：约定 commit message 规范

我们采用 Conventional Commits（约定式提交），格式：

<type>: <description>

常见 type：feat（新功能）、fix（修 bug）、docs（文档）、refactor（重构）、test（测试）、chore（杂项）。

例如：feat: 新增记账录入功能、fix: 修复金额计算精度问题。

你可以让 CLI 帮你记下这个规范——下一章我们会用 AGENTS.md 把它沉淀进项目（见第八章详细讲）。

4.4 让 CLI 写第一行代码

先把本课 ledger-starter 的 README、fixture 和 tests 复制到自己的项目；卡住时可对照 ledger-reference。

第 1 步：创建 Python 虚拟环境

# macOS / Linux / WSL2
python3 -m venv .venv
source .venv/bin/activate

# Windows PowerShell
py -m venv .venv
.\.venv\Scripts\Activate.ps1

如果 PowerShell 提示「无法加载脚本，因为在此系统上禁止运行脚本」，先执行一次：Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned，再重试激活。

激活后，命令行提示符前面会出现 (.venv)，说明你已在虚拟环境中。后续所有 Python / pip 命令都在这个环境里跑。

第 2 步：让 CLI 实现「记账录入」功能

在 CLI 里发送：

帮我实现 src/ledger.py 和 src/storage.py。
storage.py 用 SQLite 存储，entries 表字段：id、amount_cents（整数分）、type（收入/支出）、category、date、note。输入金额为元，用 Decimal 从字符串换算；不要先用浮点存储再中途迁移。
ledger.py 实现输入校验和收支规则；补齐 src/cli_app.py，入口 python -m src.cli_app，全局 --data 默认 data/ledger.db，add 接受 --amount、--type、--category、--date、--note，list 列出账目。参考 exercise-assets/ledger-starter 中的固定契约，不随生成结果改接口。
请给出完整代码。

CLI 会读取（或创建）这两个文件并写入代码。

第 3 步：人工审查 CLI 生成的代码

养成习惯：不要盲目接受 AI 的输出。CLI 每次修改文件都会显示 diff（改动对比），你要：

1. 看它改了哪些文件、加了哪些行。
2. 理解逻辑：表结构对不对？金额用什么类型存？日期格式是否统一？
3. 发现问题就追问让 CLI 改，比如「金额应该用整数分存储，避免浮点精度问题，请修改」。

4.5 从函数到可操作的入口

使用已激活环境中的 python，第一次在全新的 data/ledger.db 运行以下命令；已有个人数据时改用独立实验路径：

python -m src.cli_app --data data/ledger.db add --amount 8000 --type 收入 --category 工资 --date 2026-09-01
python -m src.cli_app --data data/ledger.db add --amount 35 --type 支出 --category 餐饮 --date 2026-09-02
python -m src.cli_app --data data/ledger.db add --amount 12 --type 支出 --category 交通 --date 2026-09-03
python -m src.cli_app --data data/ledger.db list

预期三条数据，amount_cents 分别为 800000、3500、1200。下一章 summary/report --month 2026-09 的期望收入为 800000 分，支出 4700 分，结余 795300 分；完成该阶段后运行 python -m unittest discover -s tests -v。每章先确认入口存在且前一阶段测试通过，再增加功能。

4.6 第一次提交

功能写好、审查通过后，提交第一个 commit。

帮我把暂存区的文件提交了，提交信息符合 Conventional Commits 规范，描述这次新增了记账存储功能。

CLI 会执行 git add 和 git commit。你也可以手动操作，对比一下 CLI 生成 的 message 和你自己写的：

# 手动方式（所有 OS 通用）
git add .
git commit -m "feat: 新增记账录入与 SQLite 存储功能"

提交后查看历史确认：

git log --oneline

应该能看到刚才的提交记录。

到此，「家庭账本」有了骨架和第一个功能。下一章我们继续加功能，在实战中学习代码理解、功能开发和分支管理。

---