7. 综合实战与交付

来源：Qoder

走到这里，你的「记账小管家」已经能记账、能汇总、能按分类统计，还有测试兜底、有 git 记录。它从一个空文件夹，长成了一个像样的小工具。

但一个「自己能跑」的工具，和一个「拿得出手、能交给别人用」的作品，中间还差最后一段路。这一章，我们就来走完它：加一个真正实用的功能、写一份让别人一看就懂的文档、再把整个项目的收尾工作做得漂漂亮亮。

做完这一章，你收获的不仅是一个完整的记账工具，更是一套「如何有始有终地做完一个项目」的完整经验。

7.1 加一个「拿得出手」的功能：导出月度报告

记账的最终价值，是能回头看清「这个月我的钱都花哪儿了」。所以我们的收官功能，就做一个导出月度消费报告——把某个月的收支，整理成一份清清楚楚的报告，还能导出成文件保存下来。

唤醒 Qoder，把需求讲清楚（记得我们的老规矩：让它先说思路，你同意了再动手）：

我想加最后一个功能：生成月度报告。

• 我可以指定某个月（比如 2026-09），它就把那个月的账目汇总出来：总收入、总支出、结余，以及按分类的消费明细；
• 报告先在命令行里好看地打印出来；
• 再支持导出成一个 CSV 文件，方便我用 Excel 打开或者存档。
  你先讲讲打算怎么实现，尤其是 CSV 导出这块，我同意了再写。写完之后，别忘了给这个新功能补上单元测试，并跑一遍全部测试确保没弄坏老功能。

你看，这段话里我们把前几章养成的习惯全都自然地带上了：先方案后动手、写完补测试、跑全量测试保平安。这些已经不再是我提醒你才做的事，而是变成了你提需求时的「标准动作」——这就是成长。

等 Qoder 实现完，你亲自验证一下：

python ledger.py --data data/course-september.json report --month 2026-09
python ledger.py --data data/course-september.json report --month 2026-09 --export report.csv

（命令名、字段与单位沿用第 4 章固定契约。）第一条在终端里打印报告，第二条会额外生成一个 report.csv 文件。你可以用 Excel 或任意表格软件打开那个 CSV 看看，数据是不是一目了然。

验证通过后，存档：

提交前先在 .gitignore 加入 report.csv、reports/、data/；保留课程 fixtures，不要用宽泛规则误忽略样例。检查 git diff --cached，已暂存的报告用 git restore --staged -- report.csv 取消暂存；已经提交的报告需另作移除提交，添加忽略规则不会清除历史。

git add ledger.py tests README.md .gitignore
git commit -m "feat: 支持生成并导出月度消费报告"

小提醒：导出的 report.csv 是你的个人数据产物，和之前的 data/ 目录一样，通常不该提交到 git。如果发现 git status 里冒出了 .csv 文件，可以在 .gitignore 里加一行 *.csv 把它们排除掉，再提交。

7.2 让 Qoder 帮你写文档

一个好项目，得有一份「说明书」，让别人（也包括三个月后已经忘了细节的你）打开就知道这是啥、怎么用。这份说明通常写在一个叫 README.md 的文件里。

写文档是件枯燥的事，而这正是 Qoder 的强项。跟它说：

帮我给这个项目写一份 README.md。要包含：这个项目是干什么的、需要怎么安装和运行、每个命令怎么用（记账、汇总、按分类统计、月度报告都写上，最好各给一个例子）、以及数据是怎么存的。语气友好一点，让没用过的人一看就会上手。

Qoder 会通读你的代码，然后写出一份结构清晰的 README。你读一遍，看看有没有和实际不符的地方——它偶尔会「想当然」地写上一个其实并不存在的用法，所以审核这一步不能省。有不对的地方，直接告诉它改。

写好了，提交：

git add ledger.py tests README.md .gitignore
git commit -m "docs: 添加项目 README 使用说明"

到这里，你的项目就有了代码、有测试、有文档——三件套齐活，这是一个「正经项目」该有的样子。

7.3 交付前把把关：/review、/security-scan、/export

代码写完、文档也有了，别急着收工。一个负责任的项目，在「交付」前还应该过两道检查。这正是把前面学的 skill 用起来的好时机。

第一道：代码审查 /review。 在对话框敲 /review，让 Qoder 以「审查者」的身份把你这一版代码通读一遍，挑出潜在问题：有没有边界情况没处理、有没有写得别扭的地方、有没有更清晰的写法。它给出的意见你不必全盘接受，但值得逐条看一眼——这就像交卷前自己再检查一遍，常常能捞出一些藏得比较深的小毛病。

第二道：安全扫描 /security-scan。 敲 /security-scan，让它检查代码里有没有安全隐患（比如把敏感信息硬编码、对用户输入缺乏校验等）。对我们这个小工具来说也许问题不多，但养成「交付前扫一遍安全」的意识非常重要——将来你写的是真实上线、别人会用的程序时，这一步能帮你避开大麻烦。

两道检查过完、该修的修好、该提交的提交，你就可以把这个版本「封存」了。这时可以用 /export 把你和 Qoder 这一路的对话导出保存成一个文件——它相当于你这个项目的「开发过程记录」，将来回顾「当初这个功能是怎么一步步做出来的」，会非常有价值。

7.4 收尾：整理出一份漂亮的提交历史

现在我们来欣赏一下自己的劳动成果。敲：

git log --oneline

你应该能看到一串清晰的提交记录，从上到下大概是这样一条成长轨迹（具体文字以你的为准）：

docs: 添加项目 README 使用说明
feat: 支持生成并导出月度消费报告
refactor: 重构数据结构并支持按分类统计
test: 为记账和统计功能添加单元测试
feat: 增加收支汇总统计
feat: 实现记一笔账功能
chore: 初始化项目

停下来，认真看一眼这个列表。 它就像一部浓缩的开发史，每一步做了什么、按什么顺序做的，一目了然。这就是我们从第一章就坚持「小步提交 + 规范前缀」的回报——现在，任何人（包括未来的你）看一眼这段历史，就能明白这个项目是怎么一步步长起来的。

如果你想给这个「第一个完整版本」做个特别的标记，可以打一个 tag（标签），相当于在历史上插一面纪念旗帜：

git tag v1.0

以后敲 git tag 就能看到它。这个 v1.0 就代表着「记账小管家的第一个正式版本」。

7.5 进阶一步（可选）：把项目备份到远程仓库

先在自己的 GitHub 账号创建目标仓库，复制其 URL；本节只备份已确认不含个人账目和凭证的提交。

git remote -v
git branch --show-current

没有 origin 时运行 git remote add origin <你创建的仓库URL>（替换占位符）；已有 origin 则先确认目标，不能覆盖指向。随后 git push -u origin main，按 Git 的认证提示完成操作，并在仓库页面核对提交号。

/setup-github 是 GitHub Actions 集成入口，不是首次 remote/push 的替代命令；当前官方说明 CN 版本不可用，作为独立选修看待。

7.6 回顾：这一路，你到底学会了什么

在合上这个项目之前，我们花点时间回头看一眼。你从第 1 章那个「Qoder 是什么都还不太清楚」的状态，到现在，其实已经悄悄掌握了一整套东西：

关于 Qoder 的核心能力，你亲手用过：

• 和它对话、把需求讲清楚；
• 用 /plan 让它先规划、再动手，并通过 /diff /review 审核它的每一步改动；
• 遇到 bug 时用 /debug 找根因、做修复；
• 让它写测试、用 /verify 把关，给自己建一张安全网；
• 在测试保护下用 /simplify 放心重构、加功能；
• 用 Explore / Plan / general-purpose 子代理探索代码库，用 skills、MCP、记忆等进阶能力；
• 改坏了用 /rewind 一键撤销，用会话命令保持上下文干净；
• 让它写文档，用 /review /security-scan 做交付前把关，用 /export 存档开发过程，用 Git remote/push 推送到远程。

关于开发习惯，你已经内化了：

• 小步提交：做完一小步就存档，从不憋大招；
• 规范提交信息：用 feat / fix / docs / test / refactor 前缀，让历史可读；
• 先方案后动手：让 AI 先讲思路，确认了再写，少返工；
• 每次改动都审核：方向盘始终在自己手里；
• 改完跑测试：确保没弄坏老功能；
• 危险操作先问清楚：回退、推送这类高风险动作，不盲干。

说实话，这套习惯，比这个记账工具本身值钱得多。 工具是你练手的载体，而这些习惯会跟着你走进未来每一个项目。

---

到这里，我们的实战部分就圆满收官了。你已经用 Qoder 从零做出了一个完整、可用、有文档、有版本管理的小项目。

最后一章，我们回到第 1 章埋下的那个伏笔——去看看 Qoder 的图形化形态 Desktop / IDE 长什么样、怎么用，以及它和我们用了一路的 CLI 到底该怎么选。

翻到第 8 章，我们给整本教程画个圆满的句号。