文档：明确BGM撤销按钮可见性与禁用口径

- 权威设计「单层撤销」增加撤销按钮可见性与可用性小节：可见条件为存在可撤销快照或本次 AI 操作的临时快照，启用条件为可见且面板未处于 completing / simplifying / submitting / generating 锁定状态，并补 10 行状态矩阵。
- 说明发起 AI 操作时可撤销快照被本次临时快照取代，「处理中没有可撤销快照」不等于「没有快照」，不得据此隐藏按钮；禁止为让处理期间按钮可见而保留旧快照，避免与 AI 失败不恢复旧快照冲突。
- 权威设计「AI 操作与方案 A 提交锁」限定「禁用撤销」指显示并禁用，可见性按单层撤销矩阵判定，不得隐藏。
- 权威设计验收增加撤销按钮逐行验收，要求处理期间按钮仍在可访问树中且为真实禁用态，不得用隐藏或视觉伪装代替禁用。
- decision-log 追加对应长期交互决策，标注不修改状态模型字段且不适用于 SFX。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/project-memory/shared-memory/decision-log.md

@@ -5956,3 +5956,13 @@
 - 影响范围：BGM composer 动作状态与 client、`api-server` Prompt 助手路由和候选验收、`platform-llm` 公共未完成原因 predicate、route tracking 静态映射及相应测试；不修改 SFX、正式 BGM 200 字限制、canonicalization 算法、SpacetimeDB schema、External v1 / OpenAPI 或 LLM 原文日志策略。
 - 验证方式：覆盖 canonical 2000 / 2001、两个路由 `32 KiB` / `413`、补全与两轮简化的 `length` / `content_filter`、缺失和未知 reason 兼容、连续合法请求无功能级 `429`，以及两个成功路由的 event key、`editor` module 和 User scope；运行 `api-server` 与 `platform-llm` 定向测试、`npm run check:encoding` 和 `git diff --check`。
 - 关联文档：`docs/【编辑器】画板音乐生成入口设计-2026-06-18.md`。
+
+---
+
+## 2026-08-04 BGM 撤销按钮按快照存在性显示、按面板锁定禁用
+
+- 背景：需求《BGM生成优化需求 V1.0》第三节要求“AI 开始处理”时撤销按钮显示但禁用，权威设计也只要求处理中禁用撤销，但没有写明可见性；T4 界面方案据此把渲染条件收窄为“存在可撤销快照”，而状态模型在发起 AI 操作时会把可撤销快照转为本次临时快照，两者叠加会让撤销按钮在处理期间消失，与需求不一致。
+- 决策：撤销按钮的可见条件为存在可撤销快照或本次 AI 操作的临时快照，启用条件为可见且当前 BGM 面板未处于 `completing`、`simplifying`、`submitting` 或现有 `generating` 锁定状态。因此 AI 处理期间显示并禁用，AI 失败、点击预设和完全无快照时隐藏，AI 成功、手动编辑 AI 结果和连续撤销互换时显示并启用，`submitting` 期间有快照显示并禁用、无快照隐藏，解除锁定后按快照恢复。禁用必须使用真实禁用态并保留按钮在 DOM 与可访问树中的位置，不得用隐藏、透明度或其它视觉伪装代替，也不得因锁定改变按钮占位。发起 AI 操作时仍以当时的 canonical Prompt 替换旧快照，不得为了让处理期间按钮可见而保留旧快照；那会与本日第一条“AI 失败不恢复已被替换的旧快照”冲突，并让失败后的撤销指向不相关内容。视图只按该矩阵决定显示与启用，是否真正执行撤销仍由状态层在非 `idle` 或无快照时拒绝，两处不得各写一套判定。
+- 影响范围：`/editor/canvas` 的 `audio-background-music` 面板撤销按钮与其定向测试；不改变单层交换快照语义、canonicalization、提交锁、Suno 契约或后端 Prompt 助手，也不修改状态模型字段，`temporaryPromptSnapshot` 已在公开 dialog 状态中且只在 `completing` / `simplifying` 期间非空。本条不适用于 SFX，V1.0 不改动 SFX 的一键优化与撤销行为。
+- 验证方式：按矩阵逐行覆盖初始隐藏、首次与再次 AI 处理期间显示并禁用、成功启用、失败隐藏、手动编辑后仍启用、点击预设隐藏、`submitting` 有无快照的两种表现、解除锁定后恢复，以及连续撤销互换保持启用；并断言处理期间按钮仍在可访问树中且为真实禁用态。
+- 关联文档：`docs/【编辑器】画板音乐生成入口设计-2026-06-18.md`。

docs/【编辑器】画板音乐生成入口设计-2026-06-18.md

@@ -159,6 +159,28 @@
 - 点击撤销时，先把当前输入规范化并写回，再让该 canonical Prompt 与 canonical 快照互换；按钮继续可用，允许用户在两个规范化版本间来回切换。
 - 只保存一层，快照只包含 canonical Prompt，不包含预设滚动位置、展开状态、模型、时长或其它参数。
 
+撤销按钮的可见性与可用性：
+
+- 可见条件为存在可撤销快照或本次 AI 操作的临时快照；启用条件为可见且当前 BGM 面板未处于 `completing`、`simplifying`、`submitting` 或现有 `generating` 锁定状态。发起 AI 操作时可撤销快照被本次临时快照取代，因此“处理中没有可撤销快照”不等于“没有快照”，不得据此隐藏按钮。
+- AI 处理期间按钮显示并禁用，不得隐藏。禁用必须使用真实禁用态并保留按钮在 DOM 与可访问树中的位置，不得用隐藏、透明度或其它视觉伪装代替，也不得在处理前后改变按钮占位。
+- 完全没有快照时隐藏，不显示灰色占位按钮。
+
+| 状态 | 可撤销快照 | 本次临时快照 | 撤销按钮 |
+| --- | --- | --- | --- |
+| 初始进入面板、没有历史快照 | 无 | 无 | 隐藏 |
+| AI 开始处理，首次或再次均相同 | 无 | 有 | 显示并禁用 |
+| AI 处理成功并写回输入框 | 有 | 无 | 显示并启用 |
+| AI 处理失败、原文未改变 | 无 | 无 | 隐藏 |
+| 用户手动编辑 AI 结果 | 有 | 无 | 显示并启用 |
+| 点击预设词条 | 无 | 无 | 隐藏 |
+| 点击生成提交且已有快照 | 有 | 无 | 显示并禁用 |
+| 点击生成提交且没有快照 | 无 | 无 | 隐藏 |
+| 提交成功或失败后解除锁定 | 有或无 | 无 | 有快照时显示并启用，否则隐藏 |
+| 点击撤销 | 有，与当前文本互换 | 无 | 保持显示并启用 |
+
+- 再次发起 AI 操作时仍按上面的规则用当时的 canonical Prompt 替换旧快照；不得为了让处理期间按钮可见而保留旧快照，那会与“AI 失败不恢复已被替换的旧快照”冲突，并让失败后的撤销指向不相关内容。
+- 视图只按上表决定显示与启用；是否真正执行撤销仍由状态层在非 `idle` 或无快照时拒绝，两处不得各写一套判定。
+
 ### AI 操作与方案 A 提交锁
 
 当前 BGM generation dialog 的 Prompt 助手状态为：
@@ -171,7 +193,7 @@ idle
 ```
 
 - `completing` / `simplifying` 开始时以同步 operation ID 取得当前 dialog 操作权；同一操作的后续双击无效。新操作使旧 operation ID 失效，关闭 dialog 时中止请求，dialog ID 或 operation ID 不匹配的迟到响应必须丢弃。
-- AI 处理中输入框只读，禁用预设展开/收起、预设词条、滚动箭头、AI 补全、一键简化、撤销和生成。
+- AI 处理中输入框只读，禁用预设展开/收起、预设词条、滚动箭头、AI 补全、一键简化、撤销和生成。这里的“禁用撤销”指显示并禁用，可见性按“单层撤销”一节的矩阵判定，不得隐藏。
 - 点击生成的同步事件内必须在任何 `await` 前依次完成：立即把当前 BGM dialog 切换到 `submitting`、计算 canonical Prompt 并写回输入框、按 canonical Prompt 校验 0 个有效字符和 200 字上限、冻结本次请求值。前端校验失败时立即解除锁并保留写回后的 canonical Prompt，不发送请求。提交中锁定该 dialog 的输入框、预设、展开/收起、滚动箭头、AI 操作、撤销、参数控件和生成按钮，忽略后续重复点击。
 - 锁只作用于当前 BGM dialog，不锁整个画布、其它 generation dialog、画布拖动、缩放、图层操作或其它编辑能力。
 - 后端拒绝正式提交时，解除锁，恢复当前面板并保留已经写回的 canonical Prompt 与提交前已有撤销快照，继续使用现有正式生成错误展示。
@@ -338,6 +360,7 @@ POST /api/editor/audios/background-music/prompts/simplifications
 - Prompt 助手协议测试必须证明请求显式使用 OpenAI Chat 且不发送 function tools；只接受完整 `response.text` 全量解析所得的单个 JSON object。外围 JSON whitespace 可以通过，代码块、前后解释、多个 JSON 值、畸形 JSON、仅能子串提取的 object 和任意 tool call 均失败，不触发自动修复或运行时协议 fallback。
 - Prompt 助手轮次测试必须区分业务语义轮和单轮内部 transport retry：补全始终只有一个业务语义轮；简化只有第一轮成功返回但候选不合格时才进入 170 字轮，第一轮 transport、超时或上游失败不进入第二轮。
 - AI 补全和简化成功均产生一层 canonical Prompt 交换式撤销快照；手动编辑后仍可撤销，点击预设清除快照，点击撤销前先规范化当前输入并可在两个 canonical 版本间反复互换。
+- 撤销按钮按“单层撤销”一节的矩阵逐行验收：初始与无快照时隐藏；AI 处理期间显示并禁用，且仍在可访问树中，不得用隐藏或视觉伪装代替禁用；成功后启用，失败后隐藏，手动编辑后仍启用，点击预设后隐藏；`submitting` 期间有快照显示并禁用、无快照隐藏，解除锁定后按快照恢复启用或隐藏；连续点击撤销在两个版本间互换且保持启用。
 - AI 操作的旧响应、关闭 dialog 后的响应或其它 dialog 的响应不得覆盖当前 Prompt；同一按钮双击只产生一个有效助手请求。
 - BGM 点击生成后在首个 `await` 前同步锁定当前 dialog；同一 dialog 快速重复点击只产生一次正式请求、一个生成任务和一次扣费，不锁整个画布或其它 dialog。
 - BGM 正式提交会删除首尾 Unicode `White_Space` 并同步写回输入框，不回退默认 Prompt；首尾 U+0085 等 `White_Space` 被删除，内部空格和 LF / CRLF 原样保留，U+200B、U+FEFF、组合字符和 ZWJ emoji 不被误删。canonical Prompt 在输入框、BFF、队列载荷、Suno body、生成记录和结果响应中完全一致，且没有用户不可见的前缀、后缀或模板。