docs(xceditor): deepen foundation api pages

docs/api/XCEditor/Foundation/UIEditorCommandRegistry/UIEditorCommandRegistry.md

@@ -1,36 +1,59 @@
 # UIEditorCommandRegistry
 
-**命名空间**: `XCEngine`
+**命名空间**: `XCEngine::UI::Editor`
 
-**类型**: `struct`
+**类型**: `enums + structs + functions`
 
 **头文件**: `XCEditor/Foundation/UIEditorCommandRegistry.h`
 
-**描述**: 定义 `XCEditor/Foundation` 子目录中的 `UIEditorCommandRegistry` public API。
+**描述**: editor 命令描述协议与注册表校验入口，负责定义 workspace/host 命令的静态声明格式。
 
-## 概述
+## 概览
 
-`UIEditorCommandRegistry.h` 是 `XCEditor/Foundation` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`UIEditorCommandRegistry.h` 是 `XCEditor` 命令系统的静态描述层。它不执行命令，而是先回答这些问题：
 
-## 声明概览
+- 一个 editor 命令的 `commandId`、`displayName` 和命令种类是什么。
+- 这个命令对应的是 workspace command 还是 host command。
+- 如果是 workspace command，它的 panel 路由来自固定 panel、当前 active panel，还是根本不需要 panel。
+- 当前整张命令表是否合法，是否存在重复 id、空 displayName 或错误的 panel source 组合。
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `UIEditorCommandKind` | `enum class` | 头文件中的公开声明。 |
-| `UIEditorCommandPanelSource` | `enum class` | 头文件中的公开声明。 |
-| `UIEditorWorkspaceCommandDescriptor` | `struct` | 头文件中的公开声明。 |
-| `UIEditorCommandDescriptor` | `struct` | 头文件中的公开声明。 |
-| `UIEditorCommandRegistry` | `struct` | 头文件中的公开声明。 |
-| `UIEditorCommandRegistryValidationCode` | `enum class` | 头文件中的公开声明。 |
-| `UIEditorCommandRegistryValidationResult` | `struct` | 头文件中的公开声明。 |
+## 主要声明
 
-## 结构体成员
+| 声明 | 角色 |
+|------|------|
+| `UIEditorCommandKind` | 区分 `Workspace` 与 `Host` 命令。 |
+| `UIEditorCommandPanelSource` | 描述 panel 路由来自 `None / FixedPanelId / ActivePanel`。 |
+| `UIEditorWorkspaceCommandDescriptor` | 把高层命令映射到 `UIEditorWorkspaceCommandKind + panel routing`。 |
+| `UIEditorCommandDescriptor` | 单个 editor 命令的完整静态描述。 |
+| `UIEditorCommandRegistry` | 命令描述表。 |
+| `UIEditorCommandRegistryValidationCode` | 注册表校验失败原因。 |
+| `FindUIEditorCommandDescriptor(...)` | 通过 `commandId` 查找描述。 |
+| `ValidateUIEditorCommandRegistry(...)` | 校验命令表的完整性与路由合法性。 |
 
-| 成员 | 类型 | 描述 | 默认值 |
-|------|------|------|--------|
-| `commands` | `std::vector<UIEditorCommandDescriptor>` | 结构体公开字段。 | `{}` |
+## 当前实现行为
+
+- `ValidateUIEditorCommandRegistry(...)` 会拒绝：
+  - 空 `commandId`
+  - 空 `displayName`
+  - 重复 `commandId`
+  - host 命令错误携带 workspace panel routing
+  - 需要 panel 的 workspace 命令却没有 panel source
+  - 不需要 panel 的命令却错误携带 `FixedPanelId` / `ActivePanel`
+- `FindUIEditorCommandDescriptor(...)` 当前按线性遍历 `registry.commands` 查找。
+- `CommandKindRequiresPanelId(...)` 当前把 `OpenPanel / ClosePanel / ShowPanel / HidePanel / ActivatePanel` 视为需要 panel 路由；`ResetWorkspace` 不需要。
+
+## 测试与调用链
+
+- `tests/UI/Editor/unit/test_ui_editor_command_registry.cpp`
+  - 当前覆盖 descriptor 查找、重复 id、空 displayName 和 panel source 校验。
+- `new_editor/src/Foundation/UIEditorCommandDispatcher.cpp`
+  - 直接依赖这份注册表做命令解析和配置校验。
+- `new_editor/src/Shell/UIEditorMenuModel.cpp`
+  - 当前用它决定 menu item 的 command 元数据与启用态来源。
 
 ## 相关文档
 
-- [当前目录](../Foundation.md) - 返回 `Foundation` 平行目录
-- [API 总索引](../../../main.md) - 返回顶层索引
+- [Foundation](../Foundation.md)
+- [UIEditorCommandDispatcher](../UIEditorCommandDispatcher/UIEditorCommandDispatcher.md)
+- [UIEditorShortcutManager](../UIEditorShortcutManager/UIEditorShortcutManager.md)
+- [UIEditorWorkspaceController](../../Shell/UIEditorWorkspaceController/UIEditorWorkspaceController.md)