docs: expand selection manager API docs

docs/api/XCEngine/Editor/Core/ISelectionManager/ISelectionManager.md

@@ -19,15 +19,13 @@
 
 ## 核心接口
 
-| 方法 | 作用 |
-|------|------|
-| `SetSelectedEntity()` | 设置单选对象。 |
-| `SetSelectedEntities()` | 设置多选集合。 |
-| `AddToSelection()` / `RemoveFromSelection()` | 增删选择。 |
-| `ClearSelection()` | 清空选择。 |
-| `GetSelectedEntity()` / `GetSelectedEntities()` | 查询当前选择。 |
-| `HasSelection()` / `GetSelectionCount()` | 查询选择状态。 |
-| `IsSelected()` | 判断某实体是否已选中。 |
+### 写操作
+
+- [Selection Mutations](Selection-Mutations.md)
+
+### 读操作
+
+- [Selection Queries](Selection-Queries.md)
 
 ## 相关文档
 

docs/api/XCEngine/Editor/Core/ISelectionManager/Selection-Mutations.md

@@ -0,0 +1,45 @@
+# ISelectionManager Selection Mutations
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `interface methods`
+
+**源文件**: `editor/src/Core/ISelectionManager.h`
+
+## 签名
+
+```cpp
+virtual void SetSelectedEntity(uint64_t entityId) = 0;
+virtual void SetSelectedEntities(const std::vector<uint64_t>& entityIds) = 0;
+virtual void AddToSelection(uint64_t entityId) = 0;
+virtual void RemoveFromSelection(uint64_t entityId) = 0;
+virtual void ClearSelection() = 0;
+```
+
+## 作用
+
+定义编辑器当前选择集合的写操作接口。
+
+## 契约语义
+
+- `SetSelectedEntity(...)`
+  - 把当前选择替换成单个实体。
+- `SetSelectedEntities(...)`
+  - 用给定实体 id 列表整体替换当前多选集合。
+- `AddToSelection(...)`
+  - 把一个实体追加到当前选择。
+- `RemoveFromSelection(...)`
+  - 从当前选择中移除一个实体。
+- `ClearSelection()`
+  - 清空整个选择集合。
+
+## 设计含义
+
+- `ISelectionManager` 的职责不只是“保存一个当前对象”，而是管理完整的多选集合。
+- 上层面板、命令和事件系统都可以基于这组接口表达单选、多选、追加选择和清空选择。
+
+## 相关文档
+
+- [ISelectionManager](ISelectionManager.md)
+- [Selection Queries](Selection-Queries.md)
+- [SelectionManager](../SelectionManager/SelectionManager.md)

docs/api/XCEngine/Editor/Core/ISelectionManager/Selection-Queries.md

@@ -0,0 +1,46 @@
+# ISelectionManager Selection Queries
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `interface methods`
+
+**源文件**: `editor/src/Core/ISelectionManager.h`
+
+## 签名
+
+```cpp
+virtual uint64_t GetSelectedEntity() const = 0;
+virtual const std::vector<uint64_t>& GetSelectedEntities() const = 0;
+virtual bool HasSelection() const = 0;
+virtual size_t GetSelectionCount() const = 0;
+virtual bool IsSelected(uint64_t entityId) const = 0;
+```
+
+## 作用
+
+定义当前选择集合的只读查询接口。
+
+## 契约语义
+
+- `GetSelectedEntity()`
+  - 返回当前主选中实体。
+- `GetSelectedEntities()`
+  - 返回当前完整选择集合。
+- `HasSelection()`
+  - 查询当前是否存在任何选中项。
+- `GetSelectionCount()`
+  - 查询当前选择数量。
+- `IsSelected(...)`
+  - 查询某实体是否位于当前选择集中。
+
+## 设计含义
+
+- 接口当前同时暴露“主选择”和“完整多选集合”，以支持:
+  - Inspector 只看主对象
+  - Scene View gizmo 和批量操作消费完整集合
+
+## 相关文档
+
+- [ISelectionManager](ISelectionManager.md)
+- [Selection Mutations](Selection-Mutations.md)
+- [SelectionManager](../SelectionManager/SelectionManager.md)

docs/api/XCEngine/Editor/Core/SelectionManager/Constructor-And-EventBus.md

@@ -0,0 +1,29 @@
+# SelectionManager::SelectionManager
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `constructor`
+
+**源文件**: `editor/src/Core/SelectionManager.h`
+
+## 签名
+
+```cpp
+explicit SelectionManager(EventBus& eventBus);
+```
+
+## 作用
+
+构造一个基于实体 ID 的选择管理器，并绑定选择变化的事件发布出口。
+
+## 当前实现行为
+
+- 当前实现只把传入的 `EventBus` 保存到 `m_eventBus`。
+- 选择集合 `m_selectedEntities` 初始为空。
+- 后续所有选择变化都会通过这个 `EventBus` 发布 `SelectionChangedEvent`。
+
+## 相关文档
+
+- [SelectionManager](SelectionManager.md)
+- [Selection Mutations](Selection-Mutations.md)
+- [Selection Queries And Event Publishing](Selection-Queries-And-Event-Publishing.md)

docs/api/XCEngine/Editor/Core/SelectionManager/Selection-Mutations.md

@@ -0,0 +1,59 @@
+# SelectionManager Selection Mutations
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `method group`
+
+**源文件**: `editor/src/Core/SelectionManager.h`
+
+## 签名
+
+```cpp
+void SetSelectedEntity(uint64_t entityId) override;
+void SetSelectedEntities(const std::vector<uint64_t>& entityIds) override;
+void AddToSelection(uint64_t entityId) override;
+void RemoveFromSelection(uint64_t entityId) override;
+void ClearSelection() override;
+```
+
+## 作用
+
+实现当前选择集合的更新逻辑，并在每次变更后同步发布事件。
+
+## 当前实现行为
+
+### `SetSelectedEntity(...)`
+
+- 当当前选择为空时，直接把该实体 id 压入数组。
+- 否则会把数组第一个元素改成该 id，并把数组裁剪到只剩一个元素。
+- 最后调用 `PublishSelectionChanged()`。
+
+### `SetSelectedEntities(...)`
+
+- 直接用传入 id 列表覆盖 `m_selectedEntities`。
+- 然后调用 `PublishSelectionChanged()`。
+
+### `AddToSelection(...)`
+
+- 只有当 `entityId != 0` 且当前未选中该对象时才会追加。
+- 成功追加后调用 `PublishSelectionChanged()`。
+
+### `RemoveFromSelection(...)`
+
+- 若当前选择中存在该 id，则删除它并调用 `PublishSelectionChanged()`。
+
+### `ClearSelection()`
+
+- 只有当前选择非空时才会真正清空并发布事件。
+- 这避免了无变化情况下重复广播空选择。
+
+## 当前实现边界
+
+- 当前不会自动去重 `SetSelectedEntities(...)` 传入的重复 id。
+- 当前主选择语义由数组尾元素决定，而不是独立字段。
+
+## 相关文档
+
+- [SelectionManager](SelectionManager.md)
+- [Constructor](Constructor-And-EventBus.md)
+- [Selection Queries And Event Publishing](Selection-Queries-And-Event-Publishing.md)

docs/api/XCEngine/Editor/Core/SelectionManager/Selection-Queries-And-Event-Publishing.md

@@ -0,0 +1,55 @@
+# SelectionManager Selection Queries And Event Publishing
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `method group`
+
+**源文件**: `editor/src/Core/SelectionManager.h`
+
+## 签名
+
+```cpp
+uint64_t GetSelectedEntity() const override;
+const std::vector<uint64_t>& GetSelectedEntities() const override;
+bool HasSelection() const override;
+size_t GetSelectionCount() const override;
+bool IsSelected(uint64_t entityId) const override;
+```
+
+## 作用
+
+提供选择集合查询，并说明当前 `SelectionChangedEvent` 的真实发布载荷。
+
+## 当前实现行为
+
+### 查询接口
+
+- `GetSelectedEntity()`
+  - 当前选择为空时返回 `0`
+  - 否则返回数组最后一个元素
+- `GetSelectedEntities()`
+  - 返回内部 `std::vector<uint64_t>` 的 const 引用
+- `HasSelection()`
+  - 仅检查数组是否为空
+- `GetSelectionCount()`
+  - 返回数组长度
+- `IsSelected(...)`
+  - 通过线性查找判断是否选中
+
+### 事件发布语义
+
+- 内部 `PublishSelectionChanged()` 会构造 `SelectionChangedEvent`
+- `event.selectedObjects = m_selectedEntities`
+- `event.primarySelection = GetSelectedEntity()`
+- 然后通过 `m_eventBus.Publish(event)` 同步发布
+
+## 设计含义
+
+- 当前实现没有单独维护“主选择”字段，而是把数组最后一个元素当作主选择。
+- 这使查询接口和事件负载保持一致。
+
+## 相关文档
+
+- [SelectionManager](SelectionManager.md)
+- [Constructor](Constructor-And-EventBus.md)
+- [Selection Mutations](Selection-Mutations.md)

docs/api/XCEngine/Editor/Core/SelectionManager/SelectionManager.md

@@ -22,6 +22,20 @@
 - `GetSelectedEntity()` 返回当前列表最后一个元素。
 - 空实体 ID `0` 不会被 `AddToSelection()` 添加。
 
+## 公开 API
+
+### 生命周期
+
+- [Constructor](Constructor-And-EventBus.md)
+
+### 选择修改
+
+- [Selection Mutations](Selection-Mutations.md)
+
+### 选择查询与事件发布
+
+- [Selection Queries And Event Publishing](Selection-Queries-And-Event-Publishing.md)
+
 ## 当前实现边界
 
 - 当前没有选择历史。