软件工程第二次作业

软件工程第二次个人作业

一、作业基本信息

这个作业属于哪个课程	https://edu.cnblogs.com/campus/fzu/202601SofwareEngineering
这个作业要求在哪里	https://edu.cnblogs.com/campus/fzu/202601SofwareEngineering/homework/16717
这个作业的目标	使用 Python 和 AIGC 完成“一箭又一箭”小游戏
学号	102401601

---

二、项目展示

本次作业实现了一个基于 Python 和 Pygame 的点击式箭头解谜小游戏“一箭又一箭”。

游戏采用 6×6 棋盘，每个箭头具有上、下、左、右四种方向之一。玩家点击箭头后，程序会沿箭头指向的方向检查路径。如果从箭头前方到棋盘边界之间不存在其他箭头，则该箭头可以飞出棋盘；如果存在其他箭头阻挡，则本次点击失败，并消耗一次失误机会。

游戏目前包含 3 个可通关关卡，并实现了开始界面、关卡切换、失败重试、本关通过、全部通关、箭头飞出动画以及碰撞反馈等功能。

2.1 开始界面

2.2 游戏主界面

2.3 本关通过

2.4 挑战失败

2.5 全部通关

2.6 演示视频

点击查看

---

三、项目设计与实现

3.1 开发环境

本项目主要开发环境如下：

• Python 3.13.14
• Pygame 2.6.1
• Windows
• Git / GitHub
• Codex（AIGC / Coding Agent）
• Python unittest

项目通过以下命令启动：

python main.py

自动测试通过以下命令运行：

python -m unittest discover -s tests -v

最终共有 34 个单元测试全部通过。

3.2 项目结构

为了避免将所有逻辑堆积在一个文件中，我在开发过程中逐步对游戏进行了模块划分。

ArrowGame/
├── docs/
│   └── images/
├── tests/
├── main.py
├── board.py
├── models.py
├── path_detection.py
├── game_logic.py
├── state_logic.py
├── requirements.txt
├── .gitignore
└── README.md

各文件主要职责如下：

• main.py：负责 Pygame 主循环、UI、输入、动画和状态展示。
• board.py：负责棋盘、箭头绘制和三个关卡的数据。
• models.py：定义箭头、方向、飞行动画和游戏状态等数据结构。
• path_detection.py：负责实现核心路径阻挡检测算法。
• game_logic.py：负责点击箭头之后的核心游戏处理。
• state_logic.py：负责通关、失败、重新开始和关卡导航。
• tests/：存放基于 unittest 编写的自动测试。

这样的拆分也让我在后续测试时可以直接测试核心 Python 逻辑，而不需要每次都启动完整的 Pygame 界面。

---

四、核心算法：箭头路径检测

本项目最重要的逻辑是判断一个箭头的前方是否存在其他箭头。

首先，将四个方向转换成二维坐标变化量：

UP    = (-1, 0)
DOWN  = (1, 0)
LEFT  = (0, -1)
RIGHT = (0, 1)

例如，一个向右箭头对应 (0, 1)，表示行号保持不变，列号每次增加 1。

路径检测并不是从箭头当前所在位置开始，而是从它的下一格开始。如果从当前位置开始检查，那么箭头本身就会被识别成障碍物。

因此算法过程可以概括为：

1. 根据箭头方向取得对应的方向向量；
2. 从箭头前方的下一格开始；
3. 沿该方向逐格移动；
4. 如果途中遇到其他箭头，则返回 blocked=True；
5. 如果一直扫描到棋盘边界仍未发现箭头，则返回 blocked=False。

扫描过程中始终进行边界判断：

0 <= row < rows
0 <= col < cols

从而避免访问棋盘范围之外的位置。

单次判断最多只需要扫描一行或一列，因此对于 R × C 的棋盘，时间复杂度为：

O(max(R, C))

在后续测试阶段还发现了一个边界问题：早期实现会直接访问 board[0]，如果传入空棋盘，就可能触发 IndexError。最终增加了空棋盘判断，并添加回归测试验证这一情况。

---

五、开发过程

我没有让 AIGC 一次生成整个游戏，而是将项目划分成多个较小阶段，每完成一个阶段就进行运行、测试和 Git 提交。

项目最终形成了 10 个主要 Commit：

Commit	主要内容
06558a4	创建基础 Pygame 窗口和游戏主循环
5def17a	完成棋盘网格和四方向箭头显示
a84a8d9	实现四方向箭头路径检测和单元测试
c2d5c66	实现箭头点击交互和错误次数机制
8c8bebf	实现游戏通关、失败状态和重新开始
f6a1a54	实现三个可通关关卡和关卡切换
6455740	添加开始界面和箭头飞出动画
d6996d7	完成 T01-T06 验收测试并修复空棋盘边界问题
86e0b43	添加中文多巴胺界面和关卡导航
6803dbd	完善 README 并添加游戏截图

这种方式的一个好处是，当某一阶段出现问题时，可以比较清楚地定位问题来源，而不是在一个一次性生成的大项目中寻找错误。

---

六、AIGC 使用过程

本次开发主要使用 ChatGPT / Codex 辅助完成需求分析、代码实现、测试设计、Bug 检查和界面优化。我没有直接要求 AIGC 一次生成完整项目，而是将任务拆分为多个阶段，每完成一个阶段后进行人工运行、测试和 Git 提交，再继续下一阶段。

子任务	AIGC 工具	提出的要求	AI 实现或提供了什么	实际效果	审核与修改
需求分析与项目设计	ChatGPT / Codex	分析作业要求，设计 Arrow、Direction、棋盘结构、路径算法，并给出分阶段开发方案	提出了 Direction 枚举、Arrow(row, col, direction) 数据结构、二维列表棋盘和方向向量扫描方案，同时将开发任务拆分为多个阶段	明确了项目整体结构和实现顺序，为后续编码提供基础	没有让 AI 一次生成完整项目，而是进一步缩小每个阶段的任务范围；将路径检测单独拆分，并优先保证 T01-T06
核心路径检测与单元测试	ChatGPT / Codex	实现上、下、左、右四方向的阻挡判断，并为核心算法编写单元测试	创建 path_detection.py，使用方向向量从箭头下一格开始逐格扫描；同时生成四方向、边缘等测试	成功实现 is_blocked()，路径检测可以独立测试，并被后续点击逻辑复用	人工检查为什么从下一格扫描、如何避免数组越界以及时间复杂度；运行 unittest 确认测试通过后才继续开发
点击交互与错误次数机制	ChatGPT / Codex	实现鼠标点击箭头、无遮挡时移除、被阻挡时保留，并加入错误次数和碰撞反馈	创建点击处理逻辑；无遮挡箭头从棋盘删除，被阻挡箭头保留并减少一次机会，同时增加碰撞反馈	游戏从静态棋盘变为可以实际操作的基本玩法	人工运行游戏测试空白位置、无遮挡箭头和被阻挡箭头，确认错误次数不会因为无效点击被错误扣除
游戏状态与三个关卡	ChatGPT / Codex	增加通关、失败、Restart，并实现至少三个可正常通关的关卡	增加 PLAYING、PASSED、FAILED 等状态；实现 Restart、三个固定关卡、关卡切换和可解性测试	形成完整的多关卡游戏流程，三个关卡均能按照合法顺序清空	人工实际完成关卡，检查 Level 1 → Level 2 → Level 3、失败重试以及当前关卡 Restart；使用测试验证原始关卡数据不会被修改
开始界面与箭头飞出动画	ChatGPT / Codex	增加开始页面，并让成功点击的箭头产生飞出棋盘的视觉效果，同时避免动画阻塞游戏循环	增加 Start Screen 和 FlyingArrow，使用非阻塞方式更新动画，并在飞行期间限制重复点击	游戏拥有完整的开始流程，成功点击箭头后能够看到飞出动画	人工运行检查动画和连续点击情况；核心删除逻辑继续由自动测试验证，动画视觉效果由人工验收
T01-T06 验收与 Bug 修复	ChatGPT / Codex	按照老师要求集中检查 T01-T06，寻找遗漏的边界情况，并补充回归测试	对现有测试进行梳理，发现空棋盘情况下直接访问 board[0] 可能产生 IndexError；增加空棋盘保护及相关测试	修复空棋盘边界问题，并补充边缘箭头、失败状态等回归测试；最终共有 34 个单元测试通过	重新运行完整 unittest，并人工检查通关、失败、Restart 等实际游戏流程，确认修复没有破坏已有功能
中文界面与关卡导航	ChatGPT / Codex	将界面修改为中文糖果色风格，并增加“上一关 / 下一关”导航功能	修改界面配色和中文文本，增加字体 fallback 和关卡导航逻辑，并补充导航相关测试	中文界面和关卡导航功能能够运行，自动测试保持通过	第一次实际运行后发现顶部信息和按钮发生布局重叠；根据人工截图反馈，再要求 Codex 只调整窗口高度、棋盘位置和顶部布局，修复后重新人工验收
README 与项目材料整理	ChatGPT / Codex	根据最终项目整理 README，包括项目介绍、运行方法、操作说明、核心算法、测试情况和游戏截图	完善中文版 README，并整理 docs/images/ 中的开始、游戏、通关、失败和全部通关截图	GitHub 仓库具备较完整的项目说明和运行展示材料	人工检查 README 内容、图片路径和实际运行环境；确认程序可以运行后再进行最终 docs Commit 和 Push

AIGC 使用总结

本次开发中，我主要将 AIGC 作为辅助开发和检查工具，而不是直接一次性生成完整项目。整个项目按照“提出一个子任务 → Codex 实现或分析 → 人工阅读和运行 → 自动测试 → 发现问题后继续修改 → Git 提交”的方式逐步完成。

其中比较明显的一次人工修正发生在 UI 开发阶段。中文界面和关卡导航完成后，虽然自动测试全部通过，但实际运行时仍然发现顶部文字和按钮发生重叠。这个问题无法通过核心逻辑的 unittest 发现，因此我根据实际运行结果再次要求 Codex 调整布局，并在修改后重新进行人工验收。

另外，在 T01-T06 集中验收过程中，通过 AIGC 辅助检查发现了空棋盘可能访问 board[0] 导致 IndexError 的边界问题。修复后增加了相应的回归测试，最终项目共有 34 个单元测试全部通过。

通过这些过程，我认为 AIGC 可以明显提高需求拆解、代码实现和测试设计的效率，但生成结果仍然需要开发者理解关键代码，并通过自动测试和人工运行共同验收。

---

七、测试与验收

本项目使用 Python unittest 对核心游戏逻辑进行自动测试，最终共有 34 个测试全部通过。

针对作业要求，我重点验证了 T01-T06：

七、测试与验收

本项目使用 Python unittest 对核心游戏逻辑进行自动测试，并结合人工运行对界面、动画和交互效果进行验收。最终共有 34 个单元测试全部通过。

7.1 T01-T06 测试结果

编号	测试内容	预期结果	实际结果	是否通过
T01	点击前方无遮挡的箭头	箭头成功飞出并从棋盘中消失	路径检测返回无遮挡，箭头对应位置被设置为 None；人工运行时可以正常播放飞出动画	通过
T02	点击前方有其他箭头阻挡的箭头	箭头不消失，并消耗 1 次机会	路径检测判定为 blocked，箭头保留在原位置，剩余机会减少 1，并显示碰撞反馈	通过
T03	点击位于棋盘边缘且方向朝外的箭头	箭头正常移除，不发生数组越界	四个方向的边缘情况均可正确判断，朝外箭头能够正常移除，没有发生 IndexError	通过
T04	清除当前关卡全部箭头	当前关卡通关，并能够进入下一关	最后一个箭头被清除后状态进入 PASSED；Level 1 → Level 2、Level 2 → Level 3 均可正常切换，Level 3 完成后显示全部通关	通过
T05	连续点击被阻挡箭头直到机会耗尽	剩余机会降至 0，游戏进入失败状态，并可以重新开始	最后一次错误点击后状态进入 FAILED；点击重新开始后剩余机会恢复为 3，当前关卡布局恢复	通过
T06	游戏过程中点击“重新开始”	当前关卡恢复初始布局，剩余机会恢复	已经删除的箭头重新出现，剩余机会恢复为 3；如果在 Level 2 Restart，仍保持在 Level 2	通过

7.2 自动测试

自动测试通过以下命令执行：

python -m unittest discover -s tests -v

### 7.1 T01：无遮挡箭头

相关测试包括：

```text
test_unblocked_arrow_is_removed
test_edge_arrow_can_be_removed_without_error
test_all_levels_have_a_valid_solution

自动测试验证箭头能够从二维棋盘中正确移除。箭头实际飞出棋盘的动画则通过人工运行游戏进行验收。

7.2 T02：被阻挡箭头

相关测试包括：

test_blocked_arrow_remains_and_mistake_decreases
test_last_blocked_click_can_become_failed

验证被阻挡箭头不会消失，并且剩余机会减少。

7.3 T03：边缘箭头

相关测试包括：

test_edge_arrow_facing_outward_is_not_blocked
test_edge_arrow_can_be_removed_without_error
test_empty_board_is_not_blocked

主要验证棋盘边缘的箭头不会产生数组越界问题。

7.4 T04：通关与下一关

相关测试包括：

test_clearing_last_arrow_passes_level
test_all_levels_have_a_valid_solution
test_level_one_can_advance_to_level_two
test_level_two_can_advance_to_level_three
test_last_level_is_all_clear

用于验证三个关卡都可以完成，以及关卡之间能够正确切换。

7.5 T05：失败与重新开始

相关测试包括：

test_zero_mistakes_causes_failure
test_last_blocked_click_can_become_failed
test_restart_restores_mistakes_value
test_restart_restores_deleted_arrow

验证错误次数耗尽后进入失败状态，并能够恢复棋盘和错误次数。

7.6 T06：游戏过程中 Restart

相关测试包括：

test_restart_current_level_keeps_level_two
test_restart_restores_deleted_arrow
test_game_board_copy_does_not_modify_initial_layout

验证重新开始当前关卡后仍然处于原来的关卡，同时恢复初始布局。

除此之外，测试还覆盖：

• 空棋盘；
• 空白位置点击；
• 棋盘外点击；
• 三个关卡的合法清除顺序；
• Level 1 / Level 2 / Level 3 导航；
• 第一关不能继续上一关；
• 最后一关不能继续下一关；
• 导航后错误次数恢复；
• 导航后加载完整关卡副本；
• 原始 LEVELS 数据不会被游戏过程修改。

自动测试主要覆盖与 Pygame 无关的核心逻辑。对于箭头飞出动画、碰撞颜色、中文字体、按钮位置和页面布局，我采用人工运行游戏的方式验收。

---

八、PSP

本次开发开始时对各阶段进行了时间估计，完成后记录实际投入时间。

PSP 项目	预计耗时（小时）	实际耗时（小时）	差异（小时）
需求分析与游戏设计	0.75	1	+0.25
Python / Pygame 学习	1	1	0
UI 实现	1.5	2	+0.5
路径与碰撞逻辑	1.5	2	+0.5
关卡设计	0.5	1	+0.5
AIGC 辅助开发	2	1.5	-0.5
测试与 Bug 修复	2	2	0
README / 博客整理	1	1.5	+0.5
总计	10.25	12	+1.75

实际开发耗时约 12 小时，比预计的 10.25 小时多 1.75 小时。

偏差比较明显的部分主要是 UI、路径逻辑和关卡设计。开始时我低估了实际运行后的界面调整、边界情况以及关卡可解性验证所需要的时间。

AIGC 辅助开发的实际时间反而比预计少 0.5 小时。Codex 在需求拆分、基础代码实现和测试设计方面节省了一部分时间，但这些时间并不是完全被“省掉”了——一部分工作转移到了代码阅读、测试和人工验收上。

---

九、总结与反思

通过这次作业，我对一个小游戏从需求分析到最终交付的完整开发过程有了更具体的认识。

首先，游戏表面上的规则并不复杂，但真正实现时仍然涉及数据结构、路径算法、状态管理、输入处理、动画、UI、关卡设计和测试。尤其是路径检测，如果没有先独立设计和测试，后续点击、通关和关卡逻辑都会建立在不稳定的基础上。

其次，这次作业让我更清楚地认识到 AIGC 在软件开发中的作用。Codex 可以快速提供实现方案、生成基础代码和补充测试，但开发者仍然需要知道程序为什么这样写。例如路径检测中的起始位置、数组边界和复杂度，都需要自己理解，而不能只以“程序能运行”作为判断标准。

另外，自动测试也不是全部。34 个测试能够帮助我验证核心游戏逻辑，但 UI 重叠就是一个典型的自动测试没有发现的问题。最终仍然需要结合单元测试和人工运行验收。

最后，Git 的分阶段提交也对整个开发过程有明显帮助。相比最后一次性提交完整项目，每完成一个独立功能就进行测试和 Commit，可以清楚看到项目从基础窗口、路径算法、游戏状态一直发展到最终 UI 和文档的过程，也方便在出现问题时定位修改范围。

如果继续完善这个项目，我会考虑在保持核心规则稳定的前提下增加更丰富的关卡设计、提示机制以及更完整的动画效果。不过对于本次作业，我优先保证了基础要求、三个可通关关卡、T01-T06 测试以及项目文档的完整性。