docs(xceditor): deepen foundation api pages

docs/api/XCEditor/Foundation/UIEditorCommandDispatcher/UIEditorCommandDispatcher.md

@@ -1,43 +1,60 @@
 # UIEditorCommandDispatcher
 
-**命名空间**: `XCEngine`
+**命名空间**: `XCEngine::UI::Editor`
 
 **类型**: `class`
 
 **头文件**: `XCEditor/Foundation/UIEditorCommandDispatcher.h`
 
-**描述**: 定义 `XCEditor/Foundation` 子目录中的 `UIEditorCommandDispatcher` public API。
+**描述**: editor 命令执行入口，负责把 `commandId` 解析为 workspace command 或 host command，并执行 preview / dispatch。
 
-## 概述
+## 概览
 
-`UIEditorCommandDispatcher.h` 是 `XCEditor/Foundation` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`UIEditorCommandDispatcher` 位于命令描述层和 shell 工作区控制器之间。它当前做两步：
 
-## 声明概览
+1. `Evaluate(...)`
+   - 校验注册表，查找 `commandId`，把 `ActivePanel` / `FixedPanelId` 等静态描述解析成当前可执行的具体命令。
+2. `Dispatch(...)`
+   - 在 `Evaluate(...)` 成功后，把 workspace 命令交给 `UIEditorWorkspaceController`，或者把 host 命令交给 `UIEditorHostCommandHandler`。
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `UIEditorHostCommandEvaluationResult` | `struct` | 头文件中的公开声明。 |
-| `UIEditorHostCommandDispatchResult` | `struct` | 头文件中的公开声明。 |
-| `UIEditorHostCommandHandler` | `class` | 头文件中的公开声明。 |
-| `UIEditorCommandEvaluationCode` | `enum class` | 头文件中的公开声明。 |
-| `UIEditorCommandEvaluationResult` | `struct` | 头文件中的公开声明。 |
-| `UIEditorCommandDispatchStatus` | `enum class` | 头文件中的公开声明。 |
-| `UIEditorCommandDispatchResult` | `struct` | 头文件中的公开声明。 |
-| `UIEditorCommandDispatcher` | `class` | 头文件中的公开声明。 |
+这让 menu、shortcut 和 shell interaction 都可以共享同一套命令求值与分发逻辑。
 
-## 公共方法
+## 主要声明
 
-| 方法 | 描述 |
+| 声明 | 角色 |
 |------|------|
-| [UIEditorCommandDispatcher()](Constructor.md) | 构造对象。 |
-| [GetCommandRegistry](GetCommandRegistry.md) | 获取相关状态或对象。 |
-| [SetHostCommandHandler](SetHostCommandHandler.md) | 设置相关状态或配置。 |
-| [GetHostCommandHandler](GetHostCommandHandler.md) | 获取相关状态或对象。 |
-| [ValidateConfiguration](ValidateConfiguration.md) | 公开方法，详见头文件声明。 |
-| [Evaluate](Evaluate.md) | 公开方法，详见头文件声明。 |
-| [Dispatch](Dispatch.md) | 公开方法，详见头文件声明。 |
+| `UIEditorHostCommandHandler` | 宿主命令执行抽象，允许 shell 外部接管 host 命令。 |
+| `UIEditorCommandEvaluationCode` | 命令求值失败或成功的细分原因。 |
+| `UIEditorCommandEvaluationResult` | `Evaluate(...)` 的结果，包含解析出的 workspace command 与 preview 结果。 |
+| `UIEditorCommandDispatchStatus` | 最终 dispatch 状态。 |
+| `UIEditorCommandDispatchResult` | `Dispatch(...)` 的结果。 |
+| `UIEditorCommandDispatcher` | 命令求值与分发器本体。 |
+
+## 当前实现行为
+
+- `ValidateConfiguration()` 直接复用 `ValidateUIEditorCommandRegistry(...)`。
+- `Evaluate(...)` 当前会：
+  - 在注册表无效时返回 `InvalidCommandRegistry`
+  - 在命令不存在时返回 `UnknownCommandId`
+  - 对 `Host` 命令转发给 `UIEditorHostCommandHandler::EvaluateHostCommand(...)`
+  - 对 `Workspace` 命令解析 `panelSource`
+  - 在 `ActivePanel` 但当前 workspace 没有 active panel 时返回 `MissingActivePanel`
+  - 复制一份 controller 做 preview dispatch，用 `previewResult` 预测命令是否会被拒绝
+- `Dispatch(...)` 当前先调用 `Evaluate(...)`，只有可执行时才真正分发。
+- host 命令和 workspace 命令共享统一结果结构，但最终执行路径不同。
+
+## 测试与调用链
+
+- `tests/UI/Editor/unit/test_ui_editor_command_dispatcher.cpp`
+  - 当前覆盖 active panel 解析、缺少 active panel 的拒绝路径，以及 dispatch 后 workspace 状态变更。
+- `tests/UI/Editor/unit/test_ui_editor_shell_interaction.cpp`
+  - 当前通过 shell interaction 间接消费命令派发器。
+- `tests/UI/Editor/integration/shell/menu_bar_basic/main.cpp`
+  - 当前把命令派发器挂进 menu bar / context menu 的真实交互路径。
 
 ## 相关文档
 
-- [当前目录](../Foundation.md) - 返回 `Foundation` 平行目录
-- [API 总索引](../../../main.md) - 返回顶层索引
+- [Foundation](../Foundation.md)
+- [UIEditorCommandRegistry](../UIEditorCommandRegistry/UIEditorCommandRegistry.md)
+- [UIEditorShortcutManager](../UIEditorShortcutManager/UIEditorShortcutManager.md)
+- [UIEditorWorkspaceController](../../Shell/UIEditorWorkspaceController/UIEditorWorkspaceController.md)