7f24a344d0
承接目录治理：上轮只压缩内容未减文件数，闭线工作记录仍平铺致目录看着仍一堆(创始人指出)。本次执行 B2 归档。 64 个 ≤06-15 闭线档(25 压缩桩 + 闭线 review/report/纪要/edit-plan)git mv 入 docs/agent-specs/_archive/(文件名不变、仍 git 跟踪可查)。热目录 ≤06-15 仅留 13 活档(决策/纲领/SoT/活spike)+13 个 06-16 在飞。 活资产 20 处旧路径引用(.agents/docs/memory/_index)同步改 _archive/，引用断裂复测=0；_index 活地图 + 治理档状态收口。约束：0 个 06-16 被移、orchestrator 等未跟踪在飞档零误纳。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
80 lines
8.2 KiB
Markdown
80 lines
8.2 KiB
Markdown
# 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。
|