docs(plan): add api doc restructure task board

docs/api/XCEngine/Components/VolumeRendererComponent/VolumeRendererComponent.md

@@ -0,0 +1,112 @@
+# VolumeRendererComponent
+
+**命名空间**: `XCEngine::Components`
+
+**类型**: `class`
+
+**头文件**: `XCEngine/Components/VolumeRendererComponent.h`
+
+**源文件**: `engine/src/Components/VolumeRendererComponent.cpp`
+
+**描述**: 体积渲染组件，负责把 `VolumeField`、体积材质和少量阴影标志绑定到 `GameObject` 上，并在序列化/反序列化与 deferred load 场景中保持资源身份恢复。
+
+## 角色概述
+
+`VolumeRendererComponent` 回答的问题是：
+
+- 这个对象是否要作为体积参与渲染？
+- 它绑定的是哪一个 `VolumeField`？
+- 它使用哪一个 `Material`？
+- 体积对象当前的阴影开关是什么？
+
+和 [MeshRendererComponent](../MeshRendererComponent/MeshRendererComponent.md) 类似，它同时承担“运行时资源句柄”和“可持久化资源身份”两层职责。
+
+## 当前状态模型
+
+当前实现维护两组几乎对称的资源状态：
+
+| 状态 | 作用 |
+|------|------|
+| `m_volumeField` / `m_volumeFieldPath` / `m_volumeFieldRef` | 体积资源句柄、路径缓存与稳定 `AssetRef`。 |
+| `m_material` / `m_materialPath` / `m_materialRef` | 材质句柄、路径缓存与稳定 `AssetRef`。 |
+| `m_pendingVolumeLoad` / `m_pendingMaterialLoad` | deferred async load 的挂起结果。 |
+| `m_asyncVolumeLoadRequested` / `m_asyncMaterialLoadRequested` | 防止重复发起异步加载。 |
+| `m_castShadows` / `m_receiveShadows` | 阴影相关附加开关。 |
+
+## 绑定与恢复流程
+
+### 1. 运行时按路径设置
+
+- `SetVolumeFieldPath(...)` 会立即尝试 `ResourceManager::Load<VolumeField>(path)`。
+- `SetMaterialPath(...)` 会立即尝试 `ResourceManager::Load<Material>(path)`。
+- 两条路径都会额外调用 `TryGetAssetRef(...)`，尽量把项目路径回填成稳定资源身份。
+
+### 2. 运行时按句柄设置
+
+- `SetVolumeField(...)` 与 `SetMaterial(...)` 会从句柄反推出路径。
+- 若路径对应项目资产，也会同步尝试回填 `AssetRef`。
+
+### 3. 序列化与反序列化
+
+`Serialize()` 当前优先写：
+
+- `volumeRef`
+- `materialRef`
+
+只有在没有有效 `AssetRef` 且路径带 virtual scheme 时，才会保留：
+
+- `volumePath`
+- `materialPath`
+
+`Deserialize()` 当前会先清空旧状态，再恢复：
+
+- 体积资源身份
+- 材质资源身份
+- `castShadows`
+- `receiveShadows`
+
+若开启 deferred scene load，则会优先只恢复路径/身份，等首次访问句柄时再启动异步兑现。
+
+## 与 deferred scene load 的关系
+
+- `GetVolumeField()` / `GetVolumeFieldHandle()` 会触发：
+  - `EnsureDeferredAsyncVolumeLoadStarted()`
+  - `ResolvePendingVolumeField()`
+- `GetMaterial()` / `GetMaterialHandle()` 会触发：
+  - `EnsureDeferredAsyncMaterialLoadStarted()`
+  - `ResolvePendingMaterial()`
+
+因此这几个 getter 不是纯只读访问器，而是带有“补发异步兑现”的副作用。
+
+## 与渲染链路的关系
+
+- `RenderSceneUtility` 当前会从对象上提取 `VolumeRendererComponent`，并构造 [VisibleVolumeItem](../../Rendering/FrameData/VisibleVolumeItem/VisibleVolumeItem.md)。
+- 后续 [BuiltinVolumetricPass](../../Rendering/Passes/BuiltinVolumetricPass/BuiltinVolumetricPass.md) 会消费这些可见体积项。
+- 这意味着“组件存在”不等于“这一帧一定有可绘制体积”：
+  - 体积资源可能尚未兑现
+  - 材质可能为空
+  - deferred load 可能仍在挂起
+
+## 测试与锚点
+
+- `tests/Components/test_volume_renderer_component.cpp`
+  - `SetResourcesCachesHandlesPathsAndFlags`
+  - `SerializeAndDeserializePreservesVirtualPathsAndFlags`
+  - `DeferredSceneDeserializeLoadsVolumeFieldAsyncByPath`
+- `tests/Rendering/unit/test_render_scene_extractor.cpp`
+  - 覆盖体积对象被提取进渲染场景数据
+- `engine/src/Components/ComponentFactoryRegistry.cpp`
+  - 当前把 `"VolumeRenderer"` 注册为内建组件类型
+
+## 当前实现边界
+
+- 正式持久化协议优先是 `AssetRef`，不是普通项目路径。
+- 只有 virtual scheme 路径才会在没有有效 `AssetRef` 时稳定保留。
+- 当前组件只维护一个体积资源和一个材质，不涉及更复杂的多体积槽位模型。
+
+## 相关文档
+
+- [当前模块](../Components.md)
+- [VolumeField](../../Resources/Volume/VolumeField/VolumeField.md)
+- [VisibleVolumeItem](../../Rendering/FrameData/VisibleVolumeItem/VisibleVolumeItem.md)
+- [BuiltinVolumetricPass](../../Rendering/Passes/BuiltinVolumetricPass/BuiltinVolumetricPass.md)