docs(agents): distill U2-U6 staging 验证 + dev/2.0.0 boot-repair 三类教训
ce-work U2-U6（staging 真验证）期间 §3 隔离门连拦 3 类 dev/2.0.0 boot P0，distill 防复发： - engineering-conventions §1.4：admin/app 双包同名 controller 必显式 bean 名（裸 @RestController 默认 bean 名相撞=ConflictingBeanDefinition 拒启；含自检 grep） - engineering-conventions §8：Flyway 迁移单一事实源（只放 huijing-server 聚合，禁 module 自带副本=同版本重复拒启；含自检 find）+ §9 Checklist 指向聚合器 - ui-walkthrough-cdp §1：lili-mac 系统代理→Chrome 假 502（curl 直连绕过、判据=ssh localhost）+ superpowers-chrome 陈旧会话坑；正解永远 mini-desktop localhost CDP （actuator/health 假探活已由重部署 agent 入 staging-ops §5。） Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
lili
parent
ff46b90ee7
commit
0a82a49f47
@ -64,6 +64,15 @@
|
|||||||
|
|
||||||
> 源档明确给出 system/infra/project/aigc/runtime/feed 六段；其余模块按"每模块一段顺延"规则分配（推断），新增模块时在 `-api` 的错误码常量类登记，避免与既有段重叠。
|
> 源档明确给出 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）编码规范
|
## 2. 前端（TypeScript / Vue）编码规范
|
||||||
@ -204,6 +213,7 @@ subject: 动词开头，简明描述（中英文均可）
|
|||||||
| DDL/DML 分开 | 结构变更与数据变更拆成不同迁移文件 |
|
| DDL/DML 分开 | 结构变更与数据变更拆成不同迁移文件 |
|
||||||
| CI 阻断 | CI 阶段执行 `flyway validate`，不通过则阻断合入 |
|
| CI 阻断 | CI 阶段执行 `flyway validate`，不通过则阻断合入 |
|
||||||
| 大表变更 | 用 `gh-ost` / `pt-online-schema-change` **不锁表** |
|
| 大表变更 | 用 `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）
|
- [ ] 创建 `game-module-{name}-api` + `game-module-{name}-server` 两个 Maven 模块（结构对齐 huijing-cloud fork）
|
||||||
- [ ] `-api` 中定义 VO / DTO / 枚举 / Feign 接口 / **错误码段**
|
- [ ] `-api` 中定义 VO / DTO / 枚举 / Feign 接口 / **错误码段**
|
||||||
- [ ] `-server` 中创建 `controller/admin/` + `controller/app/` + `service/` + `dal/` + `convert/`
|
- [ ] `-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 添加模块配置（如有）
|
- [ ] `huijing-server`（聚合器，B 路线保留原名）的 `pom.xml` 引入新模块依赖；并在 `HuijingServerApplication` 扫描 + `application.yaml` 类型别名纳入 `com.wanxiang.huijing.game.module`；Nacos 添加模块配置（如有）
|
||||||
- [ ] 编写单元测试（Service 层）+ 集成测试（Controller 层含 DB）
|
- [ ] 编写单元测试（Service 层）+ 集成测试（Controller 层含 DB）
|
||||||
- [ ] Swagger（Knife4j）验证 API 文档自动生成
|
- [ ] Swagger（Knife4j）验证 API 文档自动生成
|
||||||
|
|||||||
@ -9,6 +9,7 @@
|
|||||||
- 浏览器内访问前端**优先 `http://localhost:4173`**（安全上下文，省心）。**经 Tailscale IP/明文 http 现也可用**：宿主 manifest 校验的 `crypto.subtle` 在非安全上下文缺失，已补纯 JS SHA-256 兜底（2026-06-17 `4e486f60`），不再「走 IP 永远 demo 兜底」。
|
- 浏览器内访问前端**优先 `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 才能避开某失败时，先问「真实用户会不会也撞上同一失败」。**
|
- **红线（此坑血泪）**：上条「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` 验活再用。
|
- 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 实证，逐个血泪）
|
## 2. CDP 七坑（Chrome 146 实证，逐个血泪）
|
||||||
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user