# admin + Wave2 变现 并行建设 · Review/编排锚点

> 文档编号 HJ-PAR-002 · 2026-06-08 · 状态:**Phase 0 进行中(契约起草子 agent 运行)**
> 创始人决策(2026-06-08):下一主线 = **game-admin 运营后台 + Wave2 后端变现 并行建设**(AskUserQuestion 选②"admin + Wave2 并行(推荐)")。
> **v2 纠偏(2026-06-08,主 agent 只读勘察后)**:压缩前本 spec 假设"克隆 ad/trade/pay 三模块"。勘察既有代码/契约/架构文档后发现该假设有实质偏差,据权威文档(Doc B 模块职责 + MVP 决策 D3)收敛为**只新建 ad+trade 两模块,pay 复用 huijing-pay/后置**。详见 §一·纠偏。
> 复用方法:三相并行 + 主 agent 验证门(不采信子 agent 自报,见记忆 `wave-parallel-build-orchestration`、`frontend-spine-built` 假绿教训)。

---

## ⚡ 接力锚点(压缩后从这里续)

- **已完成并 push(origin/dev/2.0.0,HEAD=9e95a66)**:后端 Wave1 脊柱 5 模块(project/aigc/runtime/feed/telemetry)+ 8 类契约 + 前端 game-studio 脊柱 + 全栈命名 huijing→wanxiang。
- **本轮 = admin + Wave2 变现(ad+trade)并行**。**进度(LIVE)**:
  - ✅ **Phase 0 已锁定**:契约 ad.yaml/trade.yaml + V6/V7 起草并经主 agent 独立复核(语法/错误码 111·106/金额用分/资金幂等/状态机/seam 一致);主 agent 收紧 ad 计费 `uk_trace=(trace_id,event_type,tenant_id)` 防丢账;contracts/README 索引已更新;**admin 基线=克隆上游 huijing-ui-admin-vue3 已落 `game-admin/`**(34M/2236文件,去嵌套git)。
  - 🔄 **Phase 1 运行中**:Workflow `w2z92q6jm`(脚本 `docs/agent-specs/wf-admin-wave2-phase1.mjs`)。3 Opus agent:后端链 ad→trade(串行,trade 依赖 ad-api)∥ admin 裁剪接线。
  - ⏳ **Phase 2 待办(主 agent 验证门)**:见 §四。等 Workflow 完成通知 → 独立复跑,不采信自报。
- **本轮新增跨模块决策**:ad 归因需 game→creator → 给 **project-api 加 `getCreatorUserId(gameId)` Feign**(照 huijing DictDataApi 模式;仅 ad 碰 project,不撞车,由 ad agent 顺带建)。pay 仍不建(复用 huijing-pay 后置)。
- **命名铁律**:全栈 `wanxiang`(`com.wanxiang.huijing.game`/`WanxiangGameSDK`/`wanxiang-game-sdk`),勿用 huijing。huijing 框架 `com.wanxiang.huijing` + Maven `com.wanxiang` 不动。
- **后端验证门铁律**:`mvn -pl <模块> -am test`(带 -am 避陈旧 jar);前端 `npm run build`(`vue-tsc --noEmit` 假门禁)。

---

## 一、范围与互斥边界(三仓天然解耦,唯一共享=contracts/)

### 纠偏:为何只建 ad+trade,pay 不克隆(勘察实证)

| 勘察发现 | 结论 |
|---|---|
| **`huijing-module-pay` 已存在**(成熟:PayOrder 收单/PayWallet 钱包/PayTransfer 提现/PayRefund/notify 回调,幂等对账齐全),仅在 huijing-server 中被注释未接线 | 克隆 `game-module-pay` = 重复造轮子。pay(收单)留用 huijing-pay,会员/内购收单=P1 再启用 |
| **Doc B 模块边界**:pay=支付**收单**(微信/支付宝/IAP),**钱包/提现归 trade**;trade=分账/结算/对账/钱包打款/提现 | 钱包+提现是 **trade** 的活,trade 自建收益账户;pay 不在 MVP 钱财闭环 |
| **MVP 决策 D3**:广告分成统一 80% / 满5元提现 / 1元=10积分打赏(走同一分账);**会员订阅=P1** | MVP 钱财闭环 = 广告收入→trade 分账(80%)→收益账户→提现。**不含收单**(广告收入非收单;打赏积分=mock/P1) |
| **契约 #7 ad-slot.schema.json 已锁**、**事件 #5 已含 ad_impression/ad_reward/income_settled** | ad 模块消费既有契约,不重造广告位 schema/事件 |

→ **本轮后端 = 2 个新模块(ad+trade);pay=复用 huijing-pay 后置。**

### 三 Track 互斥边界

| Track | 目录(互斥) | 消费/依赖 | 共享资源争用 |
|---|---|---|---|
| **A. game-admin** | `game-admin/`(全新,**fork 仓内 `game-cloud/huijing-ui/huijing-ui-admin-vue3`**,Vue3+Element Plus) | 只读消费**已锁 admin-api**(project review / feed featured / telemetry game-stat + **本轮新增 ad 广告位/收入 + trade 提现审核/营收**) | 无(独立新仓目录,最干净) |
| **B. game-module-ad** | `game-cloud/game-module-ad/` | 克隆黄金模板 project;AdProvider SPI(mock);消费 #7/#5 | 根 pom / huijing-server pom / Flyway / 契约(Phase 0 锁) |
| **C. game-module-trade** | `game-cloud/game-module-trade/` | 克隆黄金模板;**消费 ad 的 `AdRevenueApi`(Feign seam)**;creator_share/withdraw_min 走 Nacos | 同上 |

> game-admin 与 game-cloud 目录完全互斥 → A 与 B/C 放心并行。B/C 各写互斥模块目录,仅共享后端基建文件(主 agent Phase 2 串行接)。**ad↔trade 有依赖**(ad 收入→trade 分账),其 Feign seam 在 Phase 0 锁死,两侧据此实现。

## 二、Phase 0 · 主 agent 锁共享资源(进行中)

1. **Flyway 版本空间**:Wave1 占 V1-V5 → **ad=V6.0.0 / trade=V7.0.0**。✅ 已定
2. **错误码段**(README §四 已预留):**ad=1-111 / trade=1-106**。✅ 已定(pay=105 留给 huijing-pay/未来)
3. **新契约锁定**(写 `contracts/`):ad.yaml + trade.yaml(API)+ V6/V7(DB)+ **ad↔trade Feign seam**(ad.yaml 内 x-feign-contracts)。⏳ 契约起草子 agent 运行中 → 主 agent 复核(yaml 语法/裸 select* 0/错误码段独占/Flyway 版本唯一/金额用分/幂等键齐/状态机/seam 两侧一致)后锁定。
4. **资金契约红线**(资金域必守):金额用「分」BIGINT、写入幂等键(trace_id/biz_no/source_ref+uk)、状态机 tinyint 非法流转服务端拒、分账幂等 uk(source,source_ref)、全 mock provider/打款但留真实接入位(SPI/回调)。
5. **game-admin 技术基线**:✅ fork 仓内 `huijing-ui/huijing-ui-admin-vue3`(Element Plus),admin-api baseURL + huijing Token 鉴权沿用。
6. **根 pom + huijing-server pom**:Phase 2 串行接(减少并行期 git 冲突面)。

## 三、Phase 1 · 并行建设(Workflow,互斥目录)

- **Track A(game-admin,~2-3 agent)**:地基(fork 裁剪 huijing-ui-admin-vue3 + admin-api 接线/鉴权) ∥ 审核+精选+广告位管理页 ∥ 数据看板+提现审核+营收页。消费已锁 admin-api(直连后端或 mock)。关键 agent 跑 Opus。
- **Track B(game-module-ad,1 Opus)**:克隆黄金模板,实现广告位 CRUD + SDK 拉取 + 曝光/激励计费(mock eCPM)+ 广告收入台账 + **AdRevenueApi(-api Feign,供 trade)**。自验 `mvn -f game-module-ad/... test`。
- **Track C(game-module-trade,1 Opus)**:克隆黄金模板,实现收益账户 + 收益流水 + 分账引擎(读 AdRevenueApi×80%)+ 提现申请/审核(满5元 mock 打款)+ 打赏入账。自验单测。
- 子 agent **只写各自目录**,不碰共享文件(pom/Flyway/契约——Phase 0 已锁)。

## 四、Phase 2 · 主 agent 集成验证门(串行 barrier,不采信自报)

1. 接共享文件:根 pom `<modules>` 加 ad/trade、huijing-server pom 加 2 依赖、Flyway V6/V7 复制到 `huijing-server/.../db/migration/`(与 contracts 源 diff-identical)。
2. 后端权威验证:`mvn -pl huijing-server -am compile`(全量集成编译)+ ad/trade 各 `mvn ... -am test`(单测绿)。
3. game-admin:`npm run build` + `/browse` 冒烟运营闭环(审核队列→决策→精选→看板→提现审核)。
4. 残留检查(huijing=0/裸select*=0)、durable 更新(.agent / 记忆 / 本 spec LIVE)。

## 五、为何 contractGaps 靠后(不进本轮并行)

contractGaps 改的是**已有共享契约**(project.publish / runtime.getPackage / feed.ShareMeta / telemetry 命名)+ 跨前后端实现。与本轮并行会让其他 Track 基于旧契约假设,一改即冲突。正解:本轮(admin+Wave2)跑完后,**单独一轮**做 contractGaps + staging 拉起手册,让现有脊柱进真实联调。

## 六、风险与约束

- 并行越宽,Phase 2 集成期问题越集中 → 主 agent 严格独立复跑,不采信自报。
- **资金域(trade)涉及金额/分账/提现**:契约/实现必须含幂等键、状态机、对账锚点(trace_id/source_ref)、补偿路径(即便 MVP mock 打款)。余额变更必有流水,账户表=流水物化汇总。
- ad↔trade 是本轮唯一跨模块强依赖:seam(AdRevenueApi)Phase 0 锁死后两侧不得各自发挥。
- game-admin fork huijing-ui-admin-vue3,与 game-studio 不同栈(Element Plus vs Vant),不复用 studio 组件。
- pay(huijing-pay)本轮不启用:trade 提现 mock 打款,留 SPI/回调位,会员/内购收单(P1)再启用 huijing-pay。