docs: refactor Components API content

docs/api/XCEngine/Components/Component/Component.md

@@ -2,45 +2,101 @@
 
 **命名空间**: `XCEngine::Components`
 
-**类型**: `class (abstract)`
+**类型**: `class (abstract base)`
 
 **头文件**: `XCEngine/Components/Component.h`
 
-**描述**: 定义 `XCEngine/Components` 子目录中的 `Component` public API。
+**描述**: 所有挂载式组件的抽象基类，定义统一的生命周期钩子、归属对象访问和启用状态控制。
 
-## 概述
+## 角色概述
 
-`Component.h` 是 `XCEngine/Components` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`Component` 是 `GameObject` 组合模型里的最小行为单元。它本身不拥有场景对象，也不负责更新循环；真正的驱动者是 `GameObject` 和 `Scene`。`Component` 主要提供三类能力：
 
-## 声明概览
+- 生命周期钩子：`Awake`、`Start`、`Update`、`FixedUpdate`、`LateUpdate`、`OnEnable`、`OnDisable`、`OnDestroy`。
+- 归属关系访问：`GetGameObject()`、`transform()`、`GetScene()`。
+- 运行期开关：`IsEnabled()`、`SetEnabled()`。
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `Component` | `class` | 头文件中的公开声明。 |
+这和 Unity 的 `Component`/`Behaviour` 设计思路相近，但当前实现更轻：基类默认几乎全部是空实现，没有调度器、执行顺序系统或线程隔离层。
 
-## 公共方法
+## 生命周期
 
-| 方法 | 描述 |
-|------|------|
-| [~Component()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [Awake](Awake.md) | 公开方法，详见头文件声明。 |
-| [Start](Start.md) | 公开方法，详见头文件声明。 |
-| [Update](Update.md) | 更新运行时状态。 |
-| [FixedUpdate](FixedUpdate.md) | 公开方法，详见头文件声明。 |
-| [LateUpdate](LateUpdate.md) | 公开方法，详见头文件声明。 |
-| [OnEnable](OnEnable.md) | 公开方法，详见头文件声明。 |
-| [OnDisable](OnDisable.md) | 公开方法，详见头文件声明。 |
-| [OnDestroy](OnDestroy.md) | 公开方法，详见头文件声明。 |
-| [GetName](GetName.md) | 获取相关状态或对象。 |
-| [Serialize](Serialize.md) | 公开方法，详见头文件声明。 |
-| [Deserialize](Deserialize.md) | 公开方法，详见头文件声明。 |
-| [GetGameObject](GetGameObject.md) | 获取相关状态或对象。 |
-| [transform](transform.md) | 公开方法，详见头文件声明。 |
-| [GetScene](GetScene.md) | 获取相关状态或对象。 |
-| [IsEnabled](IsEnabled.md) | 查询当前状态。 |
-| [SetEnabled](SetEnabled.md) | 设置相关状态或配置。 |
+`Component` 的生命周期由宿主 `GameObject` 驱动，而不是由组件自身驱动。
+
+- `Awake()`、`Start()`、`Update()`、`FixedUpdate()`、`LateUpdate()` 只有在 `GameObject`/`Scene` 主动调用时才会发生。
+- `SetEnabled()` 会根据“组件启用状态”和“对象是否在层级中激活”共同决定是否触发 `OnEnable()` 或 `OnDisable()`。
+- `OnDestroy()` 由 `GameObject::Destroy()` 或 `Scene::DestroyGameObject()` 路径触发；基类析构函数本身不补发销毁回调。
+
+按当前实现，直接对一个已经运行中的 `GameObject` 调用 `AddComponent<T>()`，不会自动调用新组件的 `Awake()`、`Start()` 或 `OnEnable()`。如果你的运行时逻辑依赖这些阶段，需要明确安排调用时机。
+
+## 所有权与归属
+
+- `Component` 不直接暴露 public 构造 ownership；实例通常由 `GameObject` 持有在 `std::unique_ptr<Component>` 容器中。
+- `m_gameObject` 由 `GameObject::AddComponent<T>()` 在挂接时回填。
+- `GetGameObject()` 仅返回裸指针，不转移所有权。
+- `GetScene()` 只是经由宿主对象转发访问场景。
+
+`transform()` 的前提条件比 `GetScene()` 更严格。当前实现直接解引用 `m_gameObject->GetTransform()`，没有空指针保护，因此它只适用于“已经成功挂到某个 `GameObject` 上”的组件。
+
+## 启用状态语义
+
+`SetEnabled(bool)` 的有效状态不是单纯的 `m_enabled`，而是：
+
+`component enabled && gameObject active in hierarchy`
+
+这意味着：
+
+- 对挂在非激活对象上的组件执行 `SetEnabled(true)`，不会立刻触发 `OnEnable()`。
+- 当对象重新进入激活层级时，`GameObject` 会补发 `OnEnable()`。
+- 如果启用状态前后“有效可用性”没有变化，`SetEnabled()` 会直接返回，不重复触发回调。
+
+这套行为已被 `tests/Components/test_component.cpp` 覆盖验证。
+
+## 序列化语义
+
+- 基类 `Serialize(std::ostream&)` 默认是 no-op。
+- 基类 `Deserialize(std::istream&)` 默认是 no-op。
+
+因此，组件是否能被场景保存/加载，完全取决于具体子类是否覆写这两个函数。文档阅读时不要默认所有组件都可持久化。
+
+## 线程语义
+
+- 当前实现没有内部加锁。
+- 文档和源码都没有提供跨线程读写同一组件实例的安全保证。
+- 按当前调用关系，生命周期和大多数组件访问应默认视为主线程/场景线程语义。
+
+对音频类组件来说，虽然会与 `AudioSystem` 交互，但这不代表 `Component` 基类本身具备线程同步能力。
+
+## 当前实现限制
+
+- `transform()` 对未附着组件是未定义用法，因为实现里没有 null check。
+- 基类不区分“已构造”“已挂接”“已进入场景”“已启动”等更细粒度状态。
+- 没有统一的反射、属性枚举或编辑器元数据系统；文档页只能按实际 public API 解释。
+
+## 相关方法
+
+- [Awake](Awake.md)
+- [Start](Start.md)
+- [Update](Update.md)
+- [FixedUpdate](FixedUpdate.md)
+- [LateUpdate](LateUpdate.md)
+- [OnEnable](OnEnable.md)
+- [OnDisable](OnDisable.md)
+- [OnDestroy](OnDestroy.md)
+- [GetGameObject](GetGameObject.md)
+- [transform](transform.md)
+- [GetScene](GetScene.md)
+- [IsEnabled](IsEnabled.md)
+- [SetEnabled](SetEnabled.md)
+- [Serialize](Serialize.md)
+- [Deserialize](Deserialize.md)
+
+## 相关指南
+
+- [GameObject-Component Lifecycle And Serialization](../../../_guides/Components/GameObject-Component-Lifecycle-And-Serialization.md)
 
 ## 相关文档
 
-- [当前目录](../Components.md) - 返回 `Components` 平行目录
-- [API 总索引](../../../main.md) - 返回顶层索引
+- [当前模块](../Components.md)
+- [GameObject](../GameObject/GameObject.md)
+- [TransformComponent](../TransformComponent/TransformComponent.md)
+- [API 总索引](../../../main.md)