games-development-ai/docs/plans/2026-07-04-配置控制面阶段三-game-admin配置控制台UI-plan.md

date, topic, status, sot-impact, 上级

date	topic	status	sot-impact	上级
2026-07-04	配置控制面-阶段三	已 Opus 对抗评审(REVISE→F1-F7 已修回本档)· F5 创始人 2026-07-04 拍档A(JSON 编辑器基线+schema 表单二期跟进)· Codex 半评审走异步 runtime 不可内联取(protocol	无契约/SoT 变更 —— 消费阶段二已落的 AdminGenConfigController(/admin-api/aigc/config 十四端点),兑现运行时 SoT §5.2「管理面配置管理」早已划界的阶段三 UI;新增件全在 game-admin 前端 + 一份系统菜单/权限种子(RBAC data,非契约)	docs/agent-specs/2026-07-02-配置控制面阶段二-yudao配置中心-设计.md

配置控制面阶段三 · game-admin 配置控制台 UI —— 实施工单

一、目标与背景

阶段二把生成配置升级成「yudao 定版 → 双路激活 → 数秒热生效」的受治理配置中心,后端治理层、版本账本、激活编排、漂移对账、NacosHotConfig 热源全部落地,并已在部署窗口批把 cheap/tier2 两档的生效链路在 mini-desktop 真机跑通。但这一整套能力现在只有 REST 端点和后台服务,运营和创始人要改一条 prompt、调一个预算阈值、把某个版本激活或回滚、看一眼线上生效值有没有漂移,都还得靠 curl 或直接连库——没有人读的界面。

阶段三补的就是这一层:在 game-admin 里落一个配置控制台,把阶段二后端的十四个端点包成运营点得动的界面。它不引入任何新的后端能力,不改一行契约,只把已经存在的治理能力变得可视、可操作、有权限边界。

阶段二设计档(§26 界限、§66、§184/193/238)早已把这块划为「阶段三、后续出 plan」,并给了范围:浏览 / 改草稿 / 定版 / 激活 / 回滚 / 历史 / diff / 漂移对账,落点 game-admin/src/views/wanxiang/config。本工单据 Opus 开工前评审把七处硬伤/欠定修回,落成可执行的六要素。

二、后端已就绪的端点面(消费对象,不改;逐端点列参数位+字段名)

AdminGenConfigController,前缀 /admin-api/aigc/config,RBAC 五权限 aigc:config:{query,save,archive,freeze,activate},VO 已定义。执行前把每个端点的参数位与精确字段名逐字对 controller 签名 + VO 源再核一遍(下表是评审后核过的口径,仍以源码为准):

端点	方法	参数位	参数/字段(逐字)	权限
/page	GET	query	GenConfigSetPageReqVO(tier/status/setKey/pageNo/pageSize)	query
/get	GET	query	id	query
/create	POST	body	{tier, setKey, name?, description?, draftPrompt?}	save
/update-draft	PUT	body	{id, name?, description?, draftPrompt?, draftContentJson?}(可空=不改)	save
/archive	POST	query ⚠	id(@RequestParam,非 body)	archive
/version/list	GET	query	configSetId	query
/version/get	GET	query	configSetId, version	query
/version/diff	GET	query	configSetId + 两版本号(逐字对 controller 签名的 @RequestParam 名)	query
/freeze	POST	body	{id, changeNote?} ⚠ 用 id 非 configSetId	freeze
/activate	POST	body	{configSetId, versionId}	activate
/rollback	POST	body	{configSetId, versionId}	activate
/recover-activating	POST	query ⚠	configSetId(@RequestParam,非 body)	activate
/reconcile	GET	query	configSetId	query
/rebroadcast	POST	query ⚠	configSetId(@RequestParam,非 body)	activate

⚠ 三个 POST(archive/recover-activating/rebroadcast)绑 @RequestParam 而非 @RequestBody:前端必须用 request.post({ url, params })(query 位)而非 { url, data }(JSON body),否则真机 400——这在 mock 下抓不到、只在真后端炸(F2)。freeze 的 body 字段是 id(不是 configSetId),activate/rollback 是 {configSetId, versionId},命名不一致易抄错、逐字核。

三、范围(MECE)

做(本工单)

3.1 api 模块 game-admin/src/api/aigc/config/index.ts

十四端点封装 + 与后端 VO 对齐的 TS 类型(配置集 GenConfigSetRespVO / 版本 GenConfigVersionRespVO / diff GenConfigVersionDiffRespVO / 漂移报告 GenConfigDriftReportRespVO)。

• 范式点名:走标准 @/config/axios(admin-api 的 CommonResult 解包)——参照 game-admin/src/api/infra/config/index.ts 或 src/api/wanxiang/trade.ts。显式排除 src/api/wanxiang/genMonitor.ts 作范式:它用独立 axios 实例、裸 JSON 不带 Token 不走 CommonResult(因 gen-worker 非 CommonResult),config 端点是 admin-api CommonResult,抄 genMonitor 会解包错(F6)。
• 三个 @RequestParam POST 用 params 位(见 §二 ⚠)。
• 枚举常量钉死并逐字对源码核(下值是评审线索,executor 必核 GenConfigSetStatusEnum、GenConfigDriftReportRespVO 的 verdict、GenConfigVersionDiffRespVO 的 changeType 源):配置集状态(草稿/待审/已激活/已归档)、漂移 verdict 五态 IN_SYNC/DRIFT/ACTIVATING_SKIPPED/NO_ACTIVE_VERSION/UNREACHABLE、diff changeType ADDED/REMOVED/CHANGED。

3.2 控制台页面 game-admin/src/views/wanxiang/config/(Vue3 + Element Plus,循 §3.1 点名的 yudao CRUD 范式)

• 配置集列表:分页表格(档位 cheap/tier2、状态、业务键筛选),行内「详情 / 归档」,顶部「新建配置集」(表单 = tier/setKey/name/description/初始 draftPrompt)。
• 配置集详情(核心页):三区——
  • ① 草稿编辑区(F1+F5 定档 A):两个字段——draftPrompt(prompt 正文大文本域,走版本行 MEDIUMTEXT 列、不进 content_json)+ draftContentJson(结构化旋钮的 routeA/routeB 嵌套信封,MVP 用原始 JSON 编辑器,jsoneditor@^10.1.3 已是 game-admin 依赖)。编辑器铁律 = round-trip 保信封:解析既有 draftContentJson → 只改目标叶子 → 原样回序列化,绝不重建成扁平结构(扁平化会丢 routeA 接线字段、激活 sanity 必拒)。保存/定版前端先做 routeA sanity 预校验(有 routeA 则 agentId/sessionId/session.chat_model_config 四字段[type/credential_id/model/parameters]齐全、routeA 存在则 draftPrompt 非空;至少一路 routeA/routeB),不过给红字提示、不提交(把后端 AIGC_CONFIG_ACTIVATE_SANITY_FAILED/_NO_ROUTE 提前到编辑期)。content_json 信封契约钉此(取自 GenConfigContentCodec 头注释 L23-45):

    { "routeA": { "agentId","sessionId",
                  "agent":{context_config,react_config},          // 可选透传 PATCH /agent
                  "session":{ "chat_model_config":{type,credential_id,model,parameters} } },  // 有 routeA 必填、整替
      "routeB": { "budget.cheap_rmb_hard_limit":10.0, "gates.qpass_go_min":0.40 } }  // area.key 扁平
    

  • ② 版本历史区:倒序表(版本号/状态/激活标记/content 字节数),行内「查看全量 / 与上一版 diff」;「定版」把当前草稿冻成版本(body {id, changeNote?})。
  • ③ 激活区:选版本「激活 / 回滚」(body {configSetId, versionId});「恢复卡激活」兜 ACTIVATING(query configSetId)。
• diff 视图:消费 /version/diff 返回——prompt 侧给「是否变更 + 两侧字节数」,结构化旋钮侧按 knobChanges[](changeType + 点路径 + 两侧值)el-table 直渲,前端不重算(F7:该 VO 扁平可直渲)。
• 漂移对账面板:详情页「对账」按钮 → /reconcile 三态报告(verdict 五态;漂移态列 driftItems[] 的 route/key/expected/actual),漂移给「一键重推」(/rebroadcast query configSetId)。

3.3 菜单 + 权限种子(F3:自建父菜单,别假设已有 AIGC 目录)

全仓无既有 aigc:config 或 AIGC 父菜单,种子须自建。循 game-cloud/game-module-{biz,trade}/sql/*_menu.sql 范式,INSERT IGNORE 幂等:

• 1 行 type=2 顶级/子菜单:承载可路由页,component=wanxiang/config/index、path/component_name 按范式接线(挂到合适父目录下,或自建 AIGC 治理目录)。
• 5 行 type=3 按钮权限:aigc:config:{query,save,archive,freeze,activate}。
• id 段避撞:biz 占 7100-7107、trade 占 7110-7112 → aigc 取 7120+,落种子前实查当前 system_menu max(id) 再定段,别硬写撞号。
• 合计 6 行(1 菜单 + 5 按钮)。

不做(划界,各自另处)

• schema 驱动引导表单(消费 AgentScope /agent/schema 自动渲染):§66/§238 交付本体,创始人 2026-07-04 拍定作二期紧随跟进(F5),不在本期 MVP;MVP 用 §3.2① 的原始 JSON 编辑器(保信封 round-trip)覆盖,能力完整、激活可靠。
• BPM 审批流可视:阶段二定「放量后启用、MVP 由创始人直接激活」,本 UI 只做直接激活路径。
• 阶段四观测(trace 回放/成本对账/在跑监控/effective 配置端点):独立阶段。
• 知识件配置面(决策6「进配置集」):范围增量,另出设计,不并入。

四、验收标准(可验证断言)

1. 构建绿:game-admin 构建脚本通过,新增页面无类型/lint 报错。
2. 端点全接:十四端点每个都有 api 封装且被至少一个页面动作调用(无孤儿封装、无写死假数据);三个 @RequestParam POST 确认走 params 位。
3. 权限门真(F4:不能用超管测——超管 *:*:* 全放行、证不出收敛):建一个只勾 aigc:config:query 的非超管运营角色,断言写操作按钮(新建/改草稿/定版/激活/回滚/归档/重推)全隐藏;再建一个含 save/freeze/activate 的角色断言相应按钮可见。种子 SQL 可幂等重跑。
4. 一条走查闭环(mini-desktop 真后端 + 已 seed 的 dataId,排 staging 窗口):新建配置集 → 改草稿(JSON 编辑器改一个 routeB 门阈值叶子、保信封)→ 定版 → 激活 → 详情「对账」显示 IN_SYNC → 篡改 Nacos 单键 → 「对账」显示 DRIFT 逐项 → 「一键重推」→ 复对账回 IN_SYNC → 回滚到上一版。每步 UI 状态与后端返回一致。
5. 诚实口径:走查若受 staging 部署窗口未到而只跑到本地 build 绿,如实标「真后端 e2e 待窗口」,不宣称闭环。

五、依赖与前置

• 阶段二后端(AdminGenConfigController + 治理服务 + 激活编排 + 对账 + GenConfigContentCodec 信封契约)——✅ 已落 dev/2.0.0。
• game-admin 项目可构建(Vue3+Vite+Element Plus yudao fork;jsoneditor 已在依赖)——执行第一步先 pnpm i + 一次基线 build 确认环境,不在坏环境上叠业务代码。
• 真后端走查依赖 game-cloud 部署带本子域(aigc:config 权限种子进库)+ AgentScope Service 在跑——排 staging/部署窗口,可逆动作免逐次请示、live 变更逐次报。

六、风险与回滚

• 风险 1(最高,F1):content_json 信封被前端扁平化——JSON 编辑器若不 round-trip 保 routeA/routeB 信封,序列化出的配置激活 sanity 必拒。缓解:§3.2① 铁律(解析→改叶子→原样回序列化)+ 前端 routeA 预校验 + 走查断言 4 用真后端激活兜真。
• 风险 2(中,F2):三个 @RequestParam POST 用错参数位——mock 抓不到、真机 400。缓解:§二 ⚠ 逐端点标位;api 封装评审时核这三个走 params。
• 风险 3(降级,F7):diff/漂移 VO 前端渲——原担忧其嵌套,实为扁平可直渲,精力压到风险 1,不在此处过度设计。
• 回滚:纯前端新增 + 一份可幂等种子,无存量改动;回滚 = 撤页面 + 撤菜单种子行,零运行时影响(后端端点本就存在、不因 UI 撤而变)。

七、执行方式

fable 列此工单并按 protocol #8 过 Opus 开工前对抗评审(REVISE→本档已修 F1-F7);F5 范围项创始人已拍。执行按现行分工——创始人驱动 opus 会话(plan 模式 + goal/ultracode 自治自审),或经全自主授权由 fable 派 opus 隔离执行、逐波终审(build 亲跑 + 走查证据)。worktree 隔离铁律:本仓 worktree 默认基线是 dev/1.0.0(TS monorepo 老线、无 game-admin),执行前必须先 git reset --hard <dev/2.0.0 tip> 或 git checkout -b work <tip> 再动手(见 tech-decisions §14 坑④),并自查 game-admin/ 存在。