@routerhub/agent-rules 1.5.90 → 1.5.92

package/AGENTS.base.md

@@ -47,11 +47,44 @@
 - 测试描述、断言使用中文。测试用例先主流程再边界情况。
 - ⚠️ 代码中出现晦涩难懂的技术名词（如 X-Request-ID、反向代理、CORS、JWT、CSRF、幂等、熔断、降级等）时，必须附加中文注解。注解分两层：（1）先说明该名词是什么功能、解决什么问题；（2）再解释其中特殊因子/字段的具体作用。目的是让不熟悉该领域的人也能看懂代码逻辑，不要求已有背景知识。
 
+## ⚠️ E2E 回归测试铁律
+
+- ⚠️ **新增测试用例必须同步改两个文件**：Runner 脚本（登记用例 + 验收详情）和报告页面（数据 + 下拉选项 + 映射 + ID 常量），缺一不可。只改一处会导致测试中心看不到新用例。
+- ⚠️ **Playwright 截图必须用 `{ mode: 'on', fullPage: true }`**，禁止用默认的 `'only-on-failure'`。后者意味着测试全过时一张图都没有，报告里全是空白的。
+- ⚠️ **必须从正确的子目录执行测试**，禁止从项目根目录直接跑。根目录跑会导致配置文件中的相对路径（如 `.env`）解析错误，拿到错误的端口号。
+- ⚠️ **终端看到「全部通过」≠ 工作完成**。真正的完成标志是三件事：① 确认测试中心在线；② 通过 API 触发可视化验收；③ 确认报告里有截图。禁止看到终端绿色就告诉用户「做完了」——用户要的是能打开看的报告，不是终端日志。
+- ⚠️ **测试突然全部失败时，先检查外部依赖（数据库/SSH 隧道等）是否断开**，再改测试代码。禁止反复改测试代码去「绕过」基础设施问题。
+- ⚠️ **页面 Loading 状态必须用元素可见性等待，禁止硬编码 `waitForTimeout`**。SPA 页面的正确等待顺序：先等关键元素出现（确认框架已挂载）→ 再等 Loading 状态消失（确认数据已返回）→ 最后才操作目标元素。顺序错了会出现「Loading 还没消失就点按钮 → 找不到 → 超时」。
+
 ## Go 规则
 
 - 值传递优先，软删除用 `gorm.DeletedAt`（禁止 `*time.Time`）。
 - 禁止无条件执行 GORM AutoMigrate，必须由开关控制，默认关闭。
 
+## ⚠️ 数据库 DELETE 铁律（最高级别，所有写操作前必检）
+
+- ⚠️ **DELETE 是数据库中唯一不可逆的写操作**（INSERT 可以删、UPDATE 可以回改，DELETE 执行后数据消失，只有备份能救）。因此 DELETE 的每一条都必须经过严格的「副作用范围检查」：
+
+  **副作用范围必须 ≤ 用户显式意图范围。**
+
+  也就是说：如果用户删了 A，代码只能删 A，绝不能顺便把 B、C、D 也删了。
+
+- ⚠️ **每写一条 DELETE 语句，必须能在注释中回答以下三个问题**：
+  1. **删什么？** 精确到表名和筛选条件
+  2. **为什么在这里删？** 业务场景是什么（用户点了哪个按钮/执行了什么操作）
+  3. **最多影响多少行？** 如果用户操作 1 条记录，这条 DELETE 最多删几行？答案 ≠ 1 时，逻辑大概率有缺陷
+
+- ⚠️ **写路径禁止「全量同步」语义**。典型的错误模式：
+  ```sql
+  -- ❌ 危险：用「当前这次操作的数据」作为基准去删掉所有其他数据
+  DELETE FROM t WHERE id NOT IN (本次操作涉及的一条/几条id)
+
+  -- ✅ 安全：删除用户显式标记为「已删除」的记录
+  DELETE FROM t WHERE status = 'deleted' AND deleted_by = 当前用户
+  ```
+
+- ⚠️ **清理过期数据/元数据时，DELETE 条件必须精确到「过期标记」字段**（如 `expired_at < NOW()`），不能依赖「不在某个列表中」这种间接条件。
+
 ## 禁止项
 
 - ⚠️ AI 禁止自动执行格式化命令（`npm run format`、`prettier` 等）。

package/package.json

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

package/rules/global.md

@@ -47,11 +47,44 @@ name: "通用规则"
 - 测试描述、断言使用中文。测试用例先主流程再边界情况。
 - ⚠️ 代码中出现晦涩难懂的技术名词（如 X-Request-ID、反向代理、CORS、JWT、CSRF、幂等、熔断、降级等）时，必须附加中文注解。注解分两层：（1）先说明该名词是什么功能、解决什么问题；（2）再解释其中特殊因子/字段的具体作用。目的是让不熟悉该领域的人也能看懂代码逻辑，不要求已有背景知识。
 
+## ⚠️ E2E 回归测试铁律
+
+- ⚠️ **新增测试用例必须同步改两个文件**：Runner 脚本（登记用例 + 验收详情）和报告页面（数据 + 下拉选项 + 映射 + ID 常量），缺一不可。只改一处会导致测试中心看不到新用例。
+- ⚠️ **Playwright 截图必须用 `{ mode: 'on', fullPage: true }`**，禁止用默认的 `'only-on-failure'`。后者意味着测试全过时一张图都没有，报告里全是空白的。
+- ⚠️ **必须从正确的子目录执行测试**，禁止从项目根目录直接跑。根目录跑会导致配置文件中的相对路径（如 `.env`）解析错误，拿到错误的端口号。
+- ⚠️ **终端看到「全部通过」≠ 工作完成**。真正的完成标志是三件事：① 确认测试中心在线；② 通过 API 触发可视化验收；③ 确认报告里有截图。禁止看到终端绿色就告诉用户「做完了」——用户要的是能打开看的报告，不是终端日志。
+- ⚠️ **测试突然全部失败时，先检查外部依赖（数据库/SSH 隧道等）是否断开**，再改测试代码。禁止反复改测试代码去「绕过」基础设施问题。
+- ⚠️ **页面 Loading 状态必须用元素可见性等待，禁止硬编码 `waitForTimeout`**。SPA 页面的正确等待顺序：先等关键元素出现（确认框架已挂载）→ 再等 Loading 状态消失（确认数据已返回）→ 最后才操作目标元素。顺序错了会出现「Loading 还没消失就点按钮 → 找不到 → 超时」。
+
 ## Go 规则
 
 - 值传递优先，软删除用 `gorm.DeletedAt`（禁止 `*time.Time`）。
 - 禁止无条件执行 GORM AutoMigrate，必须由开关控制，默认关闭。
 
+## ⚠️ 数据库 DELETE 铁律（最高级别，所有写操作前必检）
+
+- ⚠️ **DELETE 是数据库中唯一不可逆的写操作**（INSERT 可以删、UPDATE 可以回改，DELETE 执行后数据消失，只有备份能救）。因此 DELETE 的每一条都必须经过严格的「副作用范围检查」：
+
+  **副作用范围必须 ≤ 用户显式意图范围。**
+
+  也就是说：如果用户删了 A，代码只能删 A，绝不能顺便把 B、C、D 也删了。
+
+- ⚠️ **每写一条 DELETE 语句，必须能在注释中回答以下三个问题**：
+  1. **删什么？** 精确到表名和筛选条件
+  2. **为什么在这里删？** 业务场景是什么（用户点了哪个按钮/执行了什么操作）
+  3. **最多影响多少行？** 如果用户操作 1 条记录，这条 DELETE 最多删几行？答案 ≠ 1 时，逻辑大概率有缺陷
+
+- ⚠️ **写路径禁止「全量同步」语义**。典型的错误模式：
+  ```sql
+  -- ❌ 危险：用「当前这次操作的数据」作为基准去删掉所有其他数据
+  DELETE FROM t WHERE id NOT IN (本次操作涉及的一条/几条id)
+
+  -- ✅ 安全：删除用户显式标记为「已删除」的记录
+  DELETE FROM t WHERE status = 'deleted' AND deleted_by = 当前用户
+  ```
+
+- ⚠️ **清理过期数据/元数据时，DELETE 条件必须精确到「过期标记」字段**（如 `expired_at < NOW()`），不能依赖「不在某个列表中」这种间接条件。
+
 ## 禁止项
 
 - ⚠️ AI 禁止自动执行格式化命令（`npm run format`、`prettier` 等）。