td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}

一、团队分工

1.1 项目介绍

本次现场编程，我们团队选择开发一款轻量级个人记账应用——CodeMind Ledger。

项目主要面向个人日常收支管理场景，用户可以记录收入与支出，按不同条件查询账单，并通过统计数据和分类图表了解自己的消费情况。

项目采用 Python + Flask + HTML/CSS/JavaScript 的技术方案，使用本地JSON文件保存记录，尽量减少环境配置和部署的复杂度，将开发重点放在业务功能实现、团队协作以及前后端集成上。

最终完成的主要功能包括：

1. 新增记账记录：选择收入或支出，填写金额、日期、类别和备注。

2. 记录管理：后端实现记录查询、修改和删除接口。

3. 条件筛选：支持按日期范围、收支类型、类别和金额区间筛选记录。

4. 收支统计：自动计算收入总额、支出总额、结余及记录数量。

5. 分类图表：通过气泡图和排行榜展示不同支出类别的金额。

6. 数据持久化：将记录保存至JSON文件，刷新页面或重启服务后仍能读取。

7. 异常输入处理：对非法金额、日期及不合理的筛选条件进行校验和提示。

1.2 团队成员职责分工

为使12名成员能够并行开发，我们将项目划分为数据层、业务层、统计层和Web集成层四个部分，进一步拆分为12个主要模块。

td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}

其中，组长罗宇泽除负责D1模块外，还承担任务划分、接口协调、Pull Request审查、代码合并和最终集成验收工作。

分工原则：

• 每名成员负责一个主要模块，明确职责边界。

• 各模块依据统一接口契约进行开发。

• 使用个人GitHub账号提交实际编写的代码。

• 通过Pull Request提交功能，由组长检查后合并。

• 集成过程中出现跨模块问题时，由相关成员协作解决。

【插入图片：团队分工表或GitHub各成员PR记录】

二、程序运行环境

2.1 开发环境

td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}

项目使用 requirements.txt 管理Python依赖，主要包括Flask和pytest。

2.2 项目运行步骤

第一步：克隆GitHub仓库。

git clone https://github.com/yz-Yezi-Genm/codemind-ledger.git
cd codemind-ledger

第二步：创建Python虚拟环境。

py -3.10 -m venv .venv

第三步：安装项目依赖。

.\.venv\Scripts\python.exe -m pip install -r requirements.txt

第四步：启动Flask服务。

.\.venv\Scripts\python.exe app.py

服务启动后，使用浏览器访问：

http://127.0.0.1:5000/

即可进入个人记账本界面。

2.3 自动化测试环境

在项目根目录执行：

python -m pytest -q

团队在正式版本集成验收时，自动化测试结果为：

179 passed

测试涵盖数据存储、字段校验、类别规则、记录操作、筛选、统计、图表数据以及Flask API等功能。

【插入图片：终端运行179项测试全部通过的截图】

三、软件运行截图和视频

3.1 软件首页

首页主要展示当前账单周期、收入与支出汇总，以及最近的记账记录。

用户可以从首页进入新增记账和账单统计页面。

【插入图片1：包含真实记账记录的首页截图】

3.2 新增收支记录

点击首页的新增按钮后，用户可以选择收入或支出类型，并填写金额、日期、类别和备注。

系统会根据收支类型提供不同的类别选项，并在提交时对数据进行校验。

【插入图片2：新增支出页面截图】

【插入图片3：新增收入成功后的首页截图】

3.3 账单筛选

系统支持以下筛选条件：

• 日期范围；

• 收入或支出类型；

• 收支类别；

• 最低金额与最高金额；

• 多个条件组合。

多个筛选条件之间采用“与”关系，只有符合全部条件的记录才会出现在结果中。

【插入图片4：组合筛选面板截图】

【插入图片5：组合筛选结果截图】

3.4 收支统计与分类图表

统计页面能够展示当前筛选范围内的收入、支出和结余。

同时，系统提供支出分类气泡图和排行榜，用于展示各支出类别的金额分布。

当前正式版本的分类图表展示全部日期的支出统计，与筛选后的收支汇总采用不同的统计范围，页面已标明这一点。

【插入图片6：收支统计及气泡图截图】

【插入图片7：支出分类排行榜截图】

3.5 异常输入处理

在实际测试中，我们分别尝试了开始日期晚于结束日期、最低金额大于最高金额、记账金额为零以及金额为空等情况。

程序能够提示不合法的输入，避免错误数据进入账本。

【插入图片8：异常日期范围提示截图】

【插入图片9：异常金额提示截图】

3.6 软件演示视频

通过网盘分享的文件：演示视频.mp4

链接: https://pan.baidu.com/s/1zS2YOOIxCJJ8DTOzJXTaig?pwd=vrm4 提取码: vrm4

四、软件实现的关键代码

本项目采用分层、模块化的设计方式。数据层负责记录存储和校验，业务层处理记录操作，统计层负责筛选和汇总，Flask路由将这些功能提供给前端调用。

以下代码节选自项目正式版本，展示若干关键实现。

4.1 JSON数据读取（A1）

文件：core/storage.py

def load_records():"""读取所有记录，首次不存在文件时返回空列表。"""try:# 使用UTF-8编码读取JSON文件with RECORDS_PATH.open("r", encoding="utf-8") as file:records = json.load(file)except FileNotFoundError:# 首次运行时没有账本文件，返回空列表return []# 检查JSON文件是否为记录字典组成的列表if not isinstance(records, list) or not all(isinstance(record, dict) for record in records):raise ValueError("记录数据必须是字典组成的列表")return records

实现说明：

项目通过统一的存储接口读取账本，而不是由不同业务模块分别访问JSON文件。

这样可以集中处理文件读取和数据结构检查，提高模块之间的一致性。

4.2 日期参数校验（C1）

文件：services/filters.py

def _parse_date(value):"""将日期字符串转换为date对象并检查合法性。"""# 同时支持date对象和字符串形式if isinstance(value, date):return value# 先检查YYYY-MM-DD格式if not isinstance(value, str) or not _DATE_PATTERN.fullmatch(value):raise ValueError(f"日期必须为 YYYY-MM-DD 格式：{value!r}")try:# 进一步检查是否为真实有效日期return date.fromisoformat(value)except ValueError:raise ValueError(f"日期必须是真实有效的日期：{value!r}") from None

实现说明：

日期校验分为格式检查和日期有效性检查两个步骤。

例如，2026-11-07 是合法日期，而 2026-13-40 虽然形状符合要求，但并不是真实存在的日期，应当被拒绝。

在组合筛选时，程序还会对日期上下限和金额上下限进行判断，保证返回结果符合筛选条件。

4.3 收支汇总统计（C2）

文件：services/statistics.py

def calculate_summary(records):"""统计传入的记录，不修改原始数据。"""income = Decimal("0")expense = Decimal("0")for record in records:amount = Decimal(str(record["amount"]))# 根据记录类型分别累加收入和支出if record["type"] == "income":income += amountelif record["type"] == "expense":expense += amountreturn {"income": float(income),"expense": float(expense),# 结余等于收入减去支出"balance": float(income - expense),"count": len(records),}

实现说明：

该函数将统计逻辑独立于Flask路由，输入记录列表后即可计算收入、支出、结余和记录数量。

其中使用 Decimal 累加金额，避免直接使用二进制浮点数进行连续累加时出现常见的精度偏差。

4.4 Flask新增记录接口（D1）

文件：app.py

@app.post("/api/records")
def create_record():"""新增一笔收入或支出记录。"""# 获取客户端发送的JSON数据data = request.get_json(silent=True)# 请求体必须是JSON对象if not isinstance(data, dict):return jsonify({"success": False,"error": "请求体必须是 JSON 对象"}), 400try:# 调用B1模块实现新增记录new_record = add_record(data)# 新增成功，返回201状态码及记录return jsonify({"success": True,"data": new_record}), 201except ValueError as error:# 输入数据不合法，返回400状态码return jsonify({"success": False,"error": str(error)}), 400except NotImplementedError:return jsonify({"success": False,"error": "新增记录依赖的模块尚未完成"}), 501except Exception:# 记录服务器异常，避免直接向用户暴露内部细节app.logger.exception("新增记录时发生服务器异常")return jsonify({"success": False,"error": "服务器处理新增记录时发生错误"}), 500

实现说明：

D1主要负责将各成员的业务模块整合为统一的HTTP API。

以新增记录为例，Flask路由负责接收请求、检查请求体、调用B1提供的新增服务，并根据处理结果返回HTTP状态码。

这种实现方式使Web接口与业务逻辑相互分离，也便于后续编写接口测试。

4.5 修改记录时的部分字段校验（B2）

文件：services/record_edit.py

# 去除记录ID，仅保留允许编辑的字段
updates_to_apply = {key: value for key, value in updates.items() if key != "id"
}# 先对提交的部分字段进行校验
validate_partial(updates_to_apply)# 将更新字段与已有记录合并
updated_record = {**records[record_index], **updates_to_apply}
updated_record["id"] = record_id# 合并后再次校验完整记录
validate_record(updated_record)

实现说明：

用户编辑记录时，可能只更新金额或备注，而不会重新提交全部字段。

因此，B2先使用部分校验函数检查更新内容，再与原记录合并，最后执行完整校验。

这种两阶段校验方式可以同时保证编辑操作的灵活性和记录数据的一致性。

五、软件的亮点

5.1 亮点一：12人模块化开发与接口契约设计

本项目的一项特点是将完整的个人记账应用拆分为12个职责清晰的模块。

开发前，团队通过 docs/CONTRACT.md 统一约定记录结构、函数签名及API路径，使成员能够在不同分支上独立开发。

例如：

• A1统一负责JSON读写；

• B1、B2调用A1实现记录的新增、修改和删除；

• C1负责筛选，C2负责统计；

• D1通过Flask连接各业务模块；

• D2、D3分别负责页面和交互。

这种设计降低了多人开发时的文件冲突，也让团队能够通过GitHub记录各成员的实际贡献。

5.2 亮点二：支持多条件组合筛选与边界输入校验

与仅能按照日期查询的简单记账工具相比，本项目支持同时使用日期、类型、类别和金额范围等多个条件筛选账单。

筛选逻辑集中在独立的服务模块中，不直接修改原始记录数据。

同时，开发过程中考虑了非法日期、非有限金额以及筛选边界等情况，避免不合理输入影响后续统计。

例如，最低金额和最高金额相等时，可以筛选对应金额的记录；金额或日期不合法时，则返回错误信息。

5.3 亮点三：收支统计与分类可视化结合

项目不仅支持保存和查询账单，还能够根据记录计算收入、支出和结余。

统计结果通过页面直观展示，支出类别进一步以气泡图和排行榜两种形式呈现。

其中，统计模块使用 Decimal 进行金额累加，图表数据由独立模块统一计算，前端只负责展示。

这种分工既增强了用户体验，也便于测试统计结果的正确性。

六、开发过程中收获较大的事件

本次现场编程中，我们遇到的不仅是单个函数的编写问题，还包括多人协作、接口衔接和边界规则统一等问题。以下列出三项具有代表性的事件。

6.1 事件一：前端页面结构与JavaScript交互的衔接

问题背景：

D2负责HTML/CSS页面，D3负责JavaScript交互。两名成员分别开发时，需要共同遵守页面元素ID、表单字段名和事件触发方式等约定。

在实际集成过程中，筛选抽屉的展开方式、页面元素以及JavaScript交互需要进一步统一。

解决过程：

D2、D3分别修改页面结构和交互逻辑，将筛选面板统一为原生 details/summary 的展开方式，并同步调整JavaScript事件处理。

GitHub中可以看到相关修改：

• 4418476：D2统一筛选抽屉结构。

• ab60f1f：D3调整原生筛选展开逻辑并对齐页面渲染。

收获：

这次问题使我们认识到，前后端协作不仅需要统一后端API，前端页面结构本身也存在接口约定。

当两个成员分别负责页面和交互时，必须事先约定元素名称和行为，修改时及时通知对方，否则容易在集成阶段产生问题。

6.2 事件二：金额精度与异常数据的边界校验

问题背景：

在A2数据校验及C1组合筛选的开发中，团队需要处理一些容易被忽略的异常输入。

例如，极小金额、浮点数精度、无穷大、NaN以及格式不正确的日期等。

简单使用 float 转换和普通比较，不能完整覆盖这些情况。

解决过程：

A2在提交记录中多次调整金额校验规则，对极小金额、Decimal输入和浮点数误差进行处理。

C1也增加了严格日期格式检查，并使用 math.isfinite() 排除非有限金额。

可以追溯的相关提交包括：

• f120f7f：C1补充非有限金额与严格日期格式检查。

• df01e95：A2调整大额数据下的浮点容差。

收获：

这次经历说明，程序不仅需要处理正常数据，还必须考虑边界值和非法输入。

通过补充测试用例、反复修改校验规则，我们更加重视数据合法性与回归测试，而不是仅凭几个正常输入判断功能已经完成。

6.3 事件三：编辑记录时的部分校验与完整校验

问题背景：

B2最初实现修改记录功能时，需要与A2的数据校验模块对接。

新增记录与编辑记录的输入形式并不完全相同：新增时通常包含完整字段，而编辑时可能只提交需要修改的字段。

若直接对部分更新内容进行完整记录校验，可能会因为缺少未修改字段而发生错误。

解决过程：

B2在后续增强中接入A2提供的 validate_partial()，先对本次更新字段进行检查，再合并原记录并调用 validate_record() 进行完整校验。

该改动通过独立的Pull Request提交：

PR #12：接入编辑记录部分校验

相关测试覆盖了未知字段、修改类型后类别不匹配、真实JSON存储及删除等场景。

收获：

本次问题体现了模块独立开发后进行接口集成的重要性。

一个模块自身通过测试，并不代表它与其他模块组合后一定正确。只有结合真实依赖进行集成测试，才能进一步发现接口使用方式和业务规则上的问题。

七、每个组员的团队编程体验

本节由12名团队成员结合本人实际开发经历填写，重点说明所承担的任务、遇到的困难、解决方式以及本次团队编程的收获。

7.1 王智洋（A1：JSON存储）

【由王智洋本人填写。建议结合JSON文件读写、异常处理和存储测试，介绍实际开发中的困难与收获。】

7.2 颜俊宇（A2：数据校验）

【由颜俊宇本人填写。建议结合金额精度、非法日期和类别规则的处理过程。】

7.3 薛锦荣（A3：类别管理）

【由薛锦荣本人填写。建议结合收入支出类别设计及与A2的接口配合。】

7.4 洪添军（B1：新增记录）

【由洪添军本人填写。建议结合唯一ID生成、数据保存和参数校验。】

7.5 赵紫龙（B2：修改与删除）

本次团队编程中，我负责 B2“修改与删除”模块，主要实现 services/record_edit.py 中的 update_record 和 delete_record。update_record 先按 id 查找目标记录，检查更新内容是否为对象且不允许修改原 id；随后将更新字段与原记录合并，先做部分字段校验，再对合并结果进行完整校验，最后通过统一存储接口保存。delete_record 同样按 id 定位记录，只删除目标项，并在记录不存在时返回 False，便于上层 API 统一处理。

开发中遇到的主要问题是怎样安全地修改一条完整记录。如果只校验客户端本次传入的字段，可能漏掉修改 type 后新旧 category 不匹配，或者日期、金额等问题；如果直接修改原对象，又可能在后续校验失败时污染已加载的数据。为此，我将更新拆成“ID 检查—部分字段校验—合并—完整校验—保存”几个步骤，并通过新建字典和列表避免在成功保存前改写原数据。

在 PR 审查和后续增强中，我将 A2 提供的 validate_partial 接入编辑流程，同时保留合并后的 validate_record，并补充了未知字段、类型与类别不匹配、校验失败不写文件、记录不存在，以及修改和删除真实存储等测试。这个过程让我认识到，接口设计不仅要覆盖正常路径，还要明确错误返回、数据一致性和模块边界；团队协作中及时同步接口契约并开展集成测试，也比只依赖各自模块的隔离测试更可靠。

7.6 林彦翔（B3：最近记录）

【由林彦翔本人填写。建议结合同日排序、数量限制和记录查询。】

7.7 雷葭雨（C1：组合筛选）

本次我承担C1 筛选模块，主要任务是实现 filter_records 函数。一开始觉得逻辑不复杂，把几个条件判断清楚就够了，动手之后才发现，真正要花心思的是边界处理：日期和金额都要包含端点，传进来的参数还可能是空值、无穷值或者格式不对的字符串。根据评审意见，我补上了金额的有限性检查和日期的严格格式校验，又增加了一批针对异常输入的测试。这次做下来我比较直接的感受是，自己写代码时总想着正常情况，复审的人站在调用方的角度，反而更容易看出问题，这部分比单纯把功能做出来更让我有收获。

7.8 吴欣键（C2：收支统计）

【由吴欣键本人填写。建议结合Decimal金额统计及单元测试。】

7.9 林世颖（C3：分类图表）

【由林世颖本人填写。建议结合分类汇总逻辑及与前端图表的配合。】

7.10 罗宇泽（D1：Flask API集成）

【以下为待本人审核的初稿，可根据实际经历修改。】

本次团队编程中，我主要负责Flask路由及后端模块集成，同时承担组长的项目协调工作。

与单独完成一个程序不同，团队编程需要提前考虑不同模块之间如何配合。本次项目将存储、校验、业务操作、统计和前端分别交给不同成员完成，因此我在编写API时，需要根据统一接口契约调用各模块，并处理数据校验失败、记录不存在及服务器异常等情况。

在集成过程中，我也逐渐认识到，完成自己的模块并不是整个开发任务的终点。只有各模块成功合并、通过整体测试，并且能在浏览器中完成实际业务操作，才能说明软件基本达到可交付状态。

通过本次实践，我进一步熟悉了Flask接口开发、GitHub分支协作、Pull Request审查以及软件集成验收流程，也体会到了团队沟通和统一规范的重要性。

7.11 吴诗莹（D2：前端页面）

这次团队编程让我深刻体会到了多人协作与个人开发的区别。团队按照不同模块分工，通过 Git 分支、Commit 和 Pull Request 并行开发，提高了效率，但也暴露出模块衔接的问题。在与 D3 前端交互负责人丁晓炜同学联调时，虽然前期已对 DOM 结构、元素 ID 和页面状态管理进行了约定，但部分细节规定不够具体，导致模块合并后出现了一些兼容性问题。经过沟通与调整，我们最终统一了相关规范。这让我认识到，团队开发不仅需要明确 API 和数据格式，还应提前约定前端结构与交互方式，并尽早开展联调，并根据模块合并后的实际运行效果及时调整和完善。

我个人主要负责 D2 前端页面，包括 HTML 结构、CSS 手机外框、首页、记账页、统计页、表单、记录列表及分类气泡图等。开发初期，我更注重页面的视觉效果，使用了部分静态示例数据。联调后，我逐渐意识到页面还需要支持动态数据更新和真实交互，因此将静态内容调整为动态容器，并完善了表单、筛选和提示功能。这次实践提升了我在 HTML、CSS、Flask 模板及 Git 协作方面的能力，也让我理解了前端开发不仅要注重美观，更要保证结构清晰、功能完整以及与其他模块的兼容性。

7.12 丁晓炜（D3：前端交互）

本次团队编程中，我主要负责 static/app.js 中的前端交互，包括 API 调用、页面切换、记账表单提交、数据刷新、条件筛选以及分类气泡图交互。

与单独编写页面不同，前端交互需要同时配合页面结构和后端接口。我与负责页面结构和样式的吴诗莹同学进行配合，针对页面元素命名和交互方式存在的差异，对照统一接口契约，逐项统一按钮 ID、表单字段和状态类，并确定使用原生 / 控制筛选面板，避免多种展开方式相互冲突。

在功能完善过程中，我补充了分类筛选后的恢复入口，以及最近五笔与全部记录之间的切换，同时处理请求失败、重复提交和保存失败后保留输入等情况。相关功能已使用吴诗莹同学完成的实际页面配合模拟接口进行浏览器验证，真实后端的完整业务流程仍需进一步联调。

通过本次实践，我进一步熟悉了 JavaScript 异步请求、动态数据渲染和 GitHub 分支协作，也认识到完成自己的模块只是第一步。只有统一接口约定、及时沟通问题，并在整合后验证实际操作流程，才能让各模块顺利配合。

八、SP参考

参考资料：

SP参考资料：博客园文章

九、GitHub仓库地址和Commit记录

9.1 GitHub仓库地址

项目仓库：

https://github.com/yz-Yezi-Genm/codemind-ledger

正式版本：

https://github.com/yz-Yezi-Genm/codemind-ledger/releases/tag/v1.0.0

本次项目采用GitHub进行代码托管、任务分支管理、Pull Request代码审查以及最终版本发布。

9.2 团队Pull Request记录

以下是主要功能模块的PR记录：

td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}

上述13个PR均已在v1.0.0发布前合并。

【插入图片：GitHub Pull Requests 已合并列表截图】

9.3 具有代表性的Commit记录

以下列出部分能够体现真实开发和修改过程的提交：

td {white-space:nowrap;border:0.5pt solid #dee0e3;font-size:10pt;font-style:normal;font-weight:normal;vertical-align:middle;word-break:normal;word-wrap:normal;}

完整Commit历史：

https://github.com/yz-Yezi-Genm/codemind-ledger/commits/main/

9.4 GitHub Release发布

2026年11月7日16:55，团队发布了正式版本：

CodeMind Ledger v1.0.0

该版本包含已完成的12个主要功能模块以及相应测试文件。

Release链接：

https://github.com/yz-Yezi-Genm/codemind-ledger/releases/tag/v1.0.0

【插入图片：Release v1.0.0页面截图】

版本发布后，团队又通过PR #15更新了README项目说明。

此外，A1曾提交后续存储增强PR #14，涉及原子写入和备份恢复，但该PR未合并，因此不计入v1.0.0已交付功能。

通过本次现场编程，我们完成了从任务划分、独立开发、GitHub协作，到模块整合、测试和正式版本发布的完整实践流程，也对多人协作中的接口规范、代码复审和软件质量保障有了更深入的认识。