@routerhub/agent-rules 1.5.69 → 1.5.71

package/AGENTS.base.md

@@ -148,6 +148,7 @@ Closes #456
 - 所有新建 HTML 文档的文件名必须使用中文命名（如 `用户登录流程说明.html`），禁止使用英文或拼音文件名，方便团队成员一眼识别文档内容。
 - 所有新建 HTML 文档必须统一存放到项目根目录的 `docs/` 文件夹下，禁止散落在桌面、下载目录、临时目录或其他任意位置。如该文件夹不存在则先创建。
 - ⚠️ **编写 HTML 报告/文档时，每一段说明文字必须与其对应的截图、图片紧挨着放在一起（同一视觉区域内）**，禁止将说明文字集中放在页面顶部、图片全部堆在底部，导致读者需要上下翻页才能对照阅读。正确做法：每写完一段说明文字后，紧接着就放该段说明对应的图片，形成"说明 → 配图"的紧密组合，然后再写下一段说明和下一张图。
+- ⚠️ **HTML 报告必须以截图为主、文字为辅**：报告的核心内容是截图，文字仅作为截图的简要说明和补充。页面布局上截图应占主导地位（占据大部分版面），文字说明应精简扼要，禁止出现大段文字配少量截图的情况。读者应能通过翻阅截图快速了解全貌，无需阅读大量文字。
 
 ## 新需求与回归测试准入
 
@@ -254,6 +255,15 @@ Closes #456
 - 写完业务后执行 `pnpm run test:e2e:ui`，告知开发者对应测试用例名称；通过后打开 UI 供手动验证。
 - 端口被占用时自动切换新端口。
 - 自动化测试中，若 Mock 数据不影响业务逻辑验证，优先使用 Mock 数据代替真实接口调用，减少外部依赖和测试不稳定性。
+- ⚠️ **测试用例编写顺序：必须先写主流程，再写边界情况**。主流程（happy path）是最重要的，必须优先覆盖并确保通过；边界情况（异常输入、空值、超时、并发竞态等）重要性相对较低，在主流程全部覆盖完毕后再补充。禁止主流程还没写完就去写边界情况测试，也禁止因为花太多时间在边界情况上而遗漏主流程覆盖。
+- ⚠️ **测试用例必须模拟真实用户的操作流程，禁止只写「XX 可见」类表面检查**。测试用例清单中的每一条主流程用例，必须以真实用户的操作路径来编写：打开页面 → 查看初始状态 → 点击按钮/填写表单 → 提交/保存 → 验证结果页面是否正确展示。核心覆盖场景必须包括：
+  - **新建**：从入口进入 → 填写表单 → 提交 → 在列表/详情页验证新建数据是否正确显示，截图每步关键状态。
+  - **编辑**：从列表/详情进入编辑 → 修改字段 → 保存 → 验证修改后的数据在页面上是否正确回显，截图前后对比。
+  - **删除**：触发删除 → 确认弹窗 → 确认后验证列表/页面中该数据已消失，截图删除前列表和删除后列表对比。
+  - **查看/搜索**：进入列表页 → 使用搜索/筛选 → 验证搜索结果是否符合筛选条件，截图搜索结果。
+  - **状态流转**：如果业务有状态变更（如审核、启用/禁用、支付等），必须覆盖每个状态流转的操作和页面反馈，截图每个状态下的页面展示。
+  - **异常操作**：空表单提交、超长文本输入、非法字符、重复提交等用户可能触发的异常场景，截图错误提示和页面状态。
+- ⚠️ **每一条测试用例必须附带对应步骤的截图，缺一不可**。测试用例清单中每条用例必须写出预期要截哪些图（如「截图1：新建表单填写完成」「截图2：提交成功后列表页新数据出现」），实际执行时每张截图都必须产出并嵌入 HTML 报告。禁止只写操作步骤而不产出对应截图，禁止用「已验证通过」等文字描述代替截图。
 
 ## 错误日志
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routerhub/agent-rules",
-  "version": "1.5.69",
+  "version": "1.5.71",
   "description": "Shared Copilot agent rules and guidelines for RouterHub projects",
   "main": "AGENTS.base.md",
   "bin": {

package/rules/frontend.md

@@ -60,6 +60,15 @@ outputName: "frontend"
 - 写完业务后执行 `pnpm run test:e2e:ui`，告知开发者对应测试用例名称；通过后打开 UI 供手动验证。
 - 端口被占用时自动切换新端口。
 - 自动化测试中，若 Mock 数据不影响业务逻辑验证，优先使用 Mock 数据代替真实接口调用，减少外部依赖和测试不稳定性。
+- ⚠️ **测试用例编写顺序：必须先写主流程，再写边界情况**。主流程（happy path）是最重要的，必须优先覆盖并确保通过；边界情况（异常输入、空值、超时、并发竞态等）重要性相对较低，在主流程全部覆盖完毕后再补充。禁止主流程还没写完就去写边界情况测试，也禁止因为花太多时间在边界情况上而遗漏主流程覆盖。
+- ⚠️ **测试用例必须模拟真实用户的操作流程，禁止只写「XX 可见」类表面检查**。测试用例清单中的每一条主流程用例，必须以真实用户的操作路径来编写：打开页面 → 查看初始状态 → 点击按钮/填写表单 → 提交/保存 → 验证结果页面是否正确展示。核心覆盖场景必须包括：
+  - **新建**：从入口进入 → 填写表单 → 提交 → 在列表/详情页验证新建数据是否正确显示，截图每步关键状态。
+  - **编辑**：从列表/详情进入编辑 → 修改字段 → 保存 → 验证修改后的数据在页面上是否正确回显，截图前后对比。
+  - **删除**：触发删除 → 确认弹窗 → 确认后验证列表/页面中该数据已消失，截图删除前列表和删除后列表对比。
+  - **查看/搜索**：进入列表页 → 使用搜索/筛选 → 验证搜索结果是否符合筛选条件，截图搜索结果。
+  - **状态流转**：如果业务有状态变更（如审核、启用/禁用、支付等），必须覆盖每个状态流转的操作和页面反馈，截图每个状态下的页面展示。
+  - **异常操作**：空表单提交、超长文本输入、非法字符、重复提交等用户可能触发的异常场景，截图错误提示和页面状态。
+- ⚠️ **每一条测试用例必须附带对应步骤的截图，缺一不可**。测试用例清单中每条用例必须写出预期要截哪些图（如「截图1：新建表单填写完成」「截图2：提交成功后列表页新数据出现」），实际执行时每张截图都必须产出并嵌入 HTML 报告。禁止只写操作步骤而不产出对应截图，禁止用「已验证通过」等文字描述代替截图。
 
 ## 错误日志
 

package/rules/global.md

@@ -150,6 +150,7 @@ Closes #456
 - 所有新建 HTML 文档的文件名必须使用中文命名（如 `用户登录流程说明.html`），禁止使用英文或拼音文件名，方便团队成员一眼识别文档内容。
 - 所有新建 HTML 文档必须统一存放到项目根目录的 `docs/` 文件夹下，禁止散落在桌面、下载目录、临时目录或其他任意位置。如该文件夹不存在则先创建。
 - ⚠️ **编写 HTML 报告/文档时，每一段说明文字必须与其对应的截图、图片紧挨着放在一起（同一视觉区域内）**，禁止将说明文字集中放在页面顶部、图片全部堆在底部，导致读者需要上下翻页才能对照阅读。正确做法：每写完一段说明文字后，紧接着就放该段说明对应的图片，形成"说明 → 配图"的紧密组合，然后再写下一段说明和下一张图。
+- ⚠️ **HTML 报告必须以截图为主、文字为辅**：报告的核心内容是截图，文字仅作为截图的简要说明和补充。页面布局上截图应占主导地位（占据大部分版面），文字说明应精简扼要，禁止出现大段文字配少量截图的情况。读者应能通过翻阅截图快速了解全貌，无需阅读大量文字。
 
 ## 新需求与回归测试准入