diff --git a/.agents/rules/engineering-conventions.md b/.agents/rules/engineering-conventions.md
index 48dc4398..bdfa3767 100644
--- a/.agents/rules/engineering-conventions.md
+++ b/.agents/rules/engineering-conventions.md
@@ -64,6 +64,15 @@
 
 > 源档明确给出 system/infra/project/aigc/runtime/feed 六段；其余模块按"每模块一段顺延"规则分配（推断），新增模块时在 `-api` 的错误码常量类登记，避免与既有段重叠。
 
+### 1.4 Spring bean 名消歧（admin/app 双包同名 controller 必显式命名）
+
+`controller/admin/` 与 `controller/app/` 下**同简单类名**的 controller（如两个都叫 `XxxController`）若都用裸 `@RestController`，Spring 组件扫描默认 bean 名都 = 首字母小写类名 → `ConflictingBeanDefinitionException` → **整个 context 启动失败**（路径靠包级 admin-api/app-api 前缀区分、本不冲突，但 bean 名先撞死）。硬要求：
+
+- 双包同名 controller **必须显式 bean 名**：`@RestController("xxxAdminController")` / `@RestController("xxxAppController")`；
+- 其余 admin/app 对靠不同类名（如 app 端 `AppXxxController` vs 后台 `XxxController`）天然规避；
+- 自检（合入前 / CI）：`grep -rlE '^\s*@(RestController|Controller)\s*$' --include='*.java' game-cloud | xargs -n1 basename | sort | uniq -d` 应为空（裸注解重名 = 隐患）；同机理也查 `@Service/@Component`。
+- 血泪：2026-06-19 dev/2.0.0 因 `ComplianceAppeal/PolicyController` 两对双包同名裸 `@RestController` 连崩两次启动（staging 重部署 §3 隔离门逐个逮、live 零破）。
+
 ---
 
 ## 2. 前端（TypeScript / Vue）编码规范
@@ -204,6 +213,7 @@ subject: 动词开头，简明描述（中英文均可）
 | DDL/DML 分开 | 结构变更与数据变更拆成不同迁移文件 |
 | CI 阻断 | CI 阶段执行 `flyway validate`，不通过则阻断合入 |
 | 大表变更 | 用 `gh-ost` / `pt-online-schema-change` **不锁表** |
+| 单一事实源 | 迁移 SQL **只放聚合器 `huijing-server/src/main/resources/db/migration/`（全 V1-Vn）**；**禁**在 `game-module-*-server` 自带重复副本——Flyway 扫全 classpath（含各 module jar），同版本号出现 ≥2 处即 `Found more than one migration with version` **拒启**。自检：`find game-cloud -path '*/db/migration/V*.sql' \| xargs -n1 basename \| grep -oE '^V[0-9.]+' \| sort \| uniq -d` 应空。血泪：2026-06-19 V6/7/8/9/18 各 lane 在 module 自带副本致 5 版本重复、dev/2.0.0 拒启（§3 隔离门第 3 拦） |
 
 ---
 
@@ -214,7 +224,7 @@ subject: 动词开头，简明描述（中英文均可）
 - [ ] 创建 `game-module-{name}-api` + `game-module-{name}-server` 两个 Maven 模块（结构对齐 huijing-cloud fork）
 - [ ] `-api` 中定义 VO / DTO / 枚举 / Feign 接口 / **错误码段**
 - [ ] `-server` 中创建 `controller/admin/` + `controller/app/` + `service/` + `dal/` + `convert/`
-- [ ] 编写 Flyway 迁移脚本 `V{x.y.z}__{desc}.sql`
+- [ ] 编写 Flyway 迁移脚本 `V{x.y.z}__{desc}.sql`——**置于聚合器 `huijing-server/.../db/migration/`,勿在 `module-server` 自带副本**（同版本号重复会拒启,见 §8 单一事实源）
 - [ ] `huijing-server`（聚合器，B 路线保留原名）的 `pom.xml` 引入新模块依赖；并在 `HuijingServerApplication` 扫描 + `application.yaml` 类型别名纳入 `com.wanxiang.huijing.game.module`；Nacos 添加模块配置（如有）
 - [ ] 编写单元测试（Service 层）+ 集成测试（Controller 层含 DB）
 - [ ] Swagger（Knife4j）验证 API 文档自动生成
diff --git a/.agents/skills/ui-walkthrough-cdp.md b/.agents/skills/ui-walkthrough-cdp.md
index e9d972fe..607c59e9 100644
--- a/.agents/skills/ui-walkthrough-cdp.md
+++ b/.agents/skills/ui-walkthrough-cdp.md
@@ -9,6 +9,7 @@
 - 浏览器内访问前端**优先 `http://localhost:4173`**（安全上下文，省心）。**经 Tailscale IP/明文 http 现也可用**：宿主 manifest 校验的 `crypto.subtle` 在非安全上下文缺失，已补纯 JS SHA-256 兜底（2026-06-17 `4e486f60`），不再「走 IP 永远 demo 兜底」。
 - **红线（此坑血泪）**：上条「IP→demo 兜底」曾被当成「走查改用 localhost 规避」记着，却没意识到**创始人/真实用户正是经 IP 访问 → 线上游戏一直「加载失败」**（demo 退化后 W-CLEAN 占位发 game_error）。教训:**走查环境 localhost = 安全上下文，会系统性掩盖「上下文依赖缺陷」（`crypto.subtle`、`isSecureContext` 门控特性等）；用户可见 UI/e2e 走查必须另跑一遍真实访问 origin（IP/明文 http），不能只在 localhost 取证。当走查需要一个 workaround 才能避开某失败时，先问「真实用户会不会也撞上同一失败」。**
 - chrome 起后必先 `curl -s localhost:9222/json/version` 验活再用。
+- **禁从 lili-mac 浏览器 / superpowers-chrome 走查 staging（2026-06-19 实证两次假 502）**：① lili-mac 有系统代理（`HTTPProxy 127.0.0.1` + WPAD `wpad.dat`），Chrome 走代理够不到 Tailscale `100.64.0.7` → 全端 **502 假象**；而 curl 直连绕过代理 → 200，故出现「curl/ssh 显 UP 但 Chrome 见 502」的矛盾，**判据=ssh mini-desktop localhost 200 + 进程活 即为真态**。② superpowers-chrome 持久实例会复用**陈旧会话**（把重部署前的旧 502 截图当现态报，认 `session-<旧id>` 复用即是）。**正解永远是本配方（mini-desktop localhost chrome，无代理、服务+浏览器同机）**；lili-mac CDP 仅个人快验、绝不作 e2e 证。
 
 ## 2. CDP 七坑（Chrome 146 实证，逐个血泪）