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

# 后端模块并行建设 — 执行版（Wave1 脊柱）

> 编号：HJ-BUILD-001-EXEC ｜ 生成 2026-06-08 ｜ 配套 review 版 `2026-06-08-后端模块并行建设-review.md`
> 决策（创始人定）：**Workflow 编排 ｜ 先 Wave1 脊柱 4 模块 ｜ 外部依赖模块仅骨架+契约点**。
> 不变量：照抄已验证样板 `game-module-project`；契约先行；每模块验证门=编译+Service 单测；运行时/真实联调未验证须显式标注。

---

## 一、Wave1 范围（闭环脊柱 4 模块）

| 模块 | 错误码段 | Flyway 版本 | 闭环职责 | 对外接口（示例，待契约细化） | 关键依赖/对接点 |
|---|---|---|---|---|---|
| **aigc** | 1-101 | V2.0.0 | 生成（"做得出"入口） | `POST /app-api/aigc/generate` 异步提交、`GET /app-api/aigc/task/{id}` 轮询 | **Dify**（契约#6 dify-workflow-io）=人工闸门；产物=GamePackage（契约#4）→ 写 game_version；**仅骨架+对接点** |
| **runtime** | 1-102 | V3.0.0 | 预览/试玩/包服务 | `GET /app-api/runtime/package/{versionId}`、`POST /app-api/runtime/session` | GamePackage（契约#4）、SDK（契约#3）；试玩会话表 |
| **feed** | 1-103 | V4.0.0 | 游戏流/双轨专区浏览 | `GET /app-api/feed/list` 分页流、`GET /app-api/feed/zone/{zoneId}` | 消费 project 已发布 + zone（已建）；按 quality_score 排序（来自 telemetry） |
| **telemetry** | 1-104 | V5.0.0 | 遥测/事件入库 | `POST /app-api/telemetry/events/batch` 批量上报→MQ 异步 | 契约#5 events.schema；原始事件表 + 聚合；MQ 消费幂等 |

> 脊柱串起：创作（project✅）→生成（aigc 壳）→预览/试玩（runtime）→流（feed）→遥测（telemetry）→ 回灌 feed 排序。
> Flyway 版本方案：**每模块独占主版本号** `V{模块序}.x.y`（project=1、aigc=2、runtime=3、feed=4、telemetry=5），全局有序不撞车；baseline-version=0 保证均执行。

---

## 二、三相编排（Workflow）

```mermaid
flowchart TD
  subgraph PhaseA[Phase A 契约扩展（并行起草 + 评审门）]
    A1[子:aigc 契约] & A2[子:runtime 契约] & A3[子:feed 契约] & A4[子:telemetry 契约]
    --> RV[子:一致性评审：脊柱接口对齐<br/>aigc 产物→runtime 入参→feed 展示→telemetry 事件]
  end
  RV --> GATE{主 agent 审 + 锁定契约}
  GATE --> PhaseB
  subgraph PhaseB[Phase B 模块并行建设（平铺并行，写各自 game-module-名 目录）]
    B1[子:建 aigc 骨架] & B2[子:建 runtime] & B3[子:建 feed] & B4[子:建 telemetry]
    -->|各自 mvn 编译+Service 单测自验| VR[回收验证结果]
  end
  VR --> PhaseC[Phase C 主 agent 串行集成]
  PhaseC --> I1[加 4 个 yudao-server pom 依赖]
  PhaseC --> I2[确认 Flyway 版本不撞]
  PhaseC --> I3[mvn install 全量绿]
  I3 --> ACC[验收 + 更新 .agent/契约/记忆]
```

**并行安全**：Phase B 各子 agent 只写**互斥的 `game-module-{name}/` 目录**（无 worktree，无合并回写）；构建用 **`mvn -pl game-module-{name}/game-module-{name}-api,game-module-{name}/game-module-{name}-server test`**（不带 `-am`，依赖从 .m2 解析，避免并发重编 framework 撞 target/）。共享文件（yudao-server/pom.xml、Flyway 版本空间）**只在 Phase C 由主 agent 串行改**。

---

## 三、每模块产出物（DoD）

- `-api`：`enums/ErrorCodeConstants.java`（独占段）+ 状态/类型枚举 +（按需）跨模块 DTO/Feign。
- `-server`：controller(app/admin)+vo、service+impl、dal(DO 继承 `TenantBaseDO`/Mapper)、convert；外部依赖处留**清晰 TODO 对接点**（不 mock）。
- `db/migration/V{seq}.0.0__create_game_{name}.sql`（执行位）+ 同步 `contracts/db-schemas/`（授权源，diff 一致）。
- `contracts/api-schemas/{name}.yaml`（OpenAPI，端前缀 /app-api·/admin-api）。
- `XxxServiceImplTest`（`BaseMockitoUnitTest`，覆盖核心规则）。
- 模块 `.agent`：目标/边界/状态/TODO（含"运行时未验证"标注）。

## 四、验证门（每模块必过）

1. `mvn -pl game-module-{name}/...-api,...-server test` → 编译 + 单测绿。
2. 契约文件入 `contracts/`。
3. 骨架对接点显式标注"待人工闸门/运行时未验证"。

## 五、Phase C 集成 + 验收

- `yudao-server/pom.xml` 增 4 依赖（主 agent 串行）。
- Flyway 版本核对无撞（V2/3/4/5）。
- `mvn -pl yudao-server -am compile` + `mvn install` 全量绿。
- 全局扫描已覆盖 `cn.wanxiang.game.module` → 4 新模块自动接入（无需改 Application/yaml）。
- 更新 `.agent`、playbook 速查、本 spec 状态、记忆。

## 六、风险与边界（承接 review §七）

- aigc 真实生成、telemetry MQ 真实入库、Swagger/Spring 启动 = **运行时未验证**（无基建），仅交付可编译骨架。
- 子 agent 关键任务跑 Opus（记忆 `opus-subagents-critical-tasks`）；主 agent 验证门兜底。
- 契约评审门不可省（决策 5）：Phase A 锁定后才进 Phase B。

---

## 七、执行状态（LIVE · 跨会话/压缩续作锚点，每相更新）

> 用途：主 agent 若被压缩，凭此节即可干净接力，无需依赖会话记忆。

**当前相**：✅ **Wave1 后端脊柱全相完成并验证**（Phase A 契约→修复→锁定→Phase B 建设→Phase C 集成全绿）。

**已定方向（创始人 2026-06-08 选①）：下一主线 = 前端 `game-studio` 脊柱骨架**（非继续铺 Wave2/3 后端广度）。理由：闭环优先的下一环是"可试用"，前端是种子用户能试的必要环，且不卡外部闸门（用已锁契约 mock 建+本地预览）。**先出 review 版计划 → 评审 → 并行 Workflow 执行**（复用 Wave1 三相方法）。
- 前端栈：Vue3 + Vant + 自研 Canvas Runtime(<15KB, Tier1) + WanxiangGameSDK；D4 设计基准 = `ui-ux-pro-max` 技能 + `docs-design/huijing-ai-demo.html`。
- 消费契约（mock 依据）：`contracts/api-schemas/{project,aigc,runtime,feed,telemetry}.yaml` + `sdk-interface.d.ts`(#3) + `game-package.schema.json`(#4)。
- 配套交付（解锁运行时验证，给人执行）：staging 拉起手册（docker-compose 中间件 + `game-cloud/sql/mysql/ruoyi-vue-pro.sql` 初始化 yudao 基础表 + Flyway 自动建 game_ 表 + Swagger/端点冒烟）；本环境无 docker/内存不足无法代跑。
- 并行提醒人侧：长周期日历闸门（经营主体/ICP备案/支付进件/广告审核/LLM实名充值）即刻启动。

- **Phase A Workflow**（完成）：task=`wgi8h9y2a` ｜ runId=`wf_006dd49e-67b`。
- **修复 Workflow**（完成）：task=`wn3q0kegz` ｜ runId=`wf_fa1623d0-129`。
- **Phase B 构建 Workflow**（完成）：task=`wffjrukel` ｜ runId=`wf_dd456459-4a2`。建成 game-module-{aigc,runtime,feed,telemetry}（main 17/30/22/20 文件），主 agent 独立复验 4 模块全 BUILD SUCCESS、**46 单测全绿**（aigc 8/runtime 18/feed 11/telemetry 9）。
- **Phase C 集成**（完成，主 agent 串行）：根 pom 加 4 模块；yudao-server pom 加 4 `-server` 依赖；4 迁移 V2-5 复制到 db/migration（diff 一致）；**`mvn -pl yudao-server -am compile` 全量 BUILD SUCCESS（41 模块 reactor 含 5 game 模块+yudao-server）**。
- **运行时未验证（无基建）**：Spring 启动/扫描生效/Flyway 真实迁移/Swagger/真实 Dify·MQ 联调，须 staging。各模块 integrationTodos 已记录对接点（Dify/MQ/LLM/OSS/quality_score 公式/跨模块 RPC）。
- **契约校验锁定**（主 agent，✅）：5 api-yaml 语法 OK；13 表裸 select*=0；错误码段 100-104 独占；Flyway V1-5 唯一；5 决策落实命中。Wave1 契约**已锁**。
- **Phase B 隔离构建约定**：各 agent 写互斥 `game-cloud/game-module-{name}/` 目录，构建用 **`mvn -f game-cloud/game-module-{name}/pom.xml test`**（父 pom yudao 从 .m2 解析，不带 -am）；**不碰根 pom `<modules>`、不碰 yudao-server、不放迁移到 yudao-server**——这些由 Phase C 主 agent 串行集成。
- **产出落点**：`contracts/api-schemas/{aigc,runtime,feed,telemetry}.yaml` + `contracts/db-schemas/V{2,3,4,5}.0.0__create_game_*.sql`（已锁）；Phase B 产代码于 `game-cloud/game-module-{aigc,runtime,feed,telemetry}/`。

**续作序列（按此推进）**：
1. ⏳ Phase A 完成通知 → **立即把评审 findings 落盘到本节**（blocker 必修后再继续）。
2. 主 agent 审 + 锁契约（必要时改 contracts/ 后再 lock）。
3. **Phase B 构建 Workflow**：4 子 agent 平铺并行，各建 `game-module-{name}/`（克隆 project 范式），构建用 `mvn -pl game-module-{name}/game-module-{name}-api,game-module-{name}/game-module-{name}-server test`（**不带 -am**，避免并发重编 framework）。
4. **Phase C 集成（主 agent 串行）**：加 4 个 `yudao-server/pom.xml` 依赖 → 复制 4 个迁移到 `yudao-server/.../db/migration/`（与 contracts 源 diff 一致）→ `mvn -pl yudao-server -am compile` + `mvn install` 全量绿。
5. 验收 → 更新 `.agent`、本节、记忆 `golden-module-project-verified`/新增 wave1 记忆。

**不变量提醒**：错误码段 aigc=1-101/runtime=1-102/feed=1-103/telemetry=1-104；Flyway 主版本 aigc=V2/runtime=V3/feed=V4/telemetry=V5；端前缀 /app-api·/admin-api；DO 继承 TenantBaseDO；外部依赖只留对接点不 mock；运行时未验证须标注。

**Phase A 结果（已完成 2026-06-08，5 agent/329k token）**：4 契约已写入 `contracts/api-schemas/{aigc,runtime,feed,telemetry}.yaml` + `db-schemas/V{2,3,4,5}.0.0__*.sql`。评审 `spineFlowOk=true`（脊柱端到端贯通无断链）、`coherent=false`（0 blocker/3 major/3 minor，均语义对齐、无需改结构）。

**Phase A→收口决策（HJ-BUILD-FIX，主 agent 拍定，注释层修复，锁前补）**：
1. **[maj] runtime 状态机**：取包门禁判定字段=`game_runtime_package.status`（preview 放行 status∈{0,1}，play 仅 status=1）；runtime 增发布态回写对接点（admin 内部端点 `POST /admin-api/runtime/package/{versionId}/publish` 或 MQ 对接点），project.publish 编排成功后置 `package.status=1` + 回写 `game_version.status=3`。
2. **[maj] qualityScore 量纲**：aigc 侧注释正名「生成质量分(0-1)」、telemetry/feed 侧「运营质量分(0-100)」；README 契约对齐节加「两者不同量纲，不可互相回灌」；**字段名不强改**（不动锁定结构），仅注释澄清。
3. **[maj] play_count 权威源**：权威源=telemetry `game_play_start` 事件聚合；runtime session 仅作时长/质量观测、不计 play_count；runtime `sessionId`(int64) 透传进 telemetry `envelope.session_id`(转 string) 作对账键；两契约注释互指。
4. **[min] ad/income 聚合**：Wave1 脊柱范围=生成→流→试玩→质量分回灌，**不含变现**；ad/income 事件原始入库但聚合表显式标注「Wave2 范围外，later 补列」。
5. **[min] package_url 权威写者**：`game_version.package_url/checksum/bundle_size` 权威写者=runtime 编译成功后回写；aigc 只回填 `version_id` 关联 + 生成元数据（`gen_task_id`），不写 manifest 字段；aigc V2 与 runtime V3 注释互指。

> 收口方式：按**文件分组**并行修复（agent 各改互斥文件 aigc/runtime/telemetry/feed/README，无冲突）→ 主 agent 验证 → 锁契约 → Phase B。各模块 openQuestions（归属/MQ-vs-RPC/CDN 等实现期细节）记录在 Phase A 输出，留实现期与 owner 对齐，不阻断骨架。