@routerhub/agent-rules 1.5.159 → 1.5.160

package/AGENTS.base.md

@@ -235,6 +235,14 @@
 - 典型反例：`.filter(v => v.status !== 'disabled')` 在将来新增第三种状态（如 `suspended`）时会被误放行，保存必被后端拒绝。
 - 自查：凡「可选/可用/合法」判定，写成「只保留允许的那些」而不是「排除不允许的那些」。
 
+### ⑦ 白名单查询的每个 OR 分支都要过同一套守卫：新增「允许展示」条件等于新开一个门
+
+- ⚠️ 「公开展示/放行」类查询用 OR 新增「允许显示」条件时，新分支必须与原有分支共享同一套守卫（如 `status`、`is_active`、`deleted_at` 等），禁止只写 `OR new_flag = true` 就放行——否则任何一行只要新标记为 true，无论状态/启停如何都会被漏出。
+- **类比：小区正门有保安，后来在旁边加了个侧门，侧门必须也配保安——不能因为「是新加的」就不设岗。**
+- 典型反例：官网模型列表原查询 `status='published' AND is_active=true`（白名单守卫正确），新增 coming_soon 预告字段时改成 `(status='published' AND is_active=true) OR coming_soon=true`，coming_soon 分支完全绕过 status/is_active 检查——已下架（archived）/已禁用（is_active=false）的模型仅靠预告标记仍被官网返回。修复要双层堵漏：查询分支补守卫 + 状态变更（发布/下架/启停）联动清预告标记。
+- 自查（改旧代码与写新代码同样适用）：凡是「白名单 + OR」查询，把每个 OR 分支单独拿出来逐个核对——它是否覆盖了原白名单的全部守卫字段？不满足新分支条件的行最终落在哪个分支、会不会从守卫上漏过去？动到展示查询的 OR 分支时，先确认旧分支的守卫没被新分支绕过。
+- 变体：新增布尔标记字段参与「是否展示/放行」判定时，必须在引入时同时处理与既有状态字段的交叉——要么查询分支补守卫，要么状态变更时联动清理该标记，两者至少做一个、最好都做。
+
 ## ⚠️ 网关后端编码铁律（来自 PR 评审沉淀）
 
 ⚠️ 本章来自 routerhub-gateway 92 个已合入 PR 中多位评审者（hankWaling / baikaifa / sam-pomex / rachelPomex / eason-qing / enzo0824）的 review 评论沉淀，每条都有真实 PR 出处。写 Go 后端（网关/代理/计费/路由类）代码时对照本节自查。本节所有条目均为强制规则，命中即自检。

package/package.json

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

package/rules/global.md

@@ -235,6 +235,14 @@ name: "通用规则"
 - 典型反例：`.filter(v => v.status !== 'disabled')` 在将来新增第三种状态（如 `suspended`）时会被误放行，保存必被后端拒绝。
 - 自查：凡「可选/可用/合法」判定，写成「只保留允许的那些」而不是「排除不允许的那些」。
 
+### ⑦ 白名单查询的每个 OR 分支都要过同一套守卫：新增「允许展示」条件等于新开一个门
+
+- ⚠️ 「公开展示/放行」类查询用 OR 新增「允许显示」条件时，新分支必须与原有分支共享同一套守卫（如 `status`、`is_active`、`deleted_at` 等），禁止只写 `OR new_flag = true` 就放行——否则任何一行只要新标记为 true，无论状态/启停如何都会被漏出。
+- **类比：小区正门有保安，后来在旁边加了个侧门，侧门必须也配保安——不能因为「是新加的」就不设岗。**
+- 典型反例：官网模型列表原查询 `status='published' AND is_active=true`（白名单守卫正确），新增 coming_soon 预告字段时改成 `(status='published' AND is_active=true) OR coming_soon=true`，coming_soon 分支完全绕过 status/is_active 检查——已下架（archived）/已禁用（is_active=false）的模型仅靠预告标记仍被官网返回。修复要双层堵漏：查询分支补守卫 + 状态变更（发布/下架/启停）联动清预告标记。
+- 自查（改旧代码与写新代码同样适用）：凡是「白名单 + OR」查询，把每个 OR 分支单独拿出来逐个核对——它是否覆盖了原白名单的全部守卫字段？不满足新分支条件的行最终落在哪个分支、会不会从守卫上漏过去？动到展示查询的 OR 分支时，先确认旧分支的守卫没被新分支绕过。
+- 变体：新增布尔标记字段参与「是否展示/放行」判定时，必须在引入时同时处理与既有状态字段的交叉——要么查询分支补守卫，要么状态变更时联动清理该标记，两者至少做一个、最好都做。
+
 ## ⚠️ 网关后端编码铁律（来自 PR 评审沉淀）
 
 ⚠️ 本章来自 routerhub-gateway 92 个已合入 PR 中多位评审者（hankWaling / baikaifa / sam-pomex / rachelPomex / eason-qing / enzo0824）的 review 评论沉淀，每条都有真实 PR 出处。写 Go 后端（网关/代理/计费/路由类）代码时对照本节自查。本节所有条目均为强制规则，命中即自检。