games-development-ai/docs/agent-specs/2026-06-08-后端模块并行建设-review.md

后端 12 模块并行建设 — Review 版 Master Plan

编号：HJ-BUILD-001 ｜ 生成 2026-06-08 ｜ 类型：review 版（结论先行，供决策，不含代码级细节） 配套执行版（待批准后写）：2026-06-08-后端模块并行建设-execution.md 上游依据：黄金模块已验证（memory golden-module-project-verified）、契约 M0 已锁（contracts/）、MVP 执行 spec（HJ-MVP-SPEC-001）、架构三文档套件（Doc A/B/C）、克隆 playbook（.agents/skills/add-business-module.md）。

---

一、结论（先行）

1. 现在可以从串行手写切换到"契约先行 × N 路并行 × 逐模块验证门"：地基（黄金范式 + 8 契约 + 工具链）已验证，剩余 12 模块本质是"克隆范式 + 实现各自已锁契约"，模块间被契约解耦 → 可并行。
2. 并行很干净：全局扫描已覆盖整个 cn.wanxiang.game.module 命名空间，新模块零接线自动生效；唯一共享改动面 = yudao-server/pom.xml 依赖 + Flyway 版本号——由主 agent 串行统一处理，子 agent 只在隔离 worktree 内建+验模块，互不冲突。
3. 按闭环优先分三波，先证 1 条真闭环，再补变现与治理。每模块的验证门 = mvn 编译通过 + Service 单测绿（与 project 同标准）。
4. 需先补 12 模块的契约（API yaml + DB 迁移 + 错误码段），契约是并行的前置与单一事实源，须主 agent 评审锁定后才放并行建设。
5. 本计划本身是抗漂移产物：目标/决策/推理写入本 doc + 执行版 + 各模块 .agent，不依赖会话记忆。

---

二、背景与现状（已验证的地基，勿重复造）

资产	状态
黄金模块 game-module-project（-api/-server）	✅ 编译 + 单测验证（BUILD SUCCESS, 9/9）
8 类契约（M0）	✅ 已锁（project 的 API+DB 已落；其余 12 模块契约待补）
B 路线全局接线（扫描/MapperScan/type-aliases = cn.wanxiang.game.module）	✅ 已生效，新模块自动纳入
工具链 JDK17+Maven、.m2 依赖缓存	✅ 就绪（后续构建快）
克隆 playbook add-business-module.md	⚠ 存在但过时（-biz/game-server//app，未反映全局扫描），须先校正

---

三、目标 / 非目标

目标：把 MVP 后端剩余 12 个 game-module 建成可编译、可单测、接入单体的标准模块，先走通 1 条真实闭环脊柱，再补变现与治理；全过程契约先行、durable 记录、并行加速。

非目标（本阶段不做）：

• 不追求真实外部依赖打通（Dify/LLM/真实支付/广告 SDK = 人工日历闸门，见 memory mvp-binding-constraint-calendar-gates）——这些模块交付"可编译骨架 + 契约对接点"，真实联调待闸门就绪。
• 不做公网正式上线（MVP 验收 = staging 灰度，见绑定约束 memory）。
• 不在本阶段做前端（game-admin/game-studio）。

---

四、推荐方案：契约先行 × N 路并行 × 验证门

三相推进，相内并行、相间设闸：

• Phase 0｜校正 playbook（主 agent，~0.5h）：把 add-business-module.md 与黄金现实对齐（-biz→-server、game-server→yudao-server、/app→/app-api、注明全局扫描免逐模块接线、样板指向 project），作为子 agent 唯一遵循的执行手册。
• Phase A｜契约扩展（并行起草 + 主 agent 评审锁定）：为每模块产出 api-schemas/{name}.yaml + db-schemas/V{x}__{name}.sql + 错误码段，源自 Doc C 需求模块映射。子 agent 各起草一模块，主 agent 审跨模块一致性后锁定（契约是单一事实源，不可并行写完即用）。
• Phase B｜模块并行建设（子 agent，worktree 隔离）：每子 agent 克隆 project 范式实现一模块 → mvn -pl {module} -am compile + test 自验。互不触碰 yudao-server。
• Phase C｜集成（主 agent 串行）：统一加 N 个 yudao-server/pom.xml 依赖、协调 Flyway 版本号、mvn install 全量绿、汇总验收。

闭环优先分波（Phase A/B 按波推进）

flowchart LR
  P[project ✅] --> W1
  subgraph W1[Wave1 闭环脊柱：先证1条真闭环]
    A[aigc 101·壳] --> R[runtime 102] --> F[feed 103] --> T[telemetry 104]
  end
  W1 --> W2
  subgraph W2[Wave2 变现闭环]
    AD[ad 111] --> TR[trade 106] --> PAY[pay 105]
  end
  W2 --> W3
  subgraph W3[Wave3 互动与治理]
    C[community 107] --- CO[compliance 109] --- IP[ip 108] --- B[biz 110]
  end

脊柱走通 = 创作→生成(壳)→预览→流→试玩→遥测 在 staging 可跑 ≥1 条；aigc 真实生成待 Dify/LLM 闸门。

---

五、关键设计决策与取舍

#	决策	理由 / 取舍
1	子 agent 用 worktree 隔离 并行建模块	多 agent 同时写文件不冲突；代价是每 agent ~200-500ms+磁盘，值得（避免串行）。
2	集成（pom/Flyway）只由主 agent 串行做	yudao-server/pom.xml 与 Flyway 版本空间是唯一共享面，串行化消除合并冲突。
3	验证门 = 编译 + Service 单测（非集成测试）	本环境无 Docker/MySQL，集成测试（Testcontainers）跑不了；单测用 Mockito 覆盖业务逻辑，集成测试标注为 staging 阶段。诚实标注运行时未验证。
4	aigc/pay/ad 等先交付骨架	真实联调卡人工日历闸门；骨架先就位让闭环结构成立、契约对接点明确，闸门一到即填。
5	契约先补齐再并行建	契约是解耦前提与单一事实源；若边建边定契约，并行模块会互相打架。
6	跨模块只依赖对方 -api（Feign 同步 / MQ 异步）	playbook 常见坑：-server 互依赖会编译耦合/循环依赖。

---

六、编排架构

flowchart TD
  Main[主 agent：编排 + 评审 + 集成 + 验收] -->|Phase0 校正| PB[playbook 对齐黄金现实]
  Main -->|Phase A 派发| CA1[子:起草 aigc 契约]
  Main -->|Phase A 派发| CA2[子:起草 runtime 契约]
  Main -->|Phase A 派发| CAx[子:起草 ...其余契约]
  CA1 & CA2 & CAx -->|回收| Rev[主 agent 评审跨模块一致性 → 锁定契约]
  Rev -->|Phase B 派发, worktree 隔离| B1[子:建 aigc → mvn 编译+单测自验]
  Rev -->|Phase B 派发| B2[子:建 runtime → 自验]
  Rev -->|Phase B 派发| Bx[子:建 ...]
  B1 & B2 & Bx -->|回收已验证模块| Int[主 agent Phase C 串行集成]
  Int -->|加 pom 依赖 + 协调 Flyway 版本| Full[mvn install 全量验证]
  Full --> Acc[验收 + 更新 .agent/契约/记忆]

---

七、Blast radius / 风险与缓解

风险	影响	缓解
并行 agent 抢改 yudao-server/pom.xml/Flyway	合并冲突、构建坏	集成只由主 agent 串行做（决策 2）
12 模块契约一次性补，质量参差	单一事实源被污染	Phase A 主 agent 评审门 + 复用 project 契约结构
真实外部依赖未通被误判"完成"	验收虚高	骨架模块显式标注"运行时/联调未验证，待闸门"（决策 4）
Flyway 多模块版本号撞车	迁移乱序/校验失败	主 agent 统一版本空间：V{模块序}.{x.y}，集成期分配
playbook 过时致子 agent 漂移	产出不一致	Phase 0 先校正 playbook（决策硬前置）
子 agent 关键任务质量	范式走样	关键任务子 agent 跑 Opus（memory opus-subagents-critical-tasks），主 agent 验证门兜底

---

八、验收标准

• 每模块：mvn -pl {module} -am compile 绿 + Service 单测绿 + 契约文件入 contracts/。
• 整体：mvn install 全量绿；cn.wanxiang.game.module 下 13 模块全部被扫描接入。
• 脊柱（Wave1）：能在 staging（有基建时）走通 ≥1 条闭环（创作→生成壳→预览→流→试玩→遥测）。
• 文档：每模块 .agent + 契约同步 + 本计划/执行版/记忆更新，无信息只活在会话。

---

九、待你确认（决策项）

1. 是否采纳本 review 方案（契约先行 × 三相并行 × 闭环优先分波）？
2. 执行编排载体：用 Workflow 编排（确定性并行/流水线，一次跑多 agent，token 量较大）还是我手动逐波派 Agent（更可控、可中途校准）？
3. 分波范围：先只做 Wave1 脊柱（4 模块）验证编排有效，还是一次规划三波全量？
4. 骨架深度：aigc/pay/ad 等外部依赖模块，只搭骨架+契约对接点（推荐）还是连 mock 实现一并做？

批准后我：①写执行版 spec ②校正 playbook ③按选定载体派并行子 agent，主 agent 设验证门 + 串行集成。