替换面板改为非模态浮层，支持在画布上点选替换目标
- 共享选择组件新增 opt-in nonModal：不铺遮罩、不做焦点陷阱、限高 + 内部滚动，Esc 在 document 阶段截断后取消，关掉即卸载；网页端美术画布不传，弹窗行为逐字不变。 - 新增 initialSelectionRevision：面板开着时宿主换了目标才重同步当前选择，面板里的搜索词与分类筛选不被重置。 - AGC 侧把候选面板锚到画布右上角（任务开关下方），壳样式放共享样式表、宿主只负责锚定；面板开着时画布照常可点，点中合法候选落成面板当前选择，写入仍只由「确认」发起。 - 退役旧的「点选替换」按钮、画布提示条与 resourceReplacementPickMode：同一个功能不留两条 UI 路径；合法性判据仍复用 resolveResourceReplacementPick，写入仍是同一个 confirm 函数。 - 确认时用画布点选结果兜底，避免点完当帧按确认误报「请选择一个替换素材」。 - 测试：替换用例 4 条点选路径改写为非模态 + 面板点选（含四类非法目标在面板内报因、Esc 只收面板），新增「画布点选不清掉面板搜索/分类」；共享组件用例新增 nonModal 形态与浮层壳声明级契约。 - 文档：PRD 5.3 / 7.8 第 8 条改写、验收用例 S15a 改写、decision-log 新增 2026-09-21 条目、待办文档登记三项并勾掉对应需求。
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# AI 游戏创作项目开发工作台 PRD
|
||||
|
||||
更新时间：`2026-09-21`（2026-09-20 音频生成并入图片类那份后台任务账本、派生/修改类任务并入同一「生成任务」侧栏，2026-09-21 卡片浮层改为「提交即关」、**「生成任务」侧栏从画布左侧贴边改为画布右上角锚点（开关常驻）**、**资源卡可拖到对话栏批量 @ 引用**，见 §3.10 / §7.9 与 [`【功能说明】AGC聊天素材引用`](../【功能说明】AGC聊天素材引用-2026-09-08.md)；2026-09-14 图片类生成后台化：入口 IPC 为 `start_local_project_asset_generation` + 项目内任务账本 + 本地排队 + 非模态「生成任务」面板；2026-09-13 新增的功能画布底部工具栏入口矩阵 §3.10 / §7.9，以及右侧 Supervisor 对话气泡、可访问对比度与过程卡布局收口，资源卡预览、分区布局、非破坏性资源编辑、资源替换与 Godot 双根合同保持不变）
|
||||
更新时间：`2026-09-21`（2026-09-20 音频生成并入图片类那份后台任务账本、派生/修改类任务并入同一「生成任务」侧栏，2026-09-21 卡片浮层改为「提交即关」、**「生成任务」侧栏从画布左侧贴边改为画布右上角锚点（开关常驻）**、**资源卡可拖到对话栏批量 @ 引用**、**替换面板改为非模态浮层并支持在画布上点选目标**，见 §3.10 / §5.3 / §7.8 / §7.9 与 [`【功能说明】AGC聊天素材引用`](../【功能说明】AGC聊天素材引用-2026-09-08.md)；2026-09-14 图片类生成后台化：入口 IPC 为 `start_local_project_asset_generation` + 项目内任务账本 + 本地排队 + 非模态「生成任务」面板；2026-09-13 新增的功能画布底部工具栏入口矩阵 §3.10 / §7.9，以及右侧 Supervisor 对话气泡、可访问对比度与过程卡布局收口，资源卡预览、分区布局、非破坏性资源编辑、资源替换与 Godot 双根合同保持不变）
|
||||
|
||||
## 1. 产品定位
|
||||
|
||||
@@ -448,7 +448,7 @@ type ProjectVersionResourceReplacement = {
|
||||
- **失败即拒绝**：硬门禁任一项不等、源版本不存在、源版本未绑定该素材、替换素材未登记、替换素材与源素材相同、`expectedProjectId` / `expectedProjectRevision` CAS 冲突，都必须在写入前拒绝并说明原因；拒绝时 manifest、`versions` 与项目 revision 都不变，投影里不得出现新的版本卡或新的"当前使用"高亮。
|
||||
- **落盘与留痕**：改绑定属于 `versions` 变化，写入后推进一次 `projectRevision`；并追加一条 `asset.version_binding.replace` 审计（`versionId / sourceResourceId / replacementResourceId / projectRevision`）。**没有可回溯的替换历史**：替换前的身份只有这条审计与 manifest 的 `.previous` 恢复副本。
|
||||
- **入口与可见效果**：入口在资源卡选中工具条，只对「manifest 资产 + 被当前版本绑定」的素材放行；候选弹窗列出全部候选，命中硬门禁的项渲染但禁用并给出原因，只有尺寸规格差异的项仍可选但带提示。成功后**不切换版本**（没有新版本可切），只重读 manifest；可见变化是资源卡"当前使用"高亮移到替换素材、`@` 面板"当前版本素材"更新。按 §7.4 的口径，改绑定不做运行时资源重映射，运行画面本身不会因改绑定而变化；也不自动重载 / 重启运行中的预览（§3.2 末条）。
|
||||
- **点选替换（2026-09-13 补充）**：候选弹窗 footer 提供「点选替换」，用于"目标就在画布上、不想在面板里筛"的场景。点它**必须关闭弹窗**（弹窗外壳是全屏遮罩，留着它画布上的卡点不到）并进入画布点选态，画布上出现提示条（「在画布上点选要替换成的素材；点击空白处不会退出」+「取消」）。点中合法候选直接走**同一条**写入链路（载荷与弹窗确认逐字一致，不产生第二套替换口径），成功后自动退出点选态；点中非法目标（分类 / 类型不同、不在后端给出的权威候选里、源素材本身、未登记资源）**不写入**，在提示条上说明原因（与候选弹窗同一条翻译口径）并**留在**点选态。退出只有三条路：Esc（在 `document` 阶段截断，画布全局 Esc 的清选中不随之触发）、提示条「取消」、替换成功；**空白点击不退出、也不清画布选中**。点选态下卡片左键只用于点选（不起拖拽、不换选中，靠一次性抑制而不是全局关掉单击），滚轮平移与 `Ctrl/Cmd` 缩放照常可用。
|
||||
- **替换面板在画布上点选目标（2026-09-21；2026-09-13 的「点选替换」由此取代）**：候选面板是画布右上角的**非模态浮层**（无全屏遮罩、不做焦点陷阱，面板自身限高 + 内部滚动），面板开着的时候画布照常可点——在画布上点目标素材即把它落成**面板里的当前选择**（面板随之高亮；用户在面板里已输入的搜索与分类筛选不被重置），写入仍然只由面板「确认」发起（载荷与旧弹窗确认逐字一致，不产生第二套替换口径）。点中非法目标（分类 / 类型不同、不在后端给出的权威候选里、源素材本身、未登记资源）**不写入**，在面板里说明原因（同一条翻译口径）并保留原选择。退出只有两条路：面板「取消」/ 头部 ×、Esc（在 `document` 阶段截断，画布全局 Esc 的清选中不随之触发）；替换成功即关闭面板。面板开着时卡片左键只用于点选（不起拖拽、不换画布选中，靠一次性抑制而不是全局关掉单击），滚轮平移、`Ctrl/Cmd` 缩放与空白处框选照常可用。
|
||||
- **替换血缘标注（2026-09-13 补充）**：替换成功后只改绑定、光环本来就会从源素材移到替换素材，光靠光环说明不了"谁换成了谁"，所以在卡面补一层**关系标注**：源素材卡标「已被 <替换素材显示名> 替换」，替换素材卡标「替换自 <源素材显示名>」，两处分别给出稳定 DOM 判据 `data-resource-replaced-by` / `data-resource-replacement-of`，值是对面资源的 **manifest 资产 id**（不是显示名）。这份关系是**宿主会话内状态**：同一会话里再次替换**整条覆盖**上一条（只保留当前有效的一条 A→B，不做历史链，与 §7.8「只展示当前有效关系」同口径）；**切换项目 / 关闭工作台 / 重新加载 manifest 都不保留**——客户端没有替换关系的读侧事实源（写入结果只回 `versionId` / `committedProjectRevision`，审计 `asset.version_binding.replace` 只有写侧），manifest 的 `.previous` 只是原子安装的崩溃兜底副本、安装成功即删，不能当数据源，所以本标注**只在本次会话有效，不假装持久**。
|
||||
|
||||
### 5.4 游戏迭代版本（P1）
|
||||
@@ -657,7 +657,7 @@ type ProjectAgentMudPointAttribution = {
|
||||
5. 硬门禁任一为 false、源版本不存在、源版本未绑定该素材、替换素材未登记、替换素材与源素材相同、`expectedProjectId` / `expectedProjectRevision` 冲突，都必须在写入前拒绝；拒绝时 manifest、`versions` 与项目 revision 都不变，投影里不得出现新的"当前使用"高亮或版本卡变化。
|
||||
6. 成功后重读 manifest 并**不切换版本**（没有新版本可切）；**不**自动重载或重启运行中的预览（§3.2 末条），也不做运行时资源重映射。可见变化只有：资源卡"当前使用"高亮移到替换素材、`@` 面板"当前版本素材"更新。
|
||||
7. 替换成功后追加一条 `asset.version_binding.replace` 审计（`versionId / sourceResourceId / replacementResourceId / projectRevision`）；**替换历史不可回溯**——替换前身份只有这条审计与 manifest 的 `.previous` 副本，不得声称能查到"某版本历史上换过什么"。
|
||||
8. 候选弹窗提供「点选替换」（2026-09-13）：点它关闭弹窗进入画布点选态，并把「在画布上点选要替换成的素材；点击空白处不会退出」与「取消」放在画布提示条上；点中合法候选按第 3~7 条**同一条**链路提交并自动退出点选态，点中非法目标（分类 / 类型不同、不在权威候选里、源素材本身、未登记资源）零写入、留在点选态并在提示条上说明原因。退出只有 Esc（`document` 阶段截断，不清画布选中）/ 提示条「取消」/ 替换成功三条路，空白点击不退出；点选态下滚轮平移与缩放照常，卡片单击的既有语义在非点选态下不变。
|
||||
8. 替换面板在画布上点选目标（2026-09-21；取代 2026-09-13 的「点选替换」）：候选面板是非模态浮层，面板开着时画布保持可点，点画布上的候选即落进面板的当前选择（搜索与分类筛选不被重置），写入仍由面板「确认」按第 3~7 条**同一条**链路发起；点中非法目标（分类 / 类型不同、不在权威候选里、源素材本身、未登记资源）零写入并在面板里说明原因。退出只有面板「取消」/ × 与 Esc（`document` 阶段截断，不清画布选中）两条路，成功后自动关闭；面板开着时滚轮平移、缩放与空白框选照常，卡片单击的既有语义在面板关闭后不变。
|
||||
9. 替换血缘标注（2026-09-13）：替换成功后，源素材卡带「已被 <替换素材显示名> 替换」、替换素材卡带「替换自 <源素材显示名>」，稳定 DOM 判据 `data-resource-replaced-by` / `data-resource-replacement-of` 的值为对面资源的 manifest 资产 id；未参与替换的资源卡两个属性都不出现。同一会话内再次替换时**只保留当前有效的一条 A→B**（旧标注从卡上消失，不做历史链）。这份标注**只在本次会话有效**：切换项目 / 关闭工作台 / 重新加载 manifest 都不保留，也不得声称可回溯（第 7 条仍成立）。
|
||||
|
||||
### 7.9 P1 功能画布底部工具栏验收
|
||||
|
||||
@@ -1,5 +1,15 @@
|
||||
# 决策记录
|
||||
|
||||
## 2026-09-21 AGC 替换面板改为非模态浮层，支持在画布上点选目标
|
||||
|
||||
- 背景：`docs/project-memory/todos/【待办】画布验收后续修复-2026-09-18.md` 的「后续需求」要求「在替换面板中支持画布点选目标」。2026-09-13 那版做的是「候选弹窗 footer 一个『点选替换』按钮 → 关掉弹窗 → 进画布点选态 → 点中即提交」：面板与画布互斥（弹窗外壳是全屏遮罩，留着它画布上的卡点不到），用户要么在面板里筛、要么离开面板。
|
||||
- 决策：候选面板改成**非模态浮层**（共享组件新增 opt-in `nonModal`：不铺遮罩、不做焦点陷阱、面板自身限高 + 内部滚动、Esc 在 `document` 阶段截断后取消；网页端美术画布不传，弹窗行为逐字不变）。AGC 把它锚在画布**右上角、任务开关下方**（`.game-resource-replacement-panel` → `top: 8.5rem; right: 0.85rem`，壳样式在共享样式表里，宿主只负责锚定）。**面板开着时画布照常可点**：点中合法候选即落成面板里的当前选择（面板里随之 `aria-selected`），写入仍然只由面板「确认」发起；点中非法目标在面板里说明原因、零写入。旧的「点选替换」入口、画布提示条 `.game-resource-canvas-pick-hint` 与 `resourceReplacementPickMode` 随之退役（同一个功能不留两条 UI 路径）。
|
||||
- 决策（同步口径）：`selectedAssetIds` 的**数组引用不能当同步信号**（调用方每次渲染都会重建它，放进依赖会清掉用户在面板里的选择——组件里原本就为此写过一段注释），所以新增显式序号 `initialSelectionRevision`：只有宿主真的换了目标才重同步选择，搜索词与分类筛选保持原样。`confirmResourceVersionReplacement` 另外拿 `resourceReplacementPick` 兜底：点完画布当帧就按确认时不该报「请选择一个替换素材」。
|
||||
- 原因：面板与画布是同一屏的两半——目标本来就在画布上，「先把面板关掉再点」是弹窗外壳带来的妥协，不是产品意图。换成非模态之后，合法性判据仍是同一条 `resolveResourceReplacementPick`、写入仍是同一个 `confirm` 函数（载荷逐字一致），所以这是**外壳**的改动，不是第二套替换实现。
|
||||
- 已知取舍（相对旧口径的行为变化，均已随测试钉住）：面板开着时空白处点击不再被吞——画布恢复正常的清焦点 / 框选 / 平移语义（源身份在打开面板时就已冻结，替换不依赖画布选中）；「点中即提交」不再存在，提交一律由「确认」触发；关闭面板后卡片单击语义原样（一次性抑制照旧收尾）。
|
||||
- 验证：`resourceVersionReplacement.test.tsx` 19 passed（4 条旧点选用例改写为：非模态判据 + 点画布候选落进面板且零写入、面板确认才写入且载荷逐字一致+血缘、四类非法目标面板内报因零写入、Esc 只收面板不清选中；新增「画布点选不清掉面板搜索/分类」）、`projectAssetPickerDialogShellStyle.test.tsx` 7 passed（新增 nonModal 形态与浮层壳样式声明，含关掉即卸载）、`src/components/image-editor/ImageCanvasEditorView.test.tsx` 64 passed、`ImageCanvasEditorGenerationIntegration.test.tsx` 44 passed（网页端弹窗行为未变）；连同 `appSurface.test.ts`、`projectResourceLiveIntegration.test.tsx` 共 6 个文件 694 passed / 17 skipped / 0 failed；`tsc -p apps/ai-game-creator-shell/tsconfig.json --noEmit` 通过。
|
||||
- 影响范围：`src/components/image-editor/ImageCanvasProjectAssetPickerDialog.tsx`、`packages/shared/src/components/styles.css`、`apps/ai-game-creator-shell/src/view/project-development/index.tsx`、`.../features/resource-canvas/resourceCanvasChrome.css`、`apps/ai-game-creator-shell/tests/{resourceVersionReplacement.test.tsx,projectAssetPickerDialogShellStyle.test.tsx}`、PRD §5.3 / §7.8 第 8 条、`docs/technical/【测试用例】AGC资源工作台V3端到端验收-2026-09-11.md` 的 S15a。未动 Rust、SpacetimeDB、external v1。
|
||||
- 已知未覆盖：真机观感（面板在画布右上角的落点、与任务开关同时打开时的间距）未在 Tauri 目视确认；面板里不显示「本次替换的是哪张源素材」，源身份只靠画布上那张卡的选中光环表达——点空白清掉选中后就只剩面板自己的候选列表。
|
||||
## 2026-09-21 AGC 资源卡拖到对话实现批量 @ 引用
|
||||
|
||||
- 背景：`docs/project-memory/todos/【待办】画布验收后续修复-2026-09-18.md` 的「后续需求」要求「聊天拖拽批量引用」。改前只有两条入口：聊天输入框里输入 `@` 或点 `@` 按钮开素材选择面板，以及资源卡选中工具条上那枚「引用」按钮——都要先把素材找出来再点，多选批量引用没有一次成型的路径。
|
||||
|
||||
@@ -55,21 +55,29 @@
|
||||
- 范围核对：48 个改动文件全部落在 AGC 前端、3 个共享画布组件与 3 份文档；`server-rs` / `spacetime` / `docs/openapi` / `src-tauri` **零改动**（后端与契约无红线涉及），无 `.env`、密钥、构建产物或日志进入改动。
|
||||
- 合并后仍**未复验**的只有两类，且都不阻塞合并：① 真实客户端观感（本批动了动画面板样式、生图浮层紧凑排布与卡片基类 token——声明级与结构级都有守卫，真机要客户端验收确认）；② 远程 CI（runner/镜像问题仍在处理，见 Issue #431；按用户要求本批不追）。
|
||||
|
||||
### 2026-09-21 第四批（「生成任务」侧栏移到画布右上角，待客户端验收）
|
||||
### 2026-09-21 第四批（画布三项：生成任务侧栏右上角 / 拖到对话批量引用 / 替换面板画布点选，待客户端验收）
|
||||
|
||||
需求原文：「生成任务列表移到画布右上角（照抄美术画布，但是保留当前的样式）」，对应本文件「后续需求」里那条。
|
||||
需求原文（本文件「后续需求」里那两条，三项一起做）：
|
||||
|
||||
- 「生成任务列表移到画布右上角（照抄美术画布，但是保留当前的样式）」。
|
||||
- 「聊天拖拽批量引用」→ 拖动素材到对话实现批量 @ 引用。
|
||||
- 「画布点选替换」→ 在替换面板中支持画布点选目标。
|
||||
|
||||
- 改前：侧栏本体是 `position: fixed; top: 4rem; bottom: 6rem; left: 0.75rem` 的左侧贴边面板，开合口只有工具条上那一枚「生成任务 · N」按钮（资源 / 运行两个页签各渲染一次）；分组、失败可见、限高滚动、提交受理后自动展开这四条本批之前已经具备，本轮只动**位置与开合形态**。
|
||||
- 改后：新增右上角锚点 `.game-resource-generation-tasks-anchor`（`position: absolute; top: 3.5rem; right: 0.85rem; z-index: 40`，挂在 `.game-workbench-stage` 里），**开关常驻右上角、面板在开关左侧展开、收起只剩那一枚开关**（与美术画布同一形态）；工具条上那两处重复入口删除；面板改由 `max-height: min(30rem, calc(100vh - 12rem))` 封顶 + 内部滚动，自己不再定位。
|
||||
- 颜色 / 圆角 / 字重 / 阴影仍全部走 `--platform-*` token（开关沿用原工具条那枚次级胶囊的外观，只多一档面板投影），没有照搬网页端的固定色值。
|
||||
- 分档坐标：view 的 `placement`（`canvas | run | editor`）落成 `data-generation-tasks-placement`；运行表现层下移到 `top: 7rem`，避开它右上角 `game-run-version-picker`（`top: 20px; right: 20px`）。
|
||||
- 本机执行过：`resourceCanvasAssetGenerationTasksPanel.test.tsx` 11 passed、`resourceCanvasAssetGenerationTasksSidebarStyle.test.ts` 11 passed、`resourceCanvasGenerationTasksSidebarDismiss.test.tsx` 5 passed、`resourceCanvasAssetGenerationBackgroundClose.test.tsx` 5 passed；仓库根 `tests/appSurface.test.ts` **538 passed / 17 skipped / 0 failed**（与既有基线逐条一致）；`tsc -p apps/ai-game-creator-shell/tsconfig.json --noEmit` 通过。
|
||||
- 仍未做：真实客户端目视（右上角落点、与版本入口的间距）与远程 CI 都没跑；窄屏（≤480px）只有声明级断言。
|
||||
- **本批第二项（拖到对话批量引用）**：资源卡按住拖到右侧 Agent 对话栏、松手即按这次拖动真正参与位移的那批（多选整批、单选只引用按住的那张）插入 `@` 引用；落点铺虚线框 + 「松手即可 @ 引用 N 项素材」，拖回画布内松手仍是排版语义；引用口径与工具条「引用」按钮逐字一致（只认已登记素材、`source: resource-card`），派发走新增的批量事件一次事务插入。
|
||||
- **本批第三项（替换面板画布点选）**：替换候选面板从全屏弹窗改为**画布右上角的非模态浮层**（共享组件新增 opt-in `nonModal`，网页端弹窗行为不变），面板开着时画布照常可点——点中合法候选即落成面板里的当前选择，写入仍只由「确认」发起；非法目标在面板里报因、零写入。旧的「点选替换」按钮、画布提示条与点选态随之退役（同一个功能不留两条 UI 路径）。
|
||||
- 本机执行过（三项合计）：`resourceCanvasAssetGenerationTasksPanel` / `…SidebarStyle` / `…SidebarDismiss` / `…BackgroundClose`、`resourceCardReferenceDropModel`、`resourceCanvasChatReferenceDrop`、`resourceReferenceInput`、`resourceVersionReplacement`、`projectAssetPickerDialogShellStyle`、`ImageCanvasEditorView`、`ImageCanvasEditorGenerationIntegration`、`projectResourceLiveIntegration`、`appSurface` 全绿（定向批次多项合计 694 passed / 17 skipped）；`typecheck`、`check:encoding`、`git diff --check`、prettier / eslint 通过。
|
||||
- 仍未做：真实客户端目视（三项的真机手感与落点）与远程 CI 都没跑；窄屏（≤480px）只有声明级断言；「复制对话保留有效引用」未做。
|
||||
|
||||
## 后续需求
|
||||
|
||||
- 资源卡顶部独立名称区与全类型统一样式，确认 assetName/用户素材名的正式来源。
|
||||
- ~~生成任务列表移到画布右上角，进行中/已完成分组、失败可见、限高滚动及自动开合。~~ **2026-09-21 已处理**：侧栏改挂画布右上角锚点（开关常驻、面板在开关左侧展开，形态照抄美术画布，样式仍走 AGC 平台 token），工具条上的重复入口删除；`placement` 分档让运行表现层让开右上角版本入口。见下「2026-09-21 第四批」。
|
||||
- 素材替换关系与画布点选替换；聊天拖拽批量引用、复制对话保留有效引用。
|
||||
- ~~素材替换关系与画布点选替换；聊天拖拽批量引用~~ **2026-09-21 已处理**：替换面板改为画布右上角的非模态浮层、可直接在画布上点选目标素材；资源卡可拖到对话栏批量 @ 引用。见下「2026-09-21 第四批」。「复制对话保留有效引用」仍未做（同一条需求里的另一半）。
|
||||
|
||||
## 边界与验收
|
||||
|
||||
|
||||
@@ -55,7 +55,7 @@
|
||||
| **S13** 重命名 | 工具条「重命名」→ 新文件名 → 确认 | 磁盘文件名与 manifest `localPath` 更新；**asset id 不变**；写盘失败回滚文件 | L362（资源身份稳定）、L515 | 弹窗 `ariaLabel="重命名素材"`；改名后「选中资源：…」按钮的无障碍名同步变化；引用 chip 与 @ 候选列表显示名刷新 | ⚠️ **不改游戏源码里对旧 `assets/<name>` 的引用**，后果由用户自负 |
|
||||
| **S14** 下载 | 选中可下载卡 → 工具条「下载」 | 弹出**原生保存对话框**选目标路径 → 分块复制；取消即停止 | L507、飞书 §11.1.2 | 出现 `title="保存素材"` 的原生对话框；成功后状态提示含 `已保存 <路径>` | 语义是"另存为"，不是静默直下；虚拟版本条目没有文件、不放行 |
|
||||
| **S15** 删除 | 工具条 / 标签面板「删除」→ 确认弹窗 | 三分支：① 无引用→直接删；② 被引用未勾选→只删素材、版本保留**悬空绑定**、界面不合成幽灵资源卡；③ 勾选→素材与该批版本在**同一次 manifest 写入**内一起删 | L413（版本只追加的唯一例外）、L532–533；#309 C5 | 弹窗 `ariaLabel="确认删除资源"`；被引用时出现 `被 N 个游戏版本使用` + 版本列表 + checkbox `把相关游戏版本一并删除`；无引用时该 body 整块不渲染 | **只摘登记、不删磁盘文件**；读引用命令精确名是 `read_local_project_asset_references` |
|
||||
| **S15a** 替换素材（含点选替换） | 选中被**当前版本**绑定的素材 → 工具条「替换素材」→ 候选弹窗（弹窗内可筛可选）；再点 footer「点选替换」→ 弹窗关闭、进入画布点选态 → 在画布上直接点目标素材 | 弹窗确认与点选是**同一条**写入链路（`replace_local_project_version_resource`，载荷逐字一致）：改该版本绑定、不建新版本；点选态下合法目标直接提交并自动退出点选态，非法目标零写入、**留在**点选态并在提示条上说明原因 | PRD §5.3 / §7.8 第 8 条；#309「直接替换」口径 | 点选态判据：候选弹窗 `role="dialog"` 已卸载；画布出现 `.game-resource-canvas-pick-hint`，文案含「在画布上点选要替换成的素材」与「点击空白处不会退出」，并有「取消」按钮；非法目标后提示条仍在且出现 `role="alert"`（「替换素材不兼容：分类不同」/「替换素材与源素材相同」/「替换素材未登记或已被删除」）；点选期间卡片 `aria-pressed` 不变（单击只用于点选）、源素材选中与工具条不因点空白或点非法目标而丢；Esc 退出点选（画布全局 Esc 的清选中不随之触发）；点选态下滚轮平移与缩放照常可用 | 点选只能点**当前画布上可见**的卡：目标在别的栏目时先切栏目（点选会话跨栏目存活，不因「收起资源」或切栏目结束）；空白点击不退出、也不清画布选中 |
|
||||
| **S15a** 替换素材（面板内选 + 画布点选目标） | 选中被**当前版本**绑定的素材 → 工具条「替换素材」→ 画布右上角出现非模态候选面板（面板内可筛可选）→ 直接在画布上点目标素材（或点面板里的候选）→ 面板「确认」 | 面板确认与画布点选是**同一条**写入链路（`replace_local_project_version_resource`，载荷逐字一致）：改该版本绑定、不建新版本；画布点选只把目标落成面板的当前选择，确认后才写入 | PRD §5.3 / §7.8 第 8 条；#309「直接替换」口径 | 面板判据：`role="dialog"` 名为「选择替换素材」、挂 `.image-canvas-editor__project-asset-picker--floating`、**没有** `.platform-overlay` 遮罩；点画布候选后面板里该候选 `aria-selected="true"`、面板里的搜索词与分类筛选保持原样、零写入；非法目标（源素材本身 / 不在权威候选里 / 分类不同 / 未登记资源）在面板里出现 `role="alert"`（「替换素材与源素材相同」/「替换素材未登记或已被删除」/「替换素材不兼容：分类不同」）且零写入；面板关闭 = 卸载；Esc 只收面板（画布全局 Esc 的清选中不随之触发） | 点选只能点**当前画布上可见**的卡：目标在别的栏目时先切栏目（替换会话跨栏目存活，不因「收起资源」或切栏目结束）；面板开着时空白处仍可框选 / 平移，卡片单击语义的恢复发生在面板关闭之后 |
|
||||
|
||||
| **S11a** 栏目画布底部工具栏 | 进「UI 交互 / 角色与对象 / 场景与环境 / 音频」任一栏目 → 点左下角工具栏里的入口生成 → 「收起资源」回总览看工具栏消失 | 工具栏只在矩阵四个栏目（功能画布）渲染；图片类入口走 `start_local_project_asset_generation`（提交即返回、生成在后台跑），音频入口走同一条命令的音频载荷，上传复用 `upload_local_asset`；生成 / 上传成功后走既有 manifest 刷新与资源定位 | PRD §3.10、§7.9 | DOM 判据 `[data-resource-bottom-toolbar="<category>"]`（资源总览、「所有资源」展开态、文档、待归类、项目版本都**没有**这个节点）；工具栏是 `.game-resource-book-manager` 的直接子节点（`closest('.game-resource-book-scene')` 为 `null`）；每个入口一次 `start_local_project_asset_generation`：图片类载荷逐字为 `{ projectPath, projectId, taskId, kind, prompt, aspectRatio, imageSize, assetName, outputPath }`（`kind` 映射见 PRD §7.9 第 3 条；`taskId` 是前端每次提交新铸的本地任务 id），音频类载荷为 `{ projectPath, projectId, taskId, kind, prompt, assetName, idempotencyKey }`（`taskId` 即该次生成的 operation id，不发图片类那套比例 / 尺寸 / 参考 / 落点参数）；该命令提交即返回，之后有 `list_local_project_asset_generations` 轮询与 `get_local_game_project_revision` + `get_local_game_manifest` 的配对读；点「生成」即把这次输入交给后台账本并**同步关闭**面板（不等 IPC、不等排队、不等生成，画布立即恢复可交互；面板 DOM 里没有阶段文案与「后台运行并关闭」这类在途按钮），关闭不等于取消，关闭后任务仍出现在「生成任务」面板（入口按钮 `aria-label="生成任务"`，非模态浮层、无 `aria-modal`）并显示后端 `phaseDetail`；第一条未终态时提交第二条 → 第二条显示「排队中。」且生成提交 IPC 次数仍为 1，第一条终态后自动补发（次数变 2）；缺 `assets/art-spec.png` 时「生成图标素材 / 生成 UI 设计图」仍可点击（`aria-disabled="true"` 但**不是**原生 disabled）并给出含该路径的 `role="alert"` 原因、零生成请求；音频入口面板标题即「生成背景音乐」/「生成音效」且没有类型选择器 | ① 本地通道没有 `model` / `specType` / `replaceExisting` 入参：面板不渲染模型选择器，角色规范与自定义规范共用 `spec` 通道（靠 `assetName` 与提示词区分），「图标规范」在项目已有权威规范图时不再指向 `assets/art-spec.png`（否则会被 Rust 的防覆盖校验硬拒）；② 本轮不做生成视频 / 宣发素材 / 生成游戏场景 / 选择工具 / 抓手工具；③ 既有「生成素材」浮层入口只保留生成视频，音频入口只在音频栏目工具栏出现 |
|
||||
|
||||
@@ -271,5 +271,5 @@ api-server 是否本次重启：□ 是 □ 否
|
||||
|
||||
## 8. 验收边界
|
||||
|
||||
- 本用例覆盖：资源总览 / 栏目分页画布、资源卡预览与本地受控读取、资源卡选择与多选、快速编辑派生（含提示词内 @ 引用）、画布生成入口（浮层视频 + 栏目工具栏图片类与音频）、编辑标签、重命名、下载、删除三分支、版本切换与当前使用高亮、**资源替换（入口放行判据 / 候选禁用与原因 / 格式提示 / 写入载荷 / 拒绝零副作用 / 成功后不切版本不重载预览 / 弹窗与画布点选两条入口同一条写入链路）**、聊天 @ 引用（两页签 + 功能分类 + 多标签筛选 + 搜索）与原子 chip、AI 润色与发送前提醒、本地预览启动与退出收尾、两份布局 sidecar 台账。
|
||||
- 本用例覆盖：资源总览 / 栏目分页画布、资源卡预览与本地受控读取、资源卡选择与多选、快速编辑派生（含提示词内 @ 引用）、画布生成入口（浮层视频 + 栏目工具栏图片类与音频）、编辑标签、重命名、下载、删除三分支、版本切换与当前使用高亮、**资源替换（入口放行判据 / 候选禁用与原因 / 格式提示 / 写入载荷 / 拒绝零副作用 / 成功后不切版本不重载预览 / 非模态面板 + 画布点选目标同一条写入链路）**、聊天 @ 引用（两页签 + 功能分类 + 多标签筛选 + 搜索）与原子 chip、AI 润色与发送前提醒、本地预览启动与退出收尾、两份布局 sidecar 台账。
|
||||
- 本用例不覆盖（另走专项或定向测试）：双窗口 CAS 冲突、大规模 fixture 性能、素材创作无限画布阶段一至五的草稿 / 事务 / 恢复矩阵（见 `【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` 与配套专题）、UI 编辑器子路由、主站图片编辑器回归（见 PRD §7.7）。资源替换的后端矩阵（版本绑定改写放行的六条不变式与两组互斥、绑定改写两条路径、硬门禁与提示、CAS、四条拒绝路径、读时自愈口径、审计留痕）见 `apps/ai-game-creator-shell/src-tauri/src/project/manifest/version_binding_rewrite_tests.rs` 与 `apps/ai-game-creator-shell/src-tauri/src/tests/version_resource_replacement.rs`，前端矩阵见 `apps/ai-game-creator-shell/tests/resourceVersionReplacement*.test.ts(x)`。
|
||||
|
||||
Reference in New Issue
Block a user