@routerhub/agent-rules 1.5.158 → 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 后端（网关/代理/计费/路由类）代码时对照本节自查。本节所有条目均为强制规则，命中即自检。
@@ -460,6 +468,23 @@
 - ⚠️ **部署生产前必须通读一遍部署脚本再执行，禁止盲跑。** 部署脚本是多人接力的产物，其中任何一行环境值（PROJECT / 服务名 / Nacos namespace / 数据库 / 域名 / 后端 Host / VPC / 密钥名）都可能被中途改错、与线上真实环境脱节——脚本能跑、能编译、甚至能部署成功，但连的是错环境。执行前逐行核对脚本配置与线上实际（`gcloud config get-value project`、`gcloud run services list`、Nacos 配置），对不上 → 先改脚本或停下来问，禁止带着疑似错误的配置直接部署（呼应「环境配置禁止推断」）。
 - ⚠️ **部署脚本必须内置「环境自检」：在真正执行部署动作之前，先自动校验脚本配置与线上环境一致，不一致即中止（abort），禁止在环境未验证的情况下执行 deploy。** 校验项至少包括：① PROJECT 与 `gcloud config get-value project` 一致；② 目标 Cloud Run 服务真实存在；③ Nacos namespace / 库名与线上一致；④ 前端代理的后端 Host（BACKEND_RUN_HOST）指向本环境后端，而非 Dockerfile 默认值或他环境。**目标脚本若没有自检逻辑，执行者必须先补上再跑——禁止「无自检的脚本直接部署」。** 参照 agent-rules 自身 `release.sh` 的「规则漂移检查」（发版前强制校验规则已同步、未同步即中止），把「人记得校验」升级为「脚本强制校验」。
 
+### 🚨 上线安全四环铁律（部署生产 / 切流量必守）
+
+上线（部署生产、切流量、更新线上版本）的唯一不可接受后果是：**新版本有问题直接接流量，把原本正常服务顶崩**。上线必须走完以下四环，缺一不可；任何一环未过即中止，禁止带着未验证的环节继续。这里的核心是「你叫我怎样就怎样」行不通——**上线动作必须等校验全部通过才执行**。
+
+**环1 · 部署前环境对账**（详见「⚠️ 环境配置禁止推断」章节）
+- 脚本配置（PROJECT / 服务名 / Nacos namespace / 数据库 / 域名 / 后端 Host）与线上实际逐项对账（`gcloud config get-value project`、`gcloud run services list`、Nacos），对不上 → 先改脚本或停下问，禁止带疑似错误配置部署。
+
+**环2 · 部署前脚本通读 + 脚本自检**（详见上方「部署规则」两条铁律）
+- 通读一遍部署脚本再执行，禁止盲跑；脚本须内置「环境自检」（PROJECT 一致 / 目标服务存在 / Nacos 与库一致 / 后端 Host 非默认值），不一致即 abort；无自检先补上再跑。
+
+**环3 · 部署中先下不发（防「一上去就崩」的关键）**
+- 部署必须 `--no-traffic`（新 revision 保持 0% 流量），用 revision 临时 URL 验证新版本：日志无 ERROR、连对本环境库、关键接口 200、核心功能可跑通。**验证通过之前，禁止把流量切到新版本；禁止让 `gcloud run deploy` 默认把 100% 流量切到新 revision。**
+
+**环4 · 切流量渐进 + 全程可回滚**
+- 后端渐进切流量（5% → 观察 → 50% → 100%）；前端静态资源验证后一次性切。
+- 切流量前记录当前线上 revision 号；任何一步验证不过，`update-traffic --to-revision <旧版>` 秒切回，恢复线上原状后再排查。
+
 ## ⚠️ 配置中心变更生效铁律
 
 - ⚠️ **修改外部配置中心（如 Nacos）的配置后，若应用是启动时一次性拉取、没有热更新监听，必须显式重启/重新部署服务才能生效**。发布配置后如果验证发现"没生效"，先确认服务是否已经重启到最新版本，再去怀疑配置内容本身写错了——顺序反了会在"配置到底对不对"上来回排查，白白浪费时间。

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 所有对 @routerhub/agent-rules 的重大更改都会记录在这个文件中。
 
+## [1.5.159] - 2026-08-29
+
+### Added
+
+- **「部署规则」新增「🚨 上线安全四环铁律」（部署生产 / 切流量必守）**：把此前分散的上线相关规则整合为一条完整的上线流程，并补上最关键的**环3「先下不发」**与**环4「渐进切流 + 可回滚」**——
+  1. **环1 部署前环境对账**（整合 v1.5.157）：脚本配置与线上实际逐项对账，对不上停下问。
+  2. **环2 部署前脚本通读 + 自检**（整合 v1.5.158）：禁止盲跑，脚本内置环境自检不一致即 abort。
+  3. **环3 部署中先下不发**（新增，防「一上去就崩」的关键）：部署必须 `--no-traffic`，用 revision 临时 URL 验证新版本健康（日志/连库/接口/核心功能），验证通过前禁止切流量，禁止让 `gcloud run deploy` 默认切 100% 流量。
+  4. **环4 切流量渐进 + 全程可回滚**（新增）：后端 5%→50%→100% 渐进切流，前端验证后一次切；切流前记录旧 revision 号，任何一步不过 `update-traffic --to-revision` 秒切回。原因：之前规则只覆盖「配置错/盲跑」，但「脚本配置全对、新版本本身有 bug 一上去就把原服务顶崩」这一最要命场景，必须靠「不接流量先验证 + 可秒回滚」才能兜住。
+
 ## [1.5.158] - 2026-08-29
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routerhub/agent-rules",
-  "version": "1.5.158",
+  "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 后端（网关/代理/计费/路由类）代码时对照本节自查。本节所有条目均为强制规则，命中即自检。
@@ -460,6 +468,23 @@ name: "通用规则"
 - ⚠️ **部署生产前必须通读一遍部署脚本再执行，禁止盲跑。** 部署脚本是多人接力的产物，其中任何一行环境值（PROJECT / 服务名 / Nacos namespace / 数据库 / 域名 / 后端 Host / VPC / 密钥名）都可能被中途改错、与线上真实环境脱节——脚本能跑、能编译、甚至能部署成功，但连的是错环境。执行前逐行核对脚本配置与线上实际（`gcloud config get-value project`、`gcloud run services list`、Nacos 配置），对不上 → 先改脚本或停下来问，禁止带着疑似错误的配置直接部署（呼应「环境配置禁止推断」）。
 - ⚠️ **部署脚本必须内置「环境自检」：在真正执行部署动作之前，先自动校验脚本配置与线上环境一致，不一致即中止（abort），禁止在环境未验证的情况下执行 deploy。** 校验项至少包括：① PROJECT 与 `gcloud config get-value project` 一致；② 目标 Cloud Run 服务真实存在；③ Nacos namespace / 库名与线上一致；④ 前端代理的后端 Host（BACKEND_RUN_HOST）指向本环境后端，而非 Dockerfile 默认值或他环境。**目标脚本若没有自检逻辑，执行者必须先补上再跑——禁止「无自检的脚本直接部署」。** 参照 agent-rules 自身 `release.sh` 的「规则漂移检查」（发版前强制校验规则已同步、未同步即中止），把「人记得校验」升级为「脚本强制校验」。
 
+### 🚨 上线安全四环铁律（部署生产 / 切流量必守）
+
+上线（部署生产、切流量、更新线上版本）的唯一不可接受后果是：**新版本有问题直接接流量，把原本正常服务顶崩**。上线必须走完以下四环，缺一不可；任何一环未过即中止，禁止带着未验证的环节继续。这里的核心是「你叫我怎样就怎样」行不通——**上线动作必须等校验全部通过才执行**。
+
+**环1 · 部署前环境对账**（详见「⚠️ 环境配置禁止推断」章节）
+- 脚本配置（PROJECT / 服务名 / Nacos namespace / 数据库 / 域名 / 后端 Host）与线上实际逐项对账（`gcloud config get-value project`、`gcloud run services list`、Nacos），对不上 → 先改脚本或停下问，禁止带疑似错误配置部署。
+
+**环2 · 部署前脚本通读 + 脚本自检**（详见上方「部署规则」两条铁律）
+- 通读一遍部署脚本再执行，禁止盲跑；脚本须内置「环境自检」（PROJECT 一致 / 目标服务存在 / Nacos 与库一致 / 后端 Host 非默认值），不一致即 abort；无自检先补上再跑。
+
+**环3 · 部署中先下不发（防「一上去就崩」的关键）**
+- 部署必须 `--no-traffic`（新 revision 保持 0% 流量），用 revision 临时 URL 验证新版本：日志无 ERROR、连对本环境库、关键接口 200、核心功能可跑通。**验证通过之前，禁止把流量切到新版本；禁止让 `gcloud run deploy` 默认把 100% 流量切到新 revision。**
+
+**环4 · 切流量渐进 + 全程可回滚**
+- 后端渐进切流量（5% → 观察 → 50% → 100%）；前端静态资源验证后一次性切。
+- 切流量前记录当前线上 revision 号；任何一步验证不过，`update-traffic --to-revision <旧版>` 秒切回，恢复线上原状后再排查。
+
 ## ⚠️ 配置中心变更生效铁律
 
 - ⚠️ **修改外部配置中心（如 Nacos）的配置后，若应用是启动时一次性拉取、没有热更新监听，必须显式重启/重新部署服务才能生效**。发布配置后如果验证发现"没生效"，先确认服务是否已经重启到最新版本，再去怀疑配置内容本身写错了——顺序反了会在"配置到底对不对"上来回排查，白白浪费时间。