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）

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 对齐，不阻断骨架。