有数记账：现场编程团队项目总结

一、项目简介

「有数记账」是一款通过浏览器使用、由本机 Python 服务提供接口、以 JSON 文件保存账目的个人记账软件。用户可以新增、编辑、删除收入和支出，按日期、收支类型、类别、金额和备注组合筛选，查看汇总和支出分类图。项目还加入了 CSV 导出、月度预算、JSON 备份恢复、一句话记账和新版概览页面等功能。

本项目把金额保存为整数分，避免浮点数累计误差；账本默认位于项目目录的 data/ledger.json。应用只监听本机地址，适合本地个人使用和课堂演示，不提供公网或多人共享服务。

二、职责分工与 GitHub 协作

团队按功能模块划分开发工作，并安排文档、测试和演示协作。

三、运行环境与启动方式

• Python 3.10 或更新版本；开发验证记录使用 Python 3.13。
• 现代浏览器：Chrome、Edge、Firefox 或 Safari（需支持 HTML dialog 元素）。
• 前端使用原生 HTML、CSS 和 JavaScript，后端使用 Python 标准库，无需安装第三方运行依赖。
• 在项目目录运行：

python app.py --open

浏览器访问 http://127.0.0.1:8000。首次保存时会生成 data/ledger.json。如需课堂演示，建议用独立演示账本，避免录入或展示个人真实收支：

python app.py --data .qa/demo.json --port 8001 --open

运行测试：

python -m unittest discover -s tests -v

四、软件截图与演示视频

演示视频：点击观看《记账本演示》

五、关键代码

1. 金额精度与输入校验

ledger/models.py 使用 Decimal 解析金额，并转换为整数分。这样 0.10 和 0.20 相加时不会受到二进制浮点表示误差影响；同时拒绝负数、超出范围的金额及超过两位的小数。

def parse_amount(value, allow_zero=False):if isinstance(value, bool) or not isinstance(value, (str, int, float)):raise ValueError("请输入正确的金额")try:amount = Decimal(str(value).strip())  # 使用十进制解析，避免二进制浮点误差if not amount.is_finite() or amount < 0 or amount > Decimal(MAX_CENTS) / 100:raise ValueError("金额应在 0.01 至 9,999,999,999.99 元之间")cents = amount * 100                   # 统一转换为整数分保存if cents != cents.to_integral_value():raise ValueError("金额最多保留两位小数")if cents == 0 and not allow_zero:raise ValueError("金额必须大于 0")return int(cents)except (InvalidOperation, OverflowError):raise ValueError("请输入正确的金额") from None

2. 组合筛选并统一汇总口径

ledger/service.py 的 LedgerService.query 将日期、金额、类型、类别和备注关键字条件应用到同一组记录，再从筛选结果计算收入、支出、结余和分类统计。因此明细与基础汇总使用同一数据范围。

selected = [r for r in self.records if(not start or r.date >= start) and (not end or r.date <= end)and (low is None or r.amount_cents >= low)and (high is None or r.amount_cents <= high)and (not kind or r.kind == kind)and (not category or r.category == category)and (not search or search in (r.note + " " + r.category).casefold())]income = sum(r.amount_cents for r in selected if r.kind == "income")
expense = sum(r.amount_cents for r in selected if r.kind == "expense")
return {"summary": {"income_cents": income, "expense_cents": expense,"balance_cents": income - expense, "count": len(selected)},# 分类统计也从同一筛选结果计算，保证汇总口径一致。"expense_categories": [{"category": name, "amount_cents": amount}for name, amount in sorted(by_category.items(),key=lambda item: (-item[1], item[0]))],
}

3. JSON 原子写入

ledger/storage.py 在写入前检查账本是否被外部修改，将新内容写到同目录临时文件并原子替换目标文件。成功后才更新内存中的文件快照；写入失败时保留原账本。

current = self.path.read_bytes() if self.path.exists() else None
if current != self._snapshot:raise StorageError("账本文件已被其他程序修改，请重启本程序后再操作")
raw = (json.dumps({"version": 1, "records": [r.to_dict() for r in records]},ensure_ascii=False, indent=2) + "\n").encode("utf-8")
_write_atomic(self.path, raw, ".ledger-")
self._snapshot = raw

以上为便于说明的节选，完整校验和异常处理请以仓库源码为准。

六、项目亮点

1. 精确金额与可靠本地保存:金额以整数分存储；写入采用原子替换，并对损坏文件、外部修改和写入失败提供保护。
2. 多条件查询与 CSV 导出:日期、类别、收支类型、金额范围和备注关键字可以组合筛选；CSV 导出全部匹配记录而非仅当前分页，包含中文表头，并对备注中的公式前缀进行处理。
3. 便捷录入与数据保护:一句话解析会生成待确认草稿，不会在解析时直接写入账本；JSON 恢复前会校验文件、展示预览并保留恢复前账本。

以上功能可在演示视频里查看

七、编码与复审中的收获

以下事件依据项目测试和交付记录整理。总投入约 4 小时，各事件没有单独计时，表中耗时为回顾估算。

这三个事件的估算合计约 100 分钟，仅覆盖部分重点工作，其余投入用于需求分析、设计、其他模块编码、界面调整及交付材料整理。

八、团队编程体验

林志涛（102401614）

围绕基础记账应用和模块整合，我最关注的是各部分连接后能否形成完整的使用流程。记录、查询、统计和备份分别能够运行，还需要共同遵守数据格式与接口约定。我认为集成工作应尽早开展，后续希望把模块边界和验收条件写得更清楚，方便组员并行推进。

任奥辉（102401512）

备份恢复界面让我关注数据操作的确认流程。用户需要在恢复前看清记录数量、日期范围和替换范围，不能仅凭一个成功提示判断结果。我认为与后端协作时，除了明确成功返回的数据，还要约定校验失败时怎样提示，以及如何保护原账本。

吴瑞鹏（102401509）

在博客统稿这项任务中，我希望把成员提供的材料整理为连贯的项目说明，让功能介绍、代码节选、截图和提交记录相互对应。整理时需要向模块负责人核对信息，避免只列出功能名称。完成后，我也希望通过这份文档帮助读者理解团队的设计选择和协作过程。

朱铮睿（102401625）

CSV 下载交互需要把已应用的筛选条件准确传给接口，并清楚反馈下载状态。我最关注的是导出范围：用户应当得到全部匹配记录，而不是只得到当前页。前后端需要共同约定文件格式、错误提示和按钮状态，这也让我认识到交互细节属于功能完整性的一部分。

尼玛顿珠（102401635）

预算前端需要把月份、已用金额、剩余额度和超支状态组织成容易理解的信息。我认为界面设计不仅要展示数值，还应说明统计范围。与后端对接时，应先确认未设置预算、正常使用和超支等状态，减少界面显示与实际数据含义不一致的问题。

林富强（102401510）

在接口和运行文档整理中，我希望从首次使用者的角度检查说明是否充分。启动命令、端口、数据文件位置和接口字段都应能够直接核对。我认为文档应跟随代码更新，尤其需要区分筛选统计与整月统计，帮助开发人员和使用者理解同一组数据。

丁鑫河（102401525）

测试协作需要把“看起来能用”转化为可以重复检查的结果。我计划同时关注正常流程和边界情况，例如空结果、无效金额、下载失败及恢复取消。记录问题时，应保留明确的复现步骤，并分别记录自动化测试与浏览器操作结果，方便模块负责人定位问题。

林鹏远（102401526）

准备截图和录屏时，我希望通过简短的操作顺序展示完整流程，而不只是展示静态页面。演示数据需要容易核算，截图也应与最终界面保持一致。录制前应先走通新增、筛选、导出和备份等步骤，再检查画面清晰度以及视频链接是否能够正常访问。

何锦宏（102401511）

CSV 导出接口让我关注筛选结果、文件编码和表格兼容性之间的联系。导出需要与查询保持同一口径，同时处理中文、逗号、换行和公式前缀等内容。我认为先与前端负责人明确接口参数和响应约定，再用样例核对文件内容，可以减少对接时的理解偏差。

曾林远见（102401519）

月份统计需要明确月份顺序、跨年边界和无记录月份的处理方式。我最关注的是接口数据是否稳定、便于前端直接展示。与图表负责人协作时，应先约定返回结构和金额单位，再核对不同日期范围的汇总结果，避免统计与展示分别采用不同口径。

杜佳伟（102401623）

协作记录和交付核查需要把人员分工、代码提交与最终成果对应起来。我计划逐项检查 PR、commit、Release 和博客链接，并向成员确认缺失的信息。我认为交付材料应当反映真实工作，同时提供清晰的入口，让助教能够核对模块实现与成员贡献。

翁斌（102401632）

一句话记账和新版概览需要同时考虑录入效率、识别边界与展示口径。我认为识别结果应先让用户确认，再写入账本；界面图表也应明确采用全部账目还是筛选结果。后续希望继续完善异常输入提示，并在界面更新后检查资源加载和实际浏览器表现。

严科儒（102401633）

预算后端需要让月份校验、金额存储和支出汇总保持一致。我最关注的是预算与账目之间的关系：新增、修改或删除支出后，预算使用情况应准确反映变化。与前端协作时，应把字段含义和特殊状态约定清楚，并通过边界数据检查计算结果。

九、SP / PSP 时间记录

本次团队现场编程总耗时约 4 小时（240 分钟）。由于没有逐项计时，以下各阶段时间为根据任务内容整理的回顾估算，需结合成员实际投入核对，不作为精确计时记录。表中统计的是团队任务推进的时间分配，不是 13 位成员累计的人时；计划时间未单独记录，无法准确计算计划与实际的偏差。

时间复盘：后续协作应从任务开始时分别记录计划与实际耗时，特别是模块集成、代码复审和问题修复的时间，便于区分编码投入与沟通成本，并改进下一次任务估算。

十、仓库、Release 与提交记录

• GitHub 仓库：fzu-404-team/account-book
• 已关闭 PR：Pull Requests
• 主分支提交记录：Commits
• Release：demo（标题：有数记账 v1.0.0）
• 测试命令：python -m unittest discover -s tests。
• 最终测试结果：2026 年 11 月 7 日重新运行全部自动化测试，共 28 项，全部通过，输出为 Ran 28 tests 和 OK。
• 测试范围：金额精度与输入校验、账目增删改查及持久化、组合筛选与汇总、CSV 导出、备份恢复、一句话记账解析，以及 HTTP 接口和静态资源访问。
• 验证限制：上述结果为自动化测试结果，不代表所有浏览器和真实手机均已完成验证。

十一、贡献评分

按组长提供的贡献分配结果，各成员贡献系数如下。设小组最终得分为 S，则个人分数为 S × 贡献系数；其中 100% 表示获得与小组分数相同的个人分数，并非占全组贡献的 100%。

十二、工具使用说明

本项目使用 Git、GitHub 进行版本管理和协作，通过 Issue 拆分任务、Pull Request 复审与合并代码。开发过程中使用了 Codex 辅助工具，协助分析问题、检查代码和测试结果、排查页面资源加载故障、修改局域网访问配置，以及整理博客初稿、时间估算和个人体验草稿。项目部分代码包含辅助生成内容，具体范围由对应成员核实。