zizi-al/games-development-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
games-development-ai/docs/agent-specs/_archive/2026-06-08-admin-wave2并行建设-review.md
zizi 7f24a344d0 docs(agent-specs): B2 归档——64 个闭线工作记录移入 _archive/，热目录顶层 90→26 
承接目录治理：上轮只压缩内容未减文件数，闭线工作记录仍平铺致目录看着仍一堆(创始人指出)。本次执行 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>
2026-06-16 13:26:19 +00:00

8.2 KiB
Raw Blame History

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。