c4e2d73300
- game-cloud：yudao-cloud fork(裁剪至 system/infra)+ 5 业务模块 project/aigc/runtime/feed/telemetry - 黄金模块 game-module-project + 克隆 4 脊柱模块；46 单测绿 + 41 模块集成编译绿 - contracts/：8 类契约锁定(5 API YAML + sdk-interface.d.ts + game-package.schema + events 等) - yudao-server 接线：全局组件扫描 + @MapperScan + Flyway V1-V5(baseline-version=0) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
135 lines
8.6 KiB
Markdown
135 lines
8.6 KiB
Markdown
# 后端 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 按波推进）
|
||
|
||
```mermaid
|
||
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` 互依赖会编译耦合/循环依赖。 |
|
||
|
||
---
|
||
|
||
## 六、编排架构
|
||
|
||
```mermaid
|
||
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 设验证门 + 串行集成。
|