docs(xceditor): deepen foundation api pages

docs/api/XCEditor/Foundation/UIEditorShortcutManager/UIEditorShortcutManager.md

@@ -1,45 +1,64 @@
 # UIEditorShortcutManager
 
-**命名空间**: `XCEngine`
+**命名空间**: `XCEngine::UI::Editor`
 
 **类型**: `class`
 
 **头文件**: `XCEditor/Foundation/UIEditorShortcutManager.h`
 
-**描述**: 定义 `XCEditor/Foundation` 子目录中的 `UIEditorShortcutManager` public API。
+**描述**: editor 快捷键绑定与调度入口，负责把 `UIShortcutRegistry` 的匹配结果连接到 editor 命令系统。
 
-## 概述
+## 概览
 
-`UIEditorShortcutManager.h` 是 `XCEditor/Foundation` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`UIEditorShortcutManager` 在 `UIShortcutRegistry` 和 `UIEditorCommandDispatcher` 之间增加了一层 editor 语义：
 
-## 声明概览
+- 先校验 command registry 和 shortcut binding 是否自洽
+- 再根据输入事件和 `UIShortcutContext` 找到最佳匹配 binding
+- 最后把匹配结果转换成 editor command dispatch
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `UIEditorShortcutManagerValidationCode` | `enum class` | 头文件中的公开声明。 |
-| `UIEditorShortcutManagerValidationResult` | `struct` | 头文件中的公开声明。 |
-| `UIEditorShortcutDispatchStatus` | `enum class` | 头文件中的公开声明。 |
-| `UIEditorShortcutDispatchResult` | `struct` | 头文件中的公开声明。 |
-| `UIEditorShortcutManager` | `class` | 头文件中的公开声明。 |
+它同时还承担 shortcut 文案格式化，所以 menu bar / context menu 可以直接显示“当前推荐快捷键文本”。
 
-## 公共方法
+## 主要声明
 
-| 方法 | 描述 |
+| 声明 | 角色 |
 |------|------|
-| [UIEditorShortcutManager()](Constructor.md) | 构造对象。 |
-| [GetCommandDispatcher](GetCommandDispatcher.md) | 获取相关状态或对象。 |
-| [SetHostCommandHandler](SetHostCommandHandler.md) | 设置相关状态或配置。 |
-| [GetHostCommandHandler](GetHostCommandHandler.md) | 获取相关状态或对象。 |
-| [GetCommandRegistry](GetCommandRegistry.md) | 获取相关状态或对象。 |
-| [GetShortcutRegistry](GetShortcutRegistry.md) | 获取相关状态或对象。 |
-| [RegisterBinding](RegisterBinding.md) | 注册对象、回调或映射。 |
-| [UnregisterBinding](UnregisterBinding.md) | 取消注册对象、回调或映射。 |
-| [ClearBindings](ClearBindings.md) | 清空内部数据。 |
-| [ValidateConfiguration](ValidateConfiguration.md) | 公开方法，详见头文件声明。 |
-| [GetPreferredShortcutText](GetPreferredShortcutText.md) | 获取相关状态或对象。 |
-| [Dispatch](Dispatch.md) | 公开方法，详见头文件声明。 |
+| `UIEditorShortcutManagerValidationCode` | 快捷键配置校验失败原因。 |
+| `UIEditorShortcutManagerValidationResult` | 快捷键配置校验结果。 |
+| `UIEditorShortcutDispatchStatus` | `NoMatch / Suppressed / Dispatched / Rejected` 四类结果。 |
+| `UIEditorShortcutDispatchResult` | dispatch 后返回的命令 id、scope、owner 和 workspace command 结果。 |
+| `UIEditorShortcutManager` | 快捷键绑定、校验和调度器本体。 |
+
+## 当前实现行为
+
+- `ValidateConfiguration()` 当前会拒绝：
+  - 无效 command registry
+  - binding 缺少 `commandId`
+  - binding 指向未知命令
+  - `keyCode == 0`
+  - 非 `Global` scope 却没有 `ownerId`
+  - chord/scope/owner 完全冲突的重复 binding
+- `GetPreferredShortcutText(...)` 会按 `Widget > Panel > Window > Global` 的展示优先级挑选 binding，并把 chord 格式化成 `Ctrl+H` 这类文本。
+- `Dispatch(...)` 当前流程是：
+  - 配置校验
+  - `m_shortcutRegistry.Match(...)`
+  - 若 `textInputActive == true`，返回 `Suppressed`
+  - 调用 `m_commandDispatcher.Dispatch(...)`
+  - 把匹配到的 scope / owner 和 command result 一并回填到结果结构
+
+## 测试与调用链
+
+- `tests/UI/Editor/unit/test_ui_editor_shortcut_manager.cpp`
+  - 当前覆盖未知命令、冲突 chord、active-panel 路由、panel scope 优先于 global，以及 text-input suppression。
+- `tests/UI/Editor/integration/state/shortcut_dispatch/main.cpp`
+  - 当前验证 shortcut manager 在 editor shell 状态路径上的实际行为。
+- `new_editor/src/Shell/UIEditorShellAsset.cpp`
+  - 当前用 asset 中的 command registry + bindings 构建 editor 快捷键管理器。
+- `new_editor/src/Shell/UIEditorMenuModel.cpp`
+  - 当前通过它读取 shortcut 文案并参与 menu item 启用态生成。
 
 ## 相关文档
 
-- [当前目录](../Foundation.md) - 返回 `Foundation` 平行目录
-- [API 总索引](../../../main.md) - 返回顶层索引
+- [Foundation](../Foundation.md)
+- [UIEditorCommandRegistry](../UIEditorCommandRegistry/UIEditorCommandRegistry.md)
+- [UIEditorCommandDispatcher](../UIEditorCommandDispatcher/UIEditorCommandDispatcher.md)
+- [UIShortcutRegistry](../../../XCEngine/UI/Input/UIShortcutRegistry/UIShortcutRegistry.md)