docs: rebuild Scene API content

docs/api/XCEngine/Scene/Scene.md

@@ -1,21 +1,50 @@
 # Scene
 
-**命名空间**: `XCEngine::Scene`
+**命名空间**: `XCEngine::Components`
 
 **类型**: `module`
 
-**描述**: 场景与场景管理器 API。
+**描述**: 提供场景容器 `Scene` 与多场景入口 `SceneManager`，负责组织 `GameObject` 层级、场景级更新与自定义文本序列化。
 
-## 概览
+## 概述
 
-该目录与 `XCEngine/Scene` 对应的 public headers 保持平行，用于承载唯一的 canonical API 文档入口。
+`XCEngine/Scene` 这组头文件位于 `Scene` 目录下，但公开类型实际放在 `XCEngine::Components` 命名空间中。这反映了当前引擎的建模方式：
+
+- `Scene` 负责持有一组 `GameObject`。
+- `GameObject` 负责父子层级、`TransformComponent` 和其它组件。
+- `SceneManager` 负责持有多个已加载场景，并暴露“当前活动场景”入口。
+
+这和商业引擎里常见的 Unity 风格思路接近：场景是对象集合与生命周期边界，真正可组合的行为仍然落在对象与组件层。
+
+## 当前实现成熟度
+
+这一组 API 已经能支撑基础场景树、更新和保存/加载，但需要对当前边界保持诚实：
+
+- `Scene::IsActive()` / `SetActive()` 当前只是存储一个标志位，不会阻止 `Update()`、`FixedUpdate()` 或 `LateUpdate()` 运行。
+- `FindGameObjectWithTag()` 当前并没有真正的 tag 系统支持，实际按对象名称匹配。
+- `Scene::~Scene()` 不会逐个调用 `DestroyGameObject()`，因此不会触发场景销毁事件，也不会为组件调用 `OnDestroy()`。
+- `SceneManager::LoadSceneAsync()` 当前不是异步加载，只是同步包装。
+- `SceneManager` 的活动场景指针，与 `Scene` 自身的 active 标志当前是两套彼此独立的状态。
+
+## 设计要点
+
+- `Scene` 采用“所有权集中、访问返回裸指针”的模式：内部由 `std::unique_ptr<GameObject>` 持有对象，API 对外返回非拥有指针。
+- 根对象列表与父子层级分开维护，这让“遍历根对象”和“对象挂接到父节点”可以各自保持简单。
+- 序列化走的是引擎私有文本格式，而不是通用 JSON。这样实现成本低、易于直接落地组件自定义序列化，但兼容性和健壮性也相对有限。
 
 ## 头文件
 
-- [Scene](Scene/Scene.md) - `Scene.h`
-- [SceneManager](SceneManager/SceneManager.md) - `SceneManager.h`
+- [Scene](Scene/Scene.md) - `Scene.h`，单个场景容器、更新入口和序列化接口。
+- [SceneManager](SceneManager/SceneManager.md) - `SceneManager.h`，多场景注册表与活动场景入口。
+
+## 相关指南
+
+- [Scene Lifecycle And Serialization](../../_guides/Scene/Scene-Lifecycle-And-Serialization.md) - 解释场景树为什么这样设计、活动状态分层意味着什么，以及当前序列化链路的实际限制。
 
 ## 相关文档
 
+- [GameObject](../Components/GameObject/GameObject.md)
+- [Component](../Components/Component/Component.md)
+- [TransformComponent](../Components/TransformComponent/TransformComponent.md)
 - [上级目录](../XCEngine.md)
 - [API 总索引](../../main.md)