@routerhub/agent-rules 1.5.130 → 1.5.131

package/AGENTS.base.md

@@ -268,6 +268,17 @@
 - ⚠️ **修复共享网关配置时必须只做新增（additive-only），不得动原有 defaultService/pathRules**：新增一个独立的 backend service/NEG，在 url-map 上新增一个只作用于目标 host 的 pathMatcher，并显式将该 pathMatcher 自己的 `defaultService` 设置为原有的 backend service，确保其余所有路径行为不变。
 - 配置变更后如果立刻 curl 仍 404，先怀疑网关配置生效延迟（GCLB 常见有数十秒传播延迟），可用"直连后端验证"+"带 Host header 直连网关 IP 验证"两步排除"配置写错"和"还没生效"两种可能，再决定是否继续修改配置。
 
+## 域名配置前置流程（先 LB 后 DNS）
+
+- ⚠️ **给新域名配置 DNS 解析前，必须先建好负载均衡并拿到静态 IP，再把这个 IP 交给配置 DNS 的人，禁止反过来先让人家配域名、再等 IP。** 顺序错了一次 DNS 就要改两次，而且 Google 托管证书依赖「域名 A 记录已指向 LB IP」才能自动签发——没有 IP 就配 A 记录，证书会一直卡在 FAILED_NOT_VISIBLE。
+- 标准流程：
+  1. 建 GCLB 负载均衡（以 HeliosX 体系为例，Serverless NEG → Cloud Run 后端），7 层链路缺一不可：静态 IP → 转发规则(443) → Target HTTPS Proxy → SSL 证书(Google 托管) → URL Map → Backend Service → Serverless NEG → Cloud Run 服务。
+  2. 从静态 IP 资源取到 IP（例如 8.232.47.30）。
+  3. 把这个 IP 连同「配一条 A 记录」的指令一起交给对方（对方唯一要做的：加一条 A 记录 → 名称 api-test / 值 8.232.47.30）。
+  4. 对方配好 A 记录后，证书会自动签发（FAILED_NOT_VISIBLE → ACTIVE），无需手动验证。
+  5. 证书 ACTIVE 后，才跑端到端验证（HTTPS 访问、留资流程等）。
+- ⚠️ **给对方的信息必须把「负载均衡已建好 + IP」放在最显眼位置，明确告诉他「你只需要配一条 A 记录」**，避免对方误以为要自己去建 LB 或改一堆东西。
+
 ## 基础设施修复后代码 Workaround 清理规范
 
 - ⚠️ **临时绕过基础设施问题写入代码的 workaround（如硬编码直连地址、绕过网关/域名），修复根因基础设施问题后必须回退代码**，禁止让 workaround 永久留在代码里。基础设施修复完成后应主动排查代码里是否存在对应的临时绕过逻辑并清理。

package/package.json

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

package/rules/global.md

@@ -268,6 +268,17 @@ name: "通用规则"
 - ⚠️ **修复共享网关配置时必须只做新增（additive-only），不得动原有 defaultService/pathRules**：新增一个独立的 backend service/NEG，在 url-map 上新增一个只作用于目标 host 的 pathMatcher，并显式将该 pathMatcher 自己的 `defaultService` 设置为原有的 backend service，确保其余所有路径行为不变。
 - 配置变更后如果立刻 curl 仍 404，先怀疑网关配置生效延迟（GCLB 常见有数十秒传播延迟），可用"直连后端验证"+"带 Host header 直连网关 IP 验证"两步排除"配置写错"和"还没生效"两种可能，再决定是否继续修改配置。
 
+## 域名配置前置流程（先 LB 后 DNS）
+
+- ⚠️ **给新域名配置 DNS 解析前，必须先建好负载均衡并拿到静态 IP，再把这个 IP 交给配置 DNS 的人，禁止反过来先让人家配域名、再等 IP。** 顺序错了一次 DNS 就要改两次，而且 Google 托管证书依赖「域名 A 记录已指向 LB IP」才能自动签发——没有 IP 就配 A 记录，证书会一直卡在 FAILED_NOT_VISIBLE。
+- 标准流程：
+  1. 建 GCLB 负载均衡（以 HeliosX 体系为例，Serverless NEG → Cloud Run 后端），7 层链路缺一不可：静态 IP → 转发规则(443) → Target HTTPS Proxy → SSL 证书(Google 托管) → URL Map → Backend Service → Serverless NEG → Cloud Run 服务。
+  2. 从静态 IP 资源取到 IP（例如 8.232.47.30）。
+  3. 把这个 IP 连同「配一条 A 记录」的指令一起交给对方（对方唯一要做的：加一条 A 记录 → 名称 api-test / 值 8.232.47.30）。
+  4. 对方配好 A 记录后，证书会自动签发（FAILED_NOT_VISIBLE → ACTIVE），无需手动验证。
+  5. 证书 ACTIVE 后，才跑端到端验证（HTTPS 访问、留资流程等）。
+- ⚠️ **给对方的信息必须把「负载均衡已建好 + IP」放在最显眼位置，明确告诉他「你只需要配一条 A 记录」**，避免对方误以为要自己去建 LB 或改一堆东西。
+
 ## 基础设施修复后代码 Workaround 清理规范
 
 - ⚠️ **临时绕过基础设施问题写入代码的 workaround（如硬编码直连地址、绕过网关/域名），修复根因基础设施问题后必须回退代码**，禁止让 workaround 永久留在代码里。基础设施修复完成后应主动排查代码里是否存在对应的临时绕过逻辑并清理。