docs: 重构 API 文档结构并修正源码准确性

- 重组文档目录结构: 每个模块的概述页移动到模块子目录
- 重命名 index.md 为 main.md
- 修正所有模块文档中的错误:
  - math: FromEuler→FromEulerAngles, TransformDirection 包含缩放, Box 是 OBB, Color::ToRGBA 格式
  - containers: 新增 operator==/!= 文档, 补充 std::hash DJB 算法细节
  - core: 修复 types 链接错误
  - debug: LogLevelToString 返回大写, timestamp 是秒, Profiler 空实现标注, Windows API vs ANSI
  - memory: 修复头文件路径, malloc vs operator new, 新增方法文档
  - resources: 修复 Shader/Texture 链接错误
  - threading: TaskSystem::Wait 空实现标注, ReadWriteLock 重入描述, LambdaTask 链接
- 验证: fix_links.py 确认 0 个断裂引用

docs/api/rhi/d3d12/buffer/buffer.md

@@ -0,0 +1,33 @@
+# D3D12Buffer
+
+**命名空间**: `XCEngine::RHI`
+
+**描述**: DirectX 12 缓冲区的 D3D12 实现，继承自 `RHIBuffer`。
+
+## 方法列表
+
+| 方法 | 文档 |
+|------|------|
+| `Initialize` | [详细文档](initialize.md) |
+| `InitializeFromExisting` | [详细文档](initialize-from-existing.md) |
+| `InitializeWithData` | [详细文档](initialize-with-data.md) |
+| `Shutdown` | [详细文档](shutdown.md) |
+| `UpdateData` | [详细文档](update-data.md) |
+| `Map` | [详细文档](map.md) |
+| `Unmap` | [详细文档](unmap.md) |
+| `SetData` | [详细文档](set-data.md) |
+| `GetResource` | [详细文档](get-resource.md) |
+| `GetDesc` | [详细文档](get-desc.md) |
+| `GetGPUVirtualAddress` | [详细文档](get-gpu-virtual-address.md) |
+| `GetGPUAddress` | [详细文档](get-gpu-address.md) |
+| `GetSize` | [详细文档](get-size.md) |
+| `GetState` / `SetState` | [详细文档](get-state.md) |
+| `GetName` / `SetName` | [详细文档](get-name.md) |
+| `GetStride` / `SetStride` | [详细文档](get-stride.md) |
+| `GetBufferType` / `SetBufferType` | [详细文档](get-buffer-type.md) |
+| `GetNativeHandle` | [详细文档](get-native-handle.md) |
+
+## 相关文档
+
+- [D3D12 后端总览](../overview.md)
+- [RHIBuffer](../../buffer/buffer.md) - 抽象缓冲区接口

docs/api/rhi/d3d12/buffer/get-buffer-type.md

@@ -0,0 +1,16 @@
+# D3D12Buffer::GetBufferType / SetBufferType
+
+## 函数签名
+
+```cpp
+BufferType GetBufferType() const override
+void SetBufferType(BufferType type) override
+```
+
+## 中文描述
+
+获取和设置缓冲区类型（Vertex / Index / Constant 等）。
+
+## 复杂度
+
+O(1)

docs/api/rhi/d3d12/buffer/get-desc.md

@@ -0,0 +1,19 @@
+# D3D12Buffer::GetDesc
+
+## 函数签名
+
+```cpp
+D3D12_RESOURCE_DESC GetDesc() const
+```
+
+## 中文描述
+
+获取 D3D12 资源描述结构。
+
+## 返回值
+
+`D3D12_RESOURCE_DESC` - 资源描述
+
+## 复杂度
+
+O(1)

docs/api/rhi/d3d12/buffer/get-gpu-address.md

@@ -0,0 +1,19 @@
+# D3D12Buffer::GetGPUAddress
+
+## 函数签名
+
+```cpp
+uint64_t GetGPUAddress() const
+```
+
+## 中文描述
+
+获取 GPU 地址（等同于 `GetGPUVirtualAddress`）。
+
+## 返回值
+
+`uint64_t` - GPU 地址
+
+## 复杂度
+
+O(1)

docs/api/rhi/d3d12/buffer/get-gpu-virtual-address.md

@@ -0,0 +1,19 @@
+# D3D12Buffer::GetGPUVirtualAddress
+
+## 函数签名
+
+```cpp
+D3D12_GPU_VIRTUAL_ADDRESS GetGPUVirtualAddress() const
+```
+
+## 中文描述
+
+获取 GPU 虚拟地址，用于根签名绑定。
+
+## 返回值
+
+`D3D12_GPU_VIRTUAL_ADDRESS` - GPU 虚拟地址
+
+## 复杂度
+
+O(1)

docs/api/rhi/d3d12/buffer/get-name.md

@@ -0,0 +1,16 @@
+# D3D12Buffer::GetName / SetName
+
+## 函数签名
+
+```cpp
+const std::string& GetName() const override
+void SetName(const std::string& name) override
+```
+
+## 中文描述
+
+获取和设置对象名称（用于调试）。
+
+## 复杂度
+
+O(1)

docs/api/rhi/d3d12/buffer/get-native-handle.md

@@ -0,0 +1,19 @@
+# D3D12Buffer::GetNativeHandle
+
+## 函数签名
+
+```cpp
+void* GetNativeHandle() override
+```
+
+## 中文描述
+
+返回原生句柄，即 `ID3D12Resource*`。
+
+## 返回值
+
+`void*` - 原生句柄
+
+## 复杂度
+
+O(1)

docs/api/rhi/d3d12/buffer/get-resource.md

@@ -0,0 +1,19 @@
+# D3D12Buffer::GetResource
+
+## 函数签名
+
+```cpp
+ID3D12Resource* GetResource() const
+```
+
+## 中文描述
+
+获取底层 `ID3D12Resource` 指针。
+
+## 返回值
+
+`ID3D12Resource*` - D3D12 资源指针
+
+## 复杂度
+
+O(1)

docs/api/rhi/d3d12/buffer/get-size.md

@@ -0,0 +1,19 @@
+# D3D12Buffer::GetSize
+
+## 函数签名
+
+```cpp
+uint64_t GetSize() const override
+```
+
+## 中文描述
+
+获取缓冲区大小（字节）。
+
+## 返回值
+
+`uint64_t` - 缓冲区大小
+
+## 复杂度
+
+O(1)

docs/api/rhi/d3d12/buffer/get-state.md

@@ -0,0 +1,16 @@
+# D3D12Buffer::GetState / SetState
+
+## 函数签名
+
+```cpp
+ResourceStates GetState() const
+void SetState(ResourceStates state)
+```
+
+## 中文描述
+
+获取和设置当前资源状态。用于状态跟踪和屏障生成。
+
+## 复杂度
+
+O(1)

docs/api/rhi/d3d12/buffer/get-stride.md

@@ -0,0 +1,16 @@
+# D3D12Buffer::GetStride / SetStride
+
+## 函数签名
+
+```cpp
+uint32_t GetStride() const override
+void SetStride(uint32_t stride) override
+```
+
+## 中文描述
+
+获取和设置顶点缓冲区步长（字节）。
+
+## 复杂度
+
+O(1)

docs/api/rhi/d3d12/buffer/initialize-from-existing.md

@@ -0,0 +1,35 @@
+# D3D12Buffer::InitializeFromExisting
+
+## 函数签名
+
+```cpp
+bool InitializeFromExisting(ID3D12Resource* resource)
+```
+
+## 中文描述
+
+从已存在的 D3D12 资源对象初始化缓冲区包装类，不分配新资源。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `resource` | `ID3D12Resource*` | 已存在的 D3D12 资源指针 |
+
+## 返回值
+
+`bool` - 初始化是否成功
+
+## 复杂度
+
+O(1)
+
+## 示例
+
+```cpp
+ComPtr<ID3D12Resource> existingResource;
+device->CreateReservedResource(&desc, state, nullptr, IID_PPV_ARGS(&existingResource));
+
+D3D12Buffer buffer;
+buffer.InitializeFromExisting(existingResource.Get());
+```

docs/api/rhi/d3d12/buffer/initialize-with-data.md

@@ -0,0 +1,42 @@
+# D3D12Buffer::InitializeWithData
+
+## 函数签名
+
+```cpp
+bool InitializeWithData(ID3D12Device* device, ID3D12GraphicsCommandList* commandList, const void* data, uint64_t size, D3D12_RESOURCE_STATES finalState)
+```
+
+## 中文描述
+
+创建缓冲区并通过命令列表从内存数据初始化内容。内部会自动创建上传堆、复制数据、转换状态。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `device` | `ID3D12Device*` | D3D12 设备指针 |
+| `commandList` | `ID3D12GraphicsCommandList*` | 命令列表（用于复制操作） |
+| `data` | `const void*` | 初始数据指针 |
+| `size` | `uint64_t` | 数据大小（字节） |
+| `finalState` | `D3D12_RESOURCE_STATES` | 数据复制完成后的目标状态 |
+
+## 返回值
+
+`bool` - 初始化是否成功
+
+## 复杂度
+
+O(n) - 取决于数据大小，内部创建临时上传堆
+
+## 示例
+
+```cpp
+uint16_t indices[] = { 0, 1, 2, 1, 3, 2 };
+D3D12Buffer indexBuffer;
+D3D12Buffer::InitializeWithData(
+    device->GetDevice(),
+    cmdList->GetCommandList(),
+    indices,
+    sizeof(indices),
+    D3D12_RESOURCE_STATE_INDEX_BUFFER);
+```

docs/api/rhi/d3d12/buffer/initialize.md

@@ -0,0 +1,39 @@
+# D3D12Buffer::Initialize
+
+## 函数签名
+
+```cpp
+bool Initialize(ID3D12Device* device, uint64_t size, D3D12_RESOURCE_STATES initialState = D3D12_RESOURCE_STATE_COMMON, D3D12_HEAP_TYPE heapType = D3D12_HEAP_TYPE_DEFAULT)
+```
+
+## 中文描述
+
+创建新缓冲区，分配 D3D12 显存资源。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `device` | `ID3D12Device*` | D3D12 设备指针 |
+| `size` | `uint64_t` | 缓冲区大小（字节） |
+| `initialState` | `D3D12_RESOURCE_STATES` | 初始资源状态（默认 COMMON） |
+| `heapType` | `D3D12_HEAP_TYPE` | 堆类型：DEFAULT（默认）、UPLOAD（上传）、READBACK（回读） |
+
+## 返回值
+
+`bool` - 初始化是否成功
+
+## 复杂度
+
+O(n) - 取决于缓冲区大小
+
+## 示例
+
+```cpp
+D3D12Buffer vertexBuffer;
+vertexBuffer.Initialize(
+    device->GetDevice(),
+    sizeof(Vertex) * vertexCount,
+    D3D12_RESOURCE_STATE_VERTEX_AND_CONSTANT_BUFFER,
+    D3D12_HEAP_TYPE_DEFAULT);
+```

docs/api/rhi/d3d12/buffer/map.md

@@ -0,0 +1,27 @@
+# D3D12Buffer::Map
+
+## 函数签名
+
+```cpp
+void* Map() override
+```
+
+## 中文描述
+
+将缓冲区内存映射到 CPU 可访问地址。仅对 UPLOAD 或 READBACK 堆有效。
+
+## 返回值
+
+`void*` - 映射的内存指针
+
+## 复杂度
+
+O(1)
+
+## 示例
+
+```cpp
+void* mapped = uploadBuffer.Map();
+memcpy(mapped, vertexData, sizeof(vertexData));
+buffer.Unmap();
+```

docs/api/rhi/d3d12/buffer/set-data.md

@@ -0,0 +1,23 @@
+# D3D12Buffer::SetData
+
+## 函数签名
+
+```cpp
+void SetData(const void* data, size_t size, size_t offset = 0) override
+```
+
+## 中文描述
+
+设置缓冲区数据。通过 Map/Unmap 实现。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `data` | `const void*` | 数据指针 |
+| `size` | `size_t` | 数据大小 |
+| `offset` | `size_t` | 缓冲区内的偏移量 |
+
+## 复杂度
+
+O(n)

docs/api/rhi/d3d12/buffer/shutdown.md

@@ -0,0 +1,15 @@
+# D3D12Buffer::Shutdown
+
+## 函数签名
+
+```cpp
+void Shutdown() override
+```
+
+## 中文描述
+
+释放 D3D12 缓冲区资源，将成员变量置为空。
+
+## 复杂度
+
+O(1)

docs/api/rhi/d3d12/buffer/unmap.md

@@ -0,0 +1,15 @@
+# D3D12Buffer::Unmap
+
+## 函数签名
+
+```cpp
+void Unmap() override
+```
+
+## 中文描述
+
+解除缓冲区内存映射。
+
+## 复杂度
+
+O(1)

docs/api/rhi/d3d12/buffer/update-data.md

@@ -0,0 +1,28 @@
+# D3D12Buffer::UpdateData
+
+## 函数签名
+
+```cpp
+void UpdateData(const void* data, uint64_t size)
+```
+
+## 中文描述
+
+更新缓冲区数据。要求缓冲区使用 UPLOAD 堆类型，否则行为未定义。
+
+## 参数
+
+| 参数 | 类型 | 描述 |
+|------|------|------|
+| `data` | `const void*` | 新数据指针 |
+| `size` | `uint64_t` | 数据大小 |
+
+## 复杂度
+
+O(n)
+
+## 示例
+
+```cpp
+uploadBuffer.UpdateData(newData, dataSize);
+```