diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Constructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Constructor.md
index 65f0493d..e2bdad53 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Constructor.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Constructor.md
@@ -1,28 +1,23 @@
-# D3D12Buffer::D3D12Buffer()
-
-构造对象。
+# D3D12Buffer::D3D12Buffer
 
 ```cpp
 D3D12Buffer();
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+构造一个空的 D3D12 缓冲区对象。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Buffer object;
-}
-```
+- 构造函数本身没有显式逻辑。
+- 依赖类内默认值:
+  - `m_state = ResourceStates::Common`
+  - `m_name` 为空字符串
+  - `m_stride = 0`
+  - `m_bufferType = BufferType::Vertex`
 
 ## 相关文档
 
-- [返回类总览](D3D12Buffer.md)
-- [返回模块目录](../D3D12.md)
+- [Initialize](Initialize.md)
+- [D3D12Buffer](D3D12Buffer.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/D3D12Buffer.md b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/D3D12Buffer.md
index f26408b5..6dc43240 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/D3D12Buffer.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/D3D12Buffer.md
@@ -6,48 +6,77 @@
 
 **头文件**: `XCEngine/RHI/D3D12/D3D12Buffer.h`
 
-**描述**: 定义 `XCEngine/RHI/D3D12` 子目录中的 `D3D12Buffer` public API。
+**描述**: D3D12 后端的缓冲区资源封装，持有 `ID3D12Resource` 并附带引擎侧状态、步长、名称和缓冲类型元数据。
 
-## 概述
+## 概览
 
-`D3D12Buffer.h` 是 `XCEngine/RHI/D3D12` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`D3D12Buffer` 和 [D3D12Texture](../D3D12Texture/D3D12Texture.md) 属于同一层级的资源包装器: 它持有一个真实的 `ID3D12Resource`，同时保存 RHI 层需要的附加元数据。
 
-## 声明概览
+在当前实现里，这个类承担两类工作:
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `D3D12Buffer` | `class` | 继承自 `RHIBuffer` 的公开声明。 |
+- 创建或包装底层 D3D12 buffer resource
+- 为上层系统暴露 GPU 地址、步长、缓冲类型、映射接口和本地状态缓存
 
-## 公共方法
+## 设计定位
 
-| 方法 | 描述 |
-|------|------|
-| [D3D12Buffer()](Constructor.md) | 构造对象。 |
-| [~D3D12Buffer()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
-| [InitializeFromExisting](InitializeFromExisting.md) | 初始化内部状态。 |
-| [InitializeWithData](InitializeWithData.md) | 初始化内部状态。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [GetResource](GetResource.md) | 获取相关状态或对象。 |
-| [GetDesc](GetDesc.md) | 获取相关状态或对象。 |
-| [GetGPUVirtualAddress](GetGPUVirtualAddress.md) | 获取相关状态或对象。 |
-| [UpdateData](UpdateData.md) | 更新运行时状态。 |
-| [GetNativeHandle](GetNativeHandle.md) | 获取相关状态或对象。 |
-| [GetState](GetState.md) | 获取相关状态或对象。 |
-| [SetState](SetState.md) | 设置相关状态或配置。 |
-| [GetGPUAddress](GetGPUAddress.md) | 获取相关状态或对象。 |
-| [GetSize](GetSize.md) | 获取相关状态或对象。 |
-| [GetName](GetName.md) | 获取相关状态或对象。 |
-| [SetName](SetName.md) | 设置相关状态或配置。 |
-| [GetStride](GetStride.md) | 获取相关状态或对象。 |
-| [GetBufferType](GetBufferType.md) | 获取相关状态或对象。 |
-| [SetStride](SetStride.md) | 设置相关状态或配置。 |
-| [SetBufferType](SetBufferType.md) | 设置相关状态或配置。 |
-| [Map](Map.md) | 公开方法，详见头文件声明。 |
-| [Unmap](Unmap.md) | 公开方法，详见头文件声明。 |
-| [SetData](SetData.md) | 设置相关状态或配置。 |
+如果从商业引擎角度看，当前 `D3D12Buffer` 的实现更偏“简单可用”而不是“峰值性能路径”:
+
+- `D3D12Device::CreateBuffer()` 会把 constant / vertex / index buffer 都放到 `UPLOAD` heap
+- 这样 `SetData()` / `Map()` 使用起来简单
+- 代价是它不像经典的“upload staging -> default heap resident buffer”方案那样追求 GPU 访问效率
+
+这类设计在引擎早中期阶段很常见，但文档必须把这种取舍写明。
+
+## 生命周期
+
+- 构造后为空对象。
+- 可通过 [Initialize](Initialize.md)、[InitializeFromExisting](InitializeFromExisting.md)、[InitializeWithData](InitializeWithData.md) 获得底层资源。
+- [Shutdown](Shutdown.md) 只会 `Reset()` 掉 `m_resource`。
+- 析构时自动调用 `Shutdown()`。
+
+## 线程语义
+
+- 当前实现没有锁。
+- D3D12 资源引用本身可跨线程传递，但本地元数据接口和映射写入流程不应被当作并发安全 API。
+
+## 当前实现的真实行为
+
+- [Initialize](Initialize.md) 创建 committed buffer，但不会同步 `m_state`。
+- [InitializeFromExisting](InitializeFromExisting.md) 即使传入 `nullptr` 也返回 `true`。
+- [InitializeWithData](InitializeWithData.md) 会录制上传和 barrier，但不会更新 `m_state`。
+- [Shutdown](Shutdown.md) 只重置 `m_resource`，不会清空 `m_state`、`m_name`、`m_stride`、`m_bufferType`。
+- [GetDesc](GetDesc.md)、[GetGPUVirtualAddress](GetGPUVirtualAddress.md)、[GetGPUAddress](GetGPUAddress.md)、[GetSize](GetSize.md) 都会直接或间接解引用 `m_resource`，因此在资源为空时并不安全。
+
+## 为什么这样设计
+
+当前实现显然优先照顾了“让 RHI 层和测试先跑起来”的目标:
+
+- CPU 可写的 upload buffer 很容易和 `SetData()` 配合
+- `GetGPUVirtualAddress()` 又足够支持 CBV / VBV / IBV 视图创建
+
+对用户来说，关键理解是:
+
+- 这不是最终形态的高性能 D3D12 缓冲管理系统
+- 它更像一个对统一 RHI 友好的、相对直接的资源封装层
+
+## 当前限制
+
+- 多个 getter 在 `m_resource == nullptr` 时不安全。
+- 状态缓存依赖外部调用者维护。
+- `InitializeWithData()` 内部临时上传资源当前没有在函数尾部显式释放。
+- `SetName()` 只写本地字符串，不会把名称传给 D3D12 调试对象。
+
+## 关键方法
+
+- [Initialize](Initialize.md)
+- [InitializeWithData](InitializeWithData.md)
+- [Map](Map.md)
+- [SetData](SetData.md)
+- [GetGPUVirtualAddress](GetGPUVirtualAddress.md)
+- [Shutdown](Shutdown.md)
 
 ## 相关文档
 
-- [当前目录](../D3D12.md) - 返回 `D3D12` 平行目录
-- [API 总索引](../../../../main.md) - 返回顶层索引
+- [D3D12](../D3D12.md)
+- [D3D12Texture](../D3D12Texture/D3D12Texture.md)
+- [D3D12ResourceView](../D3D12ResourceView/D3D12ResourceView.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Destructor.md b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Destructor.md
index 00beab11..f7914cdf 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Destructor.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Destructor.md
@@ -1,29 +1,19 @@
-# D3D12Buffer::~D3D12Buffer()
-
-销毁对象并释放相关资源。
+# D3D12Buffer::~D3D12Buffer
 
 ```cpp
 ~D3D12Buffer() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+销毁对象并释放内部 `ID3D12Resource` 引用。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Buffer object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+- 析构函数内部调用 [Shutdown](Shutdown.md)。
+- 只重置 `m_resource`，不额外清理本地元数据。
 
 ## 相关文档
 
-- [返回类总览](D3D12Buffer.md)
-- [返回模块目录](../D3D12.md)
+- [Shutdown](Shutdown.md)
+- [GetState](GetState.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetBufferType.md b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetBufferType.md
index ef67ee16..eef0aa93 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetBufferType.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetBufferType.md
@@ -1,30 +1,20 @@
 # D3D12Buffer::GetBufferType
 
-获取相关状态或对象。
-
 ```cpp
 BufferType GetBufferType() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回该缓冲区记录的逻辑类型。
 
-**返回：** `BufferType` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Buffer object;
-    // 根据上下文补齐参数后调用 D3D12Buffer::GetBufferType(...)。
-    (void)object;
-}
-```
+- 直接返回缓存的 `m_bufferType`。
+- 构造默认值是 `BufferType::Vertex`。
+- `D3D12Device::CreateBuffer()` 会在创建成功后显式调用 [SetBufferType](SetBufferType.md)。
 
 ## 相关文档
 
-- [返回类总览](D3D12Buffer.md)
-- [返回模块目录](../D3D12.md)
+- [SetBufferType](SetBufferType.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetDesc.md b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetDesc.md
index fb3e668c..b198a068 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetDesc.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetDesc.md
@@ -1,30 +1,24 @@
 # D3D12Buffer::GetDesc
 
-获取相关状态或对象。
-
 ```cpp
 D3D12_RESOURCE_DESC GetDesc() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回底层缓冲资源描述。
 
-**返回：** `D3D12_RESOURCE_DESC` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 直接调用 `m_resource->GetDesc()`。
+- 没有空指针保护。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::D3D12Buffer object;
-    // 根据上下文补齐参数后调用 D3D12Buffer::GetDesc(...)。
-    (void)object;
-}
-```
+- 仅在资源已初始化时调用。
+- 如果对象可能已经 `Shutdown()`，应先通过 [GetResource](GetResource.md) 判空。
 
 ## 相关文档
 
-- [返回类总览](D3D12Buffer.md)
-- [返回模块目录](../D3D12.md)
+- [GetResource](GetResource.md)
+- [GetSize](GetSize.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetGPUAddress.md b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetGPUAddress.md
index 61fa03a4..b31ec79a 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetGPUAddress.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetGPUAddress.md
@@ -1,30 +1,20 @@
 # D3D12Buffer::GetGPUAddress
 
-获取相关状态或对象。
-
 ```cpp
 uint64_t GetGPUAddress() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+以 `uint64_t` 形式返回底层 GPU 虚拟地址。
 
-**返回：** `uint64_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Buffer object;
-    // 根据上下文补齐参数后调用 D3D12Buffer::GetGPUAddress(...)。
-    (void)object;
-}
-```
+- 直接返回 `m_resource->GetGPUVirtualAddress()`。
+- 没有空指针保护。
+- 其语义与 [GetGPUVirtualAddress](GetGPUVirtualAddress.md) 相同，只是返回类型更通用。
 
 ## 相关文档
 
-- [返回类总览](D3D12Buffer.md)
-- [返回模块目录](../D3D12.md)
+- [GetGPUVirtualAddress](GetGPUVirtualAddress.md)
+- [GetNativeHandle](GetNativeHandle.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetGPUVirtualAddress.md b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetGPUVirtualAddress.md
index 227e57ee..9d4472f3 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetGPUVirtualAddress.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetGPUVirtualAddress.md
@@ -1,30 +1,20 @@
 # D3D12Buffer::GetGPUVirtualAddress
 
-获取相关状态或对象。
-
 ```cpp
 D3D12_GPU_VIRTUAL_ADDRESS GetGPUVirtualAddress() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回底层缓冲区的 D3D12 GPU 虚拟地址。
 
-**返回：** `D3D12_GPU_VIRTUAL_ADDRESS` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Buffer object;
-    // 根据上下文补齐参数后调用 D3D12Buffer::GetGPUVirtualAddress(...)。
-    (void)object;
-}
-```
+- 直接调用 `m_resource->GetGPUVirtualAddress()`。
+- 当前多个后端实现会用它创建 CBV / VBV / IBV 或设置绘制视图。
+- 没有空指针保护。
 
 ## 相关文档
 
-- [返回类总览](D3D12Buffer.md)
-- [返回模块目录](../D3D12.md)
+- [GetGPUAddress](GetGPUAddress.md)
+- [GetResource](GetResource.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetName.md b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetName.md
index 523a14a8..b7fa2114 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetName.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetName.md
@@ -1,30 +1,19 @@
 # D3D12Buffer::GetName
 
-获取相关状态或对象。
-
 ```cpp
 const std::string& GetName() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回该缓冲区的引擎侧名称。
 
-**返回：** `const std::string&` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Buffer object;
-    // 根据上下文补齐参数后调用 D3D12Buffer::GetName(...)。
-    (void)object;
-}
-```
+- 直接返回 `m_name`。
+- [Shutdown](Shutdown.md) 不会清空该字段。
 
 ## 相关文档
 
-- [返回类总览](D3D12Buffer.md)
-- [返回模块目录](../D3D12.md)
+- [SetName](SetName.md)
+- [Shutdown](Shutdown.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetNativeHandle.md b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetNativeHandle.md
index 3c8130f1..1cdd32d7 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetNativeHandle.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetNativeHandle.md
@@ -1,30 +1,18 @@
 # D3D12Buffer::GetNativeHandle
 
-获取相关状态或对象。
-
 ```cpp
 void* GetNativeHandle() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回底层原生缓冲资源指针。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Buffer object;
-    // 根据上下文补齐参数后调用 D3D12Buffer::GetNativeHandle(...)。
-    (void)object;
-}
-```
+- 直接返回 `m_resource.Get()`。
 
 ## 相关文档
 
-- [返回类总览](D3D12Buffer.md)
-- [返回模块目录](../D3D12.md)
+- [GetResource](GetResource.md)
+- [GetGPUVirtualAddress](GetGPUVirtualAddress.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetResource.md b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetResource.md
index 7b1940c1..b70d4535 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetResource.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetResource.md
@@ -1,30 +1,19 @@
 # D3D12Buffer::GetResource
 
-获取相关状态或对象。
-
 ```cpp
 ID3D12Resource* GetResource() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回底层 `ID3D12Resource*`。
 
-**返回：** `ID3D12Resource*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Buffer object;
-    // 根据上下文补齐参数后调用 D3D12Buffer::GetResource(...)。
-    (void)object;
-}
-```
+- 已初始化时返回有效指针。
+- 否则返回 `nullptr`。
 
 ## 相关文档
 
-- [返回类总览](D3D12Buffer.md)
-- [返回模块目录](../D3D12.md)
+- [GetDesc](GetDesc.md)
+- [GetNativeHandle](GetNativeHandle.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetSize.md b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetSize.md
index a75c254d..f4c127d4 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetSize.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetSize.md
@@ -1,30 +1,19 @@
 # D3D12Buffer::GetSize
 
-获取相关状态或对象。
-
 ```cpp
 uint64_t GetSize() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回缓冲区大小。
 
-**返回：** `uint64_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Buffer object;
-    // 根据上下文补齐参数后调用 D3D12Buffer::GetSize(...)。
-    (void)object;
-}
-```
+- 实际实现是 `GetDesc().Width`。
+- 因为 [GetDesc](GetDesc.md) 没有空指针保护，所以该接口在资源为空时也不安全。
 
 ## 相关文档
 
-- [返回类总览](D3D12Buffer.md)
-- [返回模块目录](../D3D12.md)
+- [GetDesc](GetDesc.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetState.md b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetState.md
index 5143b1cc..352b8b7b 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetState.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetState.md
@@ -1,30 +1,24 @@
 # D3D12Buffer::GetState
 
-获取相关状态或对象。
-
 ```cpp
 ResourceStates GetState() const;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回引擎侧缓存的资源状态。
 
-**返回：** `ResourceStates` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 直接返回 `m_state`。
+- 初始化函数通常不会自动同步它。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::D3D12Buffer object;
-    // 根据上下文补齐参数后调用 D3D12Buffer::GetState(...)。
-    (void)object;
-}
-```
+- 不应把该返回值直接等同于底层 D3D12 资源的真实状态。
+- 如果你手工做了 barrier 或通过特殊初始化路径创建资源，通常还需要显式 [SetState](SetState.md)。
 
 ## 相关文档
 
-- [返回类总览](D3D12Buffer.md)
-- [返回模块目录](../D3D12.md)
+- [SetState](SetState.md)
+- [InitializeWithData](InitializeWithData.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetStride.md b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetStride.md
index 66241936..abcb6d5a 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetStride.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/GetStride.md
@@ -1,30 +1,19 @@
 # D3D12Buffer::GetStride
 
-获取相关状态或对象。
-
 ```cpp
 uint32_t GetStride() const override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+返回该缓冲区记录的元素步长。
 
-**返回：** `uint32_t` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Buffer object;
-    // 根据上下文补齐参数后调用 D3D12Buffer::GetStride(...)。
-    (void)object;
-}
-```
+- 直接返回 `m_stride`。
+- 设备工厂会在创建成功后调用 [SetStride](SetStride.md)。
 
 ## 相关文档
 
-- [返回类总览](D3D12Buffer.md)
-- [返回模块目录](../D3D12.md)
+- [SetStride](SetStride.md)
+- [GetBufferType](GetBufferType.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Initialize.md b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Initialize.md
index f140e03b..a58007ec 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Initialize.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Initialize.md
@@ -1,34 +1,47 @@
 # 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);
+bool Initialize(
+    ID3D12Device* device,
+    uint64_t size,
+    D3D12_RESOURCE_STATES initialState = D3D12_RESOURCE_STATE_COMMON,
+    D3D12_HEAP_TYPE heapType = D3D12_HEAP_TYPE_DEFAULT);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `device` - 参数语义详见头文件声明。
-- `size` - 参数语义详见头文件声明。
-- `initialState` - 参数语义详见头文件声明。
-- `heapType` - 参数语义详见头文件声明。
+创建一个 committed buffer resource。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 参数说明
 
-**示例：**
+- `device`: D3D12 设备。
+- `size`: 缓冲区大小，单位为字节。
+- `initialState`: 创建时的底层资源状态。
+- `heapType`: 使用的堆类型。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
+## 返回值
 
-void Example() {
-    XCEngine::RHI::D3D12Buffer object;
-    // 根据上下文补齐参数后调用 D3D12Buffer::Initialize(...)。
-    (void)object;
-}
-```
+- `CreateCommittedResource()` 成功时返回 `true`。
+- 失败时返回 `false`。
+
+## 当前实现行为
+
+- 构造一个 `D3D12_RESOURCE_DIMENSION_BUFFER` 描述。
+- 使用 `bufferDesc.Width = size`。
+- `Layout` 固定为 `D3D12_TEXTURE_LAYOUT_ROW_MAJOR`。
+- `Flags` 固定为 `D3D12_RESOURCE_FLAG_NONE`。
+- 调用 `CreateCommittedResource()` 创建资源。
+- 创建成功后不会同步:
+  - `m_state`
+  - `m_stride`
+  - `m_bufferType`
+
+## 设计说明
+
+- 当前工厂层会在外部再补写步长和类型。
+- 这说明初始化函数负责“创建资源”，而对象元数据完整性依赖更高层调用者。
 
 ## 相关文档
 
-- [返回类总览](D3D12Buffer.md)
-- [返回模块目录](../D3D12.md)
+- [SetStride](SetStride.md)
+- [SetBufferType](SetBufferType.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/InitializeFromExisting.md b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/InitializeFromExisting.md
index c7d5db42..e2df93e4 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/InitializeFromExisting.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/InitializeFromExisting.md
@@ -1,31 +1,32 @@
 # D3D12Buffer::InitializeFromExisting
 
-初始化内部状态。
-
 ```cpp
 bool InitializeFromExisting(ID3D12Resource* resource);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `resource` - 参数语义详见头文件声明。
+用一个已有的 `ID3D12Resource` 包装当前对象。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- 当前实现始终返回 `true`，即使 `resource == nullptr`。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::D3D12Buffer object;
-    // 根据上下文补齐参数后调用 D3D12Buffer::InitializeFromExisting(...)。
-    (void)object;
-}
-```
+- 仅把 `resource` 赋给内部 `ComPtr`。
+- 不会推导或更新:
+  - `m_state`
+  - `m_stride`
+  - `m_bufferType`
+  - `m_name`
+
+## 使用建议
+
+- 调用后应自行验证 [GetResource](GetResource.md) 是否为空。
+- 如果上层需要正确的类型和步长元数据，应显式调用 [SetStride](SetStride.md) / [SetBufferType](SetBufferType.md)。
 
 ## 相关文档
 
-- [返回类总览](D3D12Buffer.md)
-- [返回模块目录](../D3D12.md)
+- [GetResource](GetResource.md)
+- [SetBufferType](SetBufferType.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/InitializeWithData.md b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/InitializeWithData.md
index 31fbb418..2925c75f 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/InitializeWithData.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/InitializeWithData.md
@@ -1,35 +1,43 @@
 # D3D12Buffer::InitializeWithData
 
-初始化内部状态。
-
 ```cpp
-bool InitializeWithData(ID3D12Device* device, ID3D12GraphicsCommandList* commandList, const void* data, uint64_t size, D3D12_RESOURCE_STATES finalState);
+bool InitializeWithData(
+    ID3D12Device* device,
+    ID3D12GraphicsCommandList* commandList,
+    const void* data,
+    uint64_t size,
+    D3D12_RESOURCE_STATES finalState);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `device` - 参数语义详见头文件声明。
-- `commandList` - 参数语义详见头文件声明。
-- `data` - 参数语义详见头文件声明。
-- `size` - 参数语义详见头文件声明。
-- `finalState` - 参数语义详见头文件声明。
+创建一个带初始数据的默认堆缓冲区，并录制上传拷贝命令。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 前置条件
 
-**示例：**
+- `device`、`commandList` 和 `data` 必须有效。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
+## 返回值
 
-void Example() {
-    XCEngine::RHI::D3D12Buffer object;
-    // 根据上下文补齐参数后调用 D3D12Buffer::InitializeWithData(...)。
-    (void)object;
-}
-```
+- 资源创建和命令录制成功时返回 `true`。
+- 任一步骤失败时返回 `false`。
+
+## 当前实现行为
+
+- 创建一个默认堆 buffer，初始状态为 `COPY_DEST`。
+- 通过 `GetCopyableFootprints()` 计算拷贝 footprint。
+- 再创建一个 upload heap 临时缓冲。
+- 把 `data` 全量复制到该上传缓冲。
+- 录制 `CopyBufferRegion()`。
+- 录制从 `COPY_DEST` 到 `finalState` 的 transition barrier。
+
+## 重要限制
+
+- 当前函数不会把 `m_state` 更新为 `finalState`。
+- 函数内部创建的临时上传资源当前使用原始指针保存，并没有在函数尾部显式释放。
+- 该函数只负责录制命令，不负责提交命令列表或等待 GPU 完成。
 
 ## 相关文档
 
-- [返回类总览](D3D12Buffer.md)
-- [返回模块目录](../D3D12.md)
+- [GetState](GetState.md)
+- [SetState](SetState.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Map.md b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Map.md
index 2cde14a9..b29c0972 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Map.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Map.md
@@ -1,30 +1,26 @@
 # D3D12Buffer::Map
 
-公开方法，详见头文件声明。
-
 ```cpp
 void* Map() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+映射底层缓冲区并返回 CPU 指针。
 
-**返回：** `void*` - 返回值语义详见头文件声明。
+## 当前实现行为
 
-**示例：**
+- 构造 `D3D12_RANGE readRange = { 0, 0 }`。
+- 调用 `m_resource->Map(0, &readRange, &data)`。
+- 返回映射得到的指针。
+- 不检查 `Map()` 的 `HRESULT`。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::D3D12Buffer object;
-    // 根据上下文补齐参数后调用 D3D12Buffer::Map(...)。
-    (void)object;
-}
-```
+- 该接口更适合 upload / readback heap 资源。
+- 如果底层资源不可映射，当前实现不会提供错误信息，返回指针可能为空。
 
 ## 相关文档
 
-- [返回类总览](D3D12Buffer.md)
-- [返回模块目录](../D3D12.md)
+- [Unmap](Unmap.md)
+- [SetData](SetData.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/SetBufferType.md b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/SetBufferType.md
index 91f6c2dd..229863f9 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/SetBufferType.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/SetBufferType.md
@@ -1,31 +1,19 @@
 # D3D12Buffer::SetBufferType
 
-设置相关状态或配置。
-
 ```cpp
 void SetBufferType(BufferType type) override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `type` - 参数语义详见头文件声明。
+设置该缓冲区的逻辑类型元数据。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Buffer object;
-    // 根据上下文补齐参数后调用 D3D12Buffer::SetBufferType(...)。
-    (void)object;
-}
-```
+- 直接把 `m_bufferType` 设为传入值。
+- 不会修改底层资源本身。
 
 ## 相关文档
 
-- [返回类总览](D3D12Buffer.md)
-- [返回模块目录](../D3D12.md)
+- [GetBufferType](GetBufferType.md)
+- [Initialize](Initialize.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/SetData.md b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/SetData.md
index 8780b0d8..486d504f 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/SetData.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/SetData.md
@@ -1,33 +1,33 @@
 # D3D12Buffer::SetData
 
-设置相关状态或配置。
-
 ```cpp
 void SetData(const void* data, size_t size, size_t offset = 0) override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `data` - 参数语义详见头文件声明。
-- `size` - 参数语义详见头文件声明。
-- `offset` - 参数语义详见头文件声明。
+把一段 CPU 数据写入当前缓冲区指定偏移处。
 
-**返回：** `void` - 无返回值。
+## 参数说明
 
-**示例：**
+- `data`: 源数据指针。
+- `size`: 写入字节数。
+- `offset`: 写入偏移。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::D3D12Buffer object;
-    // 根据上下文补齐参数后调用 D3D12Buffer::SetData(...)。
-    (void)object;
-}
-```
+- 构造 `D3D12_RANGE writeRange = { offset, offset + size }`。
+- 调用 `Map()` 获取底层指针。
+- 执行 `memcpy(pBuffer + offset, data, size)`。
+- 调用 `Unmap()`。
+
+## 重要限制
+
+- 没有越界检查。
+- 没有检查 `Map()` 是否成功。
+- 对默认堆资源直接调用该接口并不可靠；当前实现更适合 CPU 可见堆。
 
 ## 相关文档
 
-- [返回类总览](D3D12Buffer.md)
-- [返回模块目录](../D3D12.md)
+- [Map](Map.md)
+- [UpdateData](UpdateData.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/SetName.md b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/SetName.md
index 842ee802..ea01faae 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/SetName.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/SetName.md
@@ -1,31 +1,19 @@
 # D3D12Buffer::SetName
 
-设置相关状态或配置。
-
 ```cpp
 void SetName(const std::string& name) override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `name` - 参数语义详见头文件声明。
+设置该缓冲区的引擎侧名称。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Buffer object;
-    // 根据上下文补齐参数后调用 D3D12Buffer::SetName(...)。
-    (void)object;
-}
-```
+- 仅把名称保存到 `m_name`。
+- 不会调用 `ID3D12Object::SetName()`。
 
 ## 相关文档
 
-- [返回类总览](D3D12Buffer.md)
-- [返回模块目录](../D3D12.md)
+- [GetName](GetName.md)
+- [D3D12Buffer](D3D12Buffer.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/SetState.md b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/SetState.md
index c67e03eb..eaf7ff38 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/SetState.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/SetState.md
@@ -1,31 +1,19 @@
 # D3D12Buffer::SetState
 
-设置相关状态或配置。
-
 ```cpp
 void SetState(ResourceStates state);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `state` - 参数语义详见头文件声明。
+手工同步引擎侧缓存的资源状态。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Buffer object;
-    // 根据上下文补齐参数后调用 D3D12Buffer::SetState(...)。
-    (void)object;
-}
-```
+- 直接写入 `m_state`。
+- 不会自动插入 D3D12 barrier。
 
 ## 相关文档
 
-- [返回类总览](D3D12Buffer.md)
-- [返回模块目录](../D3D12.md)
+- [GetState](GetState.md)
+- [InitializeWithData](InitializeWithData.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/SetStride.md b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/SetStride.md
index 3d8cd0ab..e3012180 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/SetStride.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/SetStride.md
@@ -1,31 +1,19 @@
 # D3D12Buffer::SetStride
 
-设置相关状态或配置。
-
 ```cpp
 void SetStride(uint32_t stride) override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `stride` - 参数语义详见头文件声明。
+设置缓冲区元素步长元数据。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Buffer object;
-    // 根据上下文补齐参数后调用 D3D12Buffer::SetStride(...)。
-    (void)object;
-}
-```
+- 直接写入 `m_stride`。
+- 不会验证该步长是否与真实数据布局一致。
 
 ## 相关文档
 
-- [返回类总览](D3D12Buffer.md)
-- [返回模块目录](../D3D12.md)
+- [GetStride](GetStride.md)
+- [GetBufferType](GetBufferType.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Shutdown.md b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Shutdown.md
index 11fa110e..9b7985bb 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Shutdown.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Shutdown.md
@@ -1,30 +1,27 @@
 # D3D12Buffer::Shutdown
 
-关闭并清理内部状态。
-
 ```cpp
 void Shutdown() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+释放内部 `ID3D12Resource` 引用。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
+- 仅调用 `m_resource.Reset()`。
+- 不会重置:
+  - `m_state`
+  - `m_name`
+  - `m_stride`
+  - `m_bufferType`
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
+## 使用建议
 
-void Example() {
-    XCEngine::RHI::D3D12Buffer object;
-    // 根据上下文补齐参数后调用 D3D12Buffer::Shutdown(...)。
-    (void)object;
-}
-```
+- `Shutdown()` 后不要继续调用 [GetDesc](GetDesc.md)、[GetSize](GetSize.md)、[GetGPUVirtualAddress](GetGPUVirtualAddress.md) 这类依赖 `m_resource` 的接口。
 
 ## 相关文档
 
-- [返回类总览](D3D12Buffer.md)
-- [返回模块目录](../D3D12.md)
+- [Destructor](Destructor.md)
+- [GetResource](GetResource.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Unmap.md b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Unmap.md
index c18520d8..0237ab23 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Unmap.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/Unmap.md
@@ -1,30 +1,19 @@
 # D3D12Buffer::Unmap
 
-公开方法，详见头文件声明。
-
 ```cpp
 void Unmap() override;
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：** 无。
+结束当前缓冲区映射。
 
-**返回：** `void` - 无返回值。
+## 当前实现行为
 
-**示例：**
-
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
-
-void Example() {
-    XCEngine::RHI::D3D12Buffer object;
-    // 根据上下文补齐参数后调用 D3D12Buffer::Unmap(...)。
-    (void)object;
-}
-```
+- 直接调用 `m_resource->Unmap(0, nullptr)`。
+- 不检查 `m_resource` 是否为空。
 
 ## 相关文档
 
-- [返回类总览](D3D12Buffer.md)
-- [返回模块目录](../D3D12.md)
+- [Map](Map.md)
+- [SetData](SetData.md)
diff --git a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/UpdateData.md b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/UpdateData.md
index 2cd0d791..2e2dc31f 100644
--- a/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/UpdateData.md
+++ b/docs/api/XCEngine/RHI/D3D12/D3D12Buffer/UpdateData.md
@@ -1,32 +1,32 @@
 # D3D12Buffer::UpdateData
 
-更新运行时状态。
-
 ```cpp
 void UpdateData(const void* data, uint64_t size);
 ```
 
-该方法声明于 `XCEngine/RHI/D3D12/D3D12Buffer.h`，当前页面用于固定 `D3D12Buffer` 类目录下的方法级 canonical 路径。
+## 作用
 
-**参数：**
-- `data` - 参数语义详见头文件声明。
-- `size` - 参数语义详见头文件声明。
+把一段数据覆盖写入缓冲区起始位置。
 
-**返回：** `void` - 无返回值。
+## 参数说明
 
-**示例：**
+- `data`: 源数据指针。
+- `size`: 写入字节数。
 
-```cpp
-#include <XCEngine/RHI/D3D12/D3D12Buffer.h>
+## 当前实现行为
 
-void Example() {
-    XCEngine::RHI::D3D12Buffer object;
-    // 根据上下文补齐参数后调用 D3D12Buffer::UpdateData(...)。
-    (void)object;
-}
-```
+- 构造 `D3D12_RANGE range = { 0, size }`。
+- 调用 `Map()` 获取指针。
+- 执行 `memcpy(pBuffer, data, size)`。
+- 调用 `Unmap()`。
+
+## 重要限制
+
+- 没有检查映射是否成功。
+- 不适合对不可 CPU 写入的堆类型使用。
+- 该接口总是从偏移 `0` 开始写入，无法指定任意目标偏移。
 
 ## 相关文档
 
-- [返回类总览](D3D12Buffer.md)
-- [返回模块目录](../D3D12.md)
+- [SetData](SetData.md)
+- [Map](Map.md)
diff --git a/docs/api/_meta/rebuild-status.md b/docs/api/_meta/rebuild-status.md
index 35af29a1..5729a82a 100644
--- a/docs/api/_meta/rebuild-status.md
+++ b/docs/api/_meta/rebuild-status.md
@@ -1,6 +1,6 @@
 # API 文档重构状态
 
-**生成时间**: `2026-03-27 23:42:53`
+**生成时间**: `2026-03-27 23:48:52`
 
 **来源**: `docs/api/_tools/audit_api_docs.py`