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/resources/resourcehandle/get.md

@@ -0,0 +1,27 @@
+# ResourceHandle::Get
+
+```cpp
+T* Get() const
+```
+
+获取资源裸指针。返回句柄内部持有的资源指针，不进行任何引用计数操作。
+
+**参数：** 无
+
+**返回：** 资源裸指针，可能为 `nullptr`（当句柄为空时）
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+ResourceHandle<Texture> tex = ResourceManager::Get().Load<Texture>("tex.png");
+Texture* raw = tex.Get();
+if (raw != nullptr) {
+    uint32_t w = raw->GetWidth();
+}
+```
+
+## 相关文档
+
+- [ResourceHandle 总览](resourcehandle.md) - 返回类总览

docs/api/resources/resourcehandle/getguid.md

@@ -0,0 +1,27 @@
+# ResourceHandle::GetGUID
+
+```cpp
+ResourceGUID GetGUID() const
+```
+
+获取资源的全局唯一标识符。如果内部指针为空，则返回一个值为 0 的空 GUID。
+
+**参数：** 无
+
+**返回：** 资源的 `ResourceGUID`，如果句柄为空则返回 `ResourceGUID(0)`
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+ResourceHandle<Texture> tex = ResourceManager::Get().Load<Texture>("tex.png");
+ResourceGUID guid = tex.GetGUID();
+if (guid.IsValid()) {
+    printf("GUID: %s\n", guid.ToString().CStr());
+}
+```
+
+## 相关文档
+
+- [ResourceHandle 总览](resourcehandle.md) - 返回类总览

docs/api/resources/resourcehandle/isvalid.md

@@ -0,0 +1,29 @@
+# ResourceHandle::IsValid
+
+```cpp
+bool IsValid() const
+```
+
+检查句柄是否持有有效资源。判断条件为：内部指针非空且资源的 `IsValid()` 返回 true。
+
+**参数：** 无
+
+**返回：** 如果持有有效资源则返回 true，否则返回 false
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+ResourceHandle<Texture> tex = ResourceManager::Get().Load<Texture>("tex.png");
+if (tex.IsValid()) {
+    // 安全访问资源
+    tex->GenerateMipmaps();
+} else {
+    printf("Texture load failed!\n");
+}
+```
+
+## 相关文档
+
+- [ResourceHandle 总览](resourcehandle.md) - 返回类总览

docs/api/resources/resourcehandle/reset.md

@@ -0,0 +1,31 @@
+# ResourceHandle::Reset
+
+```cpp
+void Reset()
+```
+
+释放当前持有的资源引用。如果内部持有的资源指针非空，则调用 `ResourceManager::Release()` 减少引用计数，并将内部指针置为 `nullptr`。析构函数会自动调用此方法。
+
+**参数：** 无
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+ResourceHandle<Texture> tex = ResourceManager::Get().Load<Texture>("tex.png");
+// 使用纹理...
+tex.Reset();  // 释放引用，引用计数 -1
+
+// 或者让句柄离开作用域自动释放
+{
+    ResourceHandle<Mesh> mesh = ResourceManager::Get().Load<Mesh>("model.fbx");
+    // 使用网格...
+}  // mesh 自动 Reset()
+```
+
+## 相关文档
+
+- [ResourceHandle 总览](resourcehandle.md) - 返回类总览

docs/api/resources/resourcehandle/resourcehandle.md

@@ -0,0 +1,101 @@
+# ResourceHandle
+
+**命名空间**: `XCEngine::Resources`
+
+**类型**: `class` (template)
+
+**描述**: 模板资源句柄类，提供资源的引用计数式安全访问，自动管理资源的加载和释放。
+
+## 概述
+
+`ResourceHandle<T>` 是一个模板句柄类，用于安全地持有对资源的引用。它通过 `ResourceManager` 自动管理引用计数：当句柄被创建时引用计数增加，当句柄被销毁或调用 `Reset()` 时引用计数减少。这确保了资源在其仍被使用时不会被卸载。
+
+## 模板参数
+
+| 参数 | 约束 | 描述 |
+|------|------|------|
+| `T` | 必须派生自 `IResource` | 资源类型 |
+
+## 公共方法
+
+### 构造/析构
+
+| 方法 | 描述 |
+|------|------|
+| `ResourceHandle() = default` | 默认构造空句柄 |
+| `explicit ResourceHandle(T* resource)` | 从裸指针构造（自动增加引用） |
+| `ResourceHandle(const ResourceHandle& other)` | 拷贝构造（自动增加引用） |
+| `ResourceHandle(ResourceHandle&& other) noexcept` | 移动构造 |
+| `~ResourceHandle()` | 析构函数（自动调用 Reset） |
+
+### 赋值
+
+| 方法 | 描述 |
+|------|------|
+| `ResourceHandle& operator=(const ResourceHandle& other)` | 拷贝赋值（自动管理引用） |
+| `ResourceHandle& operator=(ResourceHandle&& other) noexcept` | 移动赋值 |
+
+### 资源访问
+
+| 方法 | 描述 |
+|------|------|
+| `T* Get() const` | 获取裸指针 |
+| `T* operator->() const` | 通过指针访问资源成员 |
+| `T& operator*() const` | 解引用获取资源引用 |
+
+### 状态查询
+
+| 方法 | 描述 |
+|------|------|
+| `bool IsValid() const` | 检查句柄是否持有有效资源 |
+| `explicit operator bool() const` | 隐式布尔转换 |
+
+### GUID 和类型
+
+| 方法 | 描述 |
+|------|------|
+| `ResourceGUID GetGUID() const` | 获取资源的全局唯一标识符 |
+| `ResourceType GetResourceType() const` | 获取资源类型 |
+
+### 资源释放
+
+| 方法 | 描述 |
+|------|------|
+| `void Reset()` | 释放当前资源引用 |
+| `void Swap(ResourceHandle& other)` | 交换两个句柄的内容 |
+
+## 比较运算
+
+| 运算符 | 描述 |
+|------|------|
+| `operator==(ResourceHandle, ResourceHandle)` | 比较 GUID 是否相等 |
+| `operator!=(ResourceHandle, ResourceHandle)` | 比较 GUID 是否不等 |
+
+## 使用示例
+
+```cpp
+// 加载资源（引用计数 +1）
+ResourceHandle<Texture> tex = ResourceManager::Get().Load<Texture>("textures/player.png");
+
+// 检查有效性
+if (tex.IsValid()) {
+    // 安全访问资源
+    uint32_t width = tex->GetWidth();
+}
+
+// 拷贝句柄（引用计数 +1）
+ResourceHandle<Texture> tex2 = tex;
+
+// 移动句柄
+ResourceHandle<Texture> tex3 = std::move(tex2);
+
+// 句柄离开作用域时自动释放（引用计数 -1）
+tex.Reset();  // 手动释放
+```
+
+## 相关文档
+
+- [IResource](../iresource/iresource.md) - 资源基类
+- [ResourceManager](../resourcemanager/resourcemanager.md) - 资源管理器
+- [ResourceCache](../resourcecache/resourcecache.md) - 资源缓存
+- [Resources 总览](../resources.md) - 返回模块总览

docs/api/resources/resourcehandle/swap.md

@@ -0,0 +1,30 @@
+# ResourceHandle::Swap
+
+```cpp
+void Swap(ResourceHandle& other)
+```
+
+交换两个句柄持有的资源指针。使用 `std::swap` 交换内部指针，不会改变任何引用计数。此操作常用于在不影响引用计数的情况下安全地交换两个句柄的内容。
+
+**参数：**
+- `other` - 要交换的另一个 ResourceHandle 引用
+
+**返回：** 无
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+ResourceHandle<Texture> tex1 = ResourceManager::Get().Load<Texture>("a.png");
+ResourceHandle<Texture> tex2 = ResourceManager::Get().Load<Texture>("b.png");
+
+// 交换后 tex1 持有 b.png，tex2 持有 a.png
+tex1.Swap(tex2);
+
+// 引用计数不变
+```
+
+## 相关文档
+
+- [ResourceHandle 总览](resourcehandle.md) - 返回类总览