From 3bfc3f0849af086dc4c9fa14031b399b5d9d0782 Mon Sep 17 00:00:00 2001 From: Suzumiya Date: Fri, 11 Sep 2026 15:42:52 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9E=20AGC=20=E8=B5=84=E6=BA=90?= =?UTF-8?q?=E5=B7=A5=E4=BD=9C=E5=8F=B0=20V3=20=E7=AB=AF=E5=88=B0=E7=AB=AF?= =?UTF-8?q?=E9=AA=8C=E6=94=B6=E7=94=A8=E4=BE=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 docs/technical/【测试用例】AGC资源工作台V3端到端验收-2026-09-11.md - 给出从建项、对话生成素材到运行收尾的一条主线，按 S1–S21 分步列出操作、期望结果、对应 PRD 条款、可观察判据与已知例外 - 落定每步的可观察形态：资源卡 data-preview-kind / data-preview-status / data-preview-error、data-used-by-current-version、data-resource-book-category、data-resource-view-state 与控制台判据脚本 - 记录前置条件与门禁口径：dev 态前端走 Vite HMR、Rust 侧改动需重启客户端、服务端改动需重启 api-server、build-gate 代理假红需清代理变量 - 列出只靠视频或截图表达的 7 处条款清单与补齐方式，并更正 F12 无法观察 Rust 到 api-server 的 HTTP 这一前提 - 列出已知未做与已取消项，以及文档与代码的四处偏差（资源卡打开详情按钮、运行入口提示文案、画布生成入口进度、真机落盘分类分布） - 附验收记录表与逐步骤失败排查索引 --- ...用例】AGC资源工作台V3端到端验收-2026-09-11.md | 257 ++++++++++++++++++ 1 file changed, 257 insertions(+) create mode 100644 docs/technical/【测试用例】AGC资源工作台V3端到端验收-2026-09-11.md diff --git a/docs/technical/【测试用例】AGC资源工作台V3端到端验收-2026-09-11.md b/docs/technical/【测试用例】AGC资源工作台V3端到端验收-2026-09-11.md new file mode 100644 index 000000000..d7c1dbd9c --- /dev/null +++ b/docs/technical/【测试用例】AGC资源工作台V3端到端验收-2026-09-11.md @@ -0,0 +1,257 @@ +# AGC 资源工作台 V3 端到端验收 + +- 适用分支：`feat/agc-canvas-resource-workbench-v3` +- 需求来源：飞书《GameAgent客户端画布与资源工作台 V3.0》 +- 权威文档：[`【AI游戏创作】项目开发工作台PRD-2026-07-20.md`](../prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md)、Tracking Issue #309、PR #316 +- 目的：给出一条**连贯的产品使用主线**，让验收人从零到跑通走一遍，就能把当前 PRD 要做的需求全部验收完；每一步都给出**可观察判据**，而不是"看起来对"。 + +## 1. 验收基线的先决条件 + +| 事实 | 依据 | 对验收的影响 | +| --- | --- | --- | +| 基线 commit 为 `ea9668e4a`（2026-09-11 15:37） | `git log -1`：`ea9668e4a`「资源总览「所有资源」卡补上资源预览」 | 验收记录表回填此 hash 作为冻结基线 | +| 三个验收重点改动已入库，但**必须重新构建 / 重启客户端才会生效** | `2a157ea6f`「预览可见性门禁等 root 就绪再建 observer，并把登记表补挂齐」、`6bdc8bbd9`「AGC 资源分类面板改为「编辑素材标签」：只编辑标签、分类不再有手动入口」、`ea9668e4a`「资源总览「所有资源」卡补上资源预览」 | ① 可见卡停 `idle` 的修复；② 「编辑标签」只改 tags；③ 「所有资源」卡渲染真实预览。客户端若仍在跑旧构建（真机当前进程即属此列），这三条会得到**假失败** | +| 工作区仍有 1 个非本用例范围的文件处于修改态 | `git status --short`：`apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts`（3 insertions / 2 deletions） | 只影响 AGC 全量测试结果，不影响手工验收；该文件相关用例失败时先与基线比对再定性 | +| 真机项目落盘分类分布与旧构建指纹一致 | 真机 `.agent/manifest.json` 落盘 `category` = `unclassified 57 / ui-interaction 3 / scene 1` | 未用新构建复测时，卡片预览、标签面板、所有资源预览三条会得到**假失败** | + +> 结论：验收开始前先固化"客户端构建版本 + api-server 是否重启 + 基线 commit"三件事，否则后续结论不可信。 + +## 2. 主线一句话概述 + +用一次「做游戏」从零建项目 → Agent 对话产出首轮素材并登记进 manifest → 在资源总览与栏目画布上把 6 类资产与项目版本走一遍管理闭环（预览 / 搜索 / 选择多选 / 快速编辑 / 生成入口 / 编辑标签 / 重命名 / 下载 / 删除 / 版本切换）→ 回对话侧 @ 引用素材 + AI 润色 + 发送前提醒 → 在运行视图跑通本地 loopback 预览并完成退出收尾。 + +每一步的判据都落在 **F12 控制台可读的 DOM 属性**或 **Tauri IPC 调用**上。 + +## 3. 分步验收表 + +> PRD 行号指向 `docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`（当前 594 行）。 + +### A 阶段 · 从零进项目 + +| 步骤 | 操作 | 期望结果 | 对应 PRD 条款 | 怎么判"过了"（可观察判据） | 已知例外 / 未做项 | +| --- | --- | --- | --- | --- | --- | +| **S1** 建项 | 首页「做游戏」→ 输入需求 → 选择目录 → 确认为新项目 | 建项成功并直接进入项目工作台，不新建第二套页面或资产系统 | L7（四区）、L23（创作链路）、L108 | 进入后四区同时在 DOM：左侧平台导航、`.game-workbench-stage`（`aria-label="项目主视窗"`）、右侧 Supervisor 对话栏、底部 Agent Dock | 普通用户「新增资源」入口禁用（L108、L587） | +| **S2** 落地视图 | 进项目后不动鼠标，看中央区 | 落 `resource-overview`；manifest 里 `preview.status=running` 的**陈旧记录**不得把你直接丢进运行界面 | L145–146、**L165**（`run` 自动进入只认内存 registry 活体确认） | `document.querySelector('.game-workbench-stage')?.dataset.resourceViewState` ∈ `resources.list` / `resources.selected.` / `resources.ui-editor`；**该属性为 `undefined` 即说明已在 run 视图** | 陈旧记录对齐：命中"记录 running 但 registry 没跑"时调 `stop_local_game_preview` 并按真相投影 `{status:'stopped'}`（`sessionPreview.ts:87-101`） | +| **S3** 项目页面板（可跳过） | 「项目组」页：搜索、行尾更多菜单、Escape 关闭 | 表格只显示权威数据列；Escape 关菜单并把焦点还给触发按钮；移除只改本机最近项目记录、不动磁盘 | L135–139 | 无匹配状态提供「清除搜索」；document/body 无页面级横纵向溢出 | **L139 要求 populated fixture 截图 + 视频演示搜索/清除/行尾菜单** —— 视频条款，见 7.1 | + +### B 阶段 · 素材产生与登记 + +| 步骤 | 操作 | 期望结果 | 对应 PRD 条款 | 怎么判"过了" | 已知例外 / 未做项 | +| --- | --- | --- | --- | --- | --- | +| **S4** 首轮生成 | 在右侧 Supervisor 对话里发起首轮素材生成 | 生成由**对话启动**（不用画布按钮）；素材写入对应栏目并登记进 manifest；未生成的素材不显示为可编辑对象 | L25、L94、L500；飞书 §4 首轮生成 | 对话完成后 `.agent/manifest.json` 的 `assets[]` 长度增加；新卡 `data-resource-card-id` 为 `asset:` 形态 | 「首轮进度投影」只在 Issue 交付范围的"应该"清单出现、**无编码级判据**；现有可见性由底部 Agent 状态栏承载 | +| **S5** 栏目归属 | 看资源总览的栏目缩略卡与各栏目卡片 | 固定 7 栏：`UI 交互 → 角色与对象 → 场景与环境 → 音频 → 文档 → 待归类 → 项目版本`；分区口径是 manifest `assets[].category`，前端交互不能改分类 | L50、L56、L324、L358–360、L539 | `[...document.querySelectorAll('.game-resource-book-thumbnail[data-resource-book-category]')].map(e=>e.dataset.resourceBookCategory)`；再数每栏 `.game-resource-card` 数量 | **读时自愈**：落盘 `unclassified` 而 `kind` 能明确分类时按派生值显示（L360）。真机 57 条落盘 `unclassified` 在 UI 上应显示到正确栏目，**判定必须看 UI 计数，不能看 manifest 文件计数** | +| **S6** 卡片预览台账 | 逐栏目看卡片是否显示真实主体 | 图片与安全 SVG 直接显示主体并保留透明棋盘底；视频、音频、文档、项目版本用稳定固定卡；失败显示类型占位、不挂破图、不降级为项目外 URL | L55、L61–62、**L67**、L347–349 | 见 5.1 的四条脚本：区分"没读 / 读失败 / 解码为空 / 不适用" | **可见卡停 `idle` 的真 bug 已修但未提交**（`useProjectResourceCardPreviews.ts`）；未用新构建时会出现假失败 | + +### C 阶段 · 资源管理闭环 + +| 步骤 | 操作 | 期望结果 | 对应 PRD 条款 | 怎么判"过了" | 已知例外 / 未做项 | +| --- | --- | --- | --- | --- | --- | +| **S7** 栏目导航 | 点总览第 0 张「所有资源」卡 → 栏目缩略卡片进栏目 → 页内底部「下一页」 | 「所有资源」是汇总页（第 0 张）；全部栏目（含空栏目）都可到达；左侧悬浮栏目大纲导航已删除；滚轮不切栏目 | L56、L512、L539–541 | `[data-resource-book-all-page="true"]`、`[data-resource-book-all-host="true"]`、`[data-resource-book-view="main"\|"child"]`、当前栏目 `.game-resource-book-scene-titlebar.is-active[data-resource-book-category]` | 「所有资源」卡渲染真实预览属**未提交改动**（`game-resource-book-preview-card`）；旧构建只有占位摞 | +| **S8** 搜索 | 点右下角 `搜索资源` 按钮或按 `Ctrl/Cmd+F` → 输入 → Esc | 浮层收起**不清搜索条件**；`type=search` 原生 Esc 清空被 `preventDefault` 挡掉；存在搜索时 Dock 按钮高亮 | L55、L322（搜索只隐藏卡片、不重排坐标） | `button[aria-label="搜索资源"]` 的 `aria-expanded`、`title="搜索资源（Ctrl/Cmd+F）"`、`.is-active`；输入框 `input[type=search][aria-label="搜索项目资源"]`，其 `id` 等于按钮的 `aria-controls` | 匹配字段 = **名称 / 路径 / 媒体类型 / 任务标题**，不含 `sourceLabel` | +| **S9** 选择与多选 | 单击卡片 → `Shift`/`Ctrl`/`Meta` 再点 → 空白处拖拽框选 | 点卡 = 选中并在卡片旁浮出工具条；三种修饰键等效追加；框选可见选框 | L51、L61–62、L318–319 | `data-resource-card-id` + class 含 `is-selected` + `aria-pressed="true"`；浮出容器 `role="toolbar"`（图片 `aria-label="图片工具栏"`，音频 `"素材工具栏"`） | ⚠️ **PRD L61–62 要求的「打开详情」按钮在代码中不存在**（测试显式断言为 `null`），按 Issue #309 C3「取消资源详情面板与全屏编辑路由」判，不要判为缺失；真正入口是 `aria-label="选中资源：<栏目> <名>"` 按钮 | +| **S10** 快速编辑（图片） | 选中 PNG/JPEG/WEBP 卡 → 工具条「快速编辑」→ 输入 → 提交 | 先 `normalize_local_project_raster_resource`，再 `derive_local_project_resource(editKind='image-reference')` → 服务端 `/api/editor/images/edits`；**产出一张新素材**，源素材与源文件不变，新资源带 `referenceResourceIds` 血缘 | L123、L193、L476–478、L557；#309 C3/C10 | 提交后 `assets[]` +1、卡片 +1 且 `data-resource-card-id` 为新 id；**源卡仍在且内容未变**；工具条真渲染的只有 `quick-edit` 与 `download` | ① 服务端白名单 17 项（`editor_project.rs:4120-4141`），`character-animation`/`video`/`audio`/`document`/`code` 等**仍会 400**；② 工具条 7 个动作（重绘 / 裁剪扩图 / 去背景 / 像素完美 / 切图集 / 提取 UI 素材 / 角色动画）按 opt-in **不渲染** | +| **S11** 画布生成入口 | 画布级入口 → 选「视频 / 音效 / 背景音乐」→ 填名与提示词 → 提交 | 无源新建三类素材之一 → 新卡产出并定位 | 飞书 §4（首轮由对话启动）、L122 | 提交后 `assets[]` +1；面板是独立浮层（非在当前面板下方追加） | ⚠️ **Issue #309 写「画布生成入口未接」，但当前代码已接三类**（`resourceCanvasGenerationModel.ts` 仅 `video`/`sound-effect`/`background-music`）；图片等类型会直接报「当前资源类型不支持无源生成」 | +| **S12** 编辑标签 | 选中已登记素材 → 工具条「编辑标签」→ 增删标签 → 保存 | 面板**只编辑 `manifest.assets[].tags`**；`category` 读一次权威值后**原样回传**；顶部没有分类 chip 排 | L360（2026-09-11 收口）、#309 C2 | 面板标题「编辑素材标签」，底部只有「取消 / 保存标签」；保存后 `assets[n].tags` 变化而 `assets[n].category` **逐字不变** | 面板内的「删除资源」按钮是**唯一**删除入口，保留；「用户手动设置 category」这项能力已移除 | +| **S13** 重命名 | 工具条「重命名」→ 新文件名 → 确认 | 磁盘文件名与 manifest `localPath` 更新；**asset id 不变**；写盘失败回滚文件 | L362（资源身份稳定）、L515 | 弹窗 `ariaLabel="重命名素材"`；改名后「选中资源：…」按钮的无障碍名同步变化；引用 chip 与 @ 候选列表显示名刷新 | ⚠️ **不改游戏源码里对旧 `assets/` 的引用**，后果由用户自负 | +| **S14** 下载 | 选中可下载卡 → 工具条「下载」 | 弹出**原生保存对话框**选目标路径 → 分块复制；取消即停止 | L507、飞书 §11.1.2 | 出现 `title="保存素材"` 的原生对话框；成功后状态提示含 `已保存 <路径>` | 语义是"另存为"，不是静默直下；虚拟版本条目没有文件、不放行 | +| **S15** 删除 | 工具条 / 标签面板「删除」→ 确认弹窗 | 三分支：① 无引用→直接删；② 被引用未勾选→只删素材、版本保留**悬空绑定**、界面不合成幽灵资源卡；③ 勾选→素材与该批版本在**同一次 manifest 写入**内一起删 | L413（版本只追加的唯一例外）、L532–533；#309 C5 | 弹窗 `ariaLabel="确认删除资源"`；被引用时出现 `被 N 个游戏版本使用` + 版本列表 + checkbox `把相关游戏版本一并删除`；无引用时该 body 整块不渲染 | **只摘登记、不删磁盘文件**；读引用命令精确名是 `read_local_project_asset_references` | + +### D 阶段 · 版本与运行 + +| 步骤 | 操作 | 期望结果 | 对应 PRD 条款 | 怎么判"过了" | 已知例外 / 未做项 | +| --- | --- | --- | --- | --- | --- | +| **S16** 版本切换 | 运行模块**右上角**版本选择器 → 切到另一版本 | 触发钮显示当前版本；切换后资源卡「当前使用」高亮与 **@ 面板「当前版本素材」同步更新**，并重载当前预览 | L165、L190、L324、L530；#309 C7 | `aria-label="当前版本：