补充 UI 编辑器撤销重做规范

明确撤销与重做的 State 范围、事务边界和生命周期

明确连续控件与节点变换的低频提交规则

明确资产文件、副作用、快捷键和验收标准

docs/【UI编辑器】撤销重做规范-2026-09-03.md

@@ -0,0 +1,69 @@
+# UI 编辑器撤销与重做规范
+
+## 目标
+
+UI 编辑器支持撤销最近一次或多次作品编辑，并支持重做被撤销的编辑，降低误操作返工成本，同时保持现有保存、AI 工作流和资产文件行为不变。
+
+## 适用范围
+
+撤销历史属于当前 UI 编辑会话，历史只保存可序列化的编辑器 `State` 快照，不保存页面临时状态。
+
+纳入历史的操作：
+
+- 设计图名称、描述、角色和从属关系修改；
+- 设计图、精灵、字体资源的新增、删除和元数据修改；
+- 节点新增、删除、移动、Transform、Layout、元数据、子节点显示模式修改；
+- 组件新增、删除、排序和字段修改；
+- AI suggest、recognize、merge、bind，以及批量导入、批量删除等批量 State 修改，整次成功调用作为一条记录；
+- 节点拖动或缩放，按一次按下到松开的连续操作作为一条记录。
+
+不纳入历史的操作：
+
+- 选择项、隐藏节点、工作流步骤、面板展开状态和画布视口等 UI 临时状态；
+- 打开/切换项目、服务端重新加载和清空编辑器；这些操作替换 State 后重置历史；
+- 保存、自动保存、生成代码、发布请求本身；撤销只改变本地 State，后续保存才同步远端；
+- 素材上传、AI 生成等已发生的外部副作用；若副作用同时落地了本地 State，只撤销本地 State 变化；
+- no-op、锁定、校验失败或目标不存在的操作。
+
+导入资源被撤销时只回退编辑器 State 中的资源记录和引用，不删除已经写入磁盘的资产文件；重做恢复原资源 ID 与文件引用。
+
+## 历史模型
+
+- 栈按会话全局维护，最多保留最近 100 条事务；超限丢弃最旧记录。
+- 每条记录保存 `before` 与 `after` 的完整结构化 State 快照，快照不复制二进制文件内容。
+- 提交前后快照相同则不产生记录。
+- 撤销将当前 State 恢复为记录的 `before`，并把记录移入 redo 栈；重做恢复 `after`。
+- 撤销后发生新的有效编辑时清空 redo 栈。
+- 撤销/重做恢复 State 时不得再次写入历史。
+
+## 事务边界
+
+- 普通字段、按钮和列表操作一次成功调用对应一条记录。
+- 节点拖动/缩放期间只更新预览层临时变换；松开时提交最终变换并生成一条记录。取消、卸载、切换资源、未越过阈值或无变化不提交。
+- AI 和批量操作通过事务边界合并内部多次 State 替换，整次成功调用只生成一条记录；失败不留下部分历史。
+- 颜色选择器、九宫格边界拖动等连续控件在交互期间使用本地 draft 预览，释放或确认时一次提交。
+
+## 用户入口
+
+- 桌面端页面工具栏提供撤销和重做按钮。
+- 非文本编辑目标聚焦编辑器时支持 `Cmd/Ctrl+Z` 撤销、`Cmd/Ctrl+Shift+Z` 和 `Ctrl+Y` 重做。
+- `input`、`textarea`、`select`、`contenteditable` 以及按钮/链接等控件交给浏览器原生行为，不拦截文本撤销。
+- 无可撤销或重做记录时按钮禁用，并提供可访问名称。
+
+## 脏状态与选择
+
+撤销和重做恢复的 State 继续参与现有 dirty 判定、保存和后端持久化。历史快照不包含当前设计图、节点选择、隐藏集合或视口；恢复后若当前选择已不存在，页面清理无效选择并保持安全空态。
+
+## 验收标准
+
+1. 单次字段编辑可撤销和重做。
+2. 连续多次编辑按逆序撤销。
+3. 节点拖动/缩放一次手势只产生一条记录，取消和零变化不产生记录。
+4. AI/批量操作一次调用只产生一条记录，失败不产生部分记录。
+5. 撤销后新编辑清空 redo。
+6. 加载/切换/清空重置历史；保存/自动保存不清空历史。
+7. 撤销/重做资源导入不删除资产文件，并恢复原资源引用。
+8. 工具栏按钮、禁用态和桌面快捷键可用，文本控件保留原生撤销。
+9. no-op、锁定、校验失败和不存在目标不进入历史。
+10. 颜色选择器和九宫格边界拖动不会按每个 pointer move 写入 State。
+