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/math/vector3/angle.md

@@ -0,0 +1,23 @@
+# Vector3::Angle
+
+```cpp
+static float Angle(const Vector3& from, const Vector3& to)
+```
+
+计算两个向量之间的夹角（以度为单位）。
+
+**参数：**
+- `from` - 起始向量
+- `to` - 目标向量
+
+**返回：** `float` - 两向量之间的夹角（0-180度）
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 a(1.0f, 0.0f, 0.0f);
+Vector3 b(0.0f, 1.0f, 0.0f);
+float angle = Vector3::Angle(a, b);  // 90.0f
+```

docs/api/math/vector3/back.md

@@ -0,0 +1,17 @@
+# Vector3::Back
+
+```cpp
+static Vector3 Back()
+```
+
+返回后方向向量 (0, 0, -1)。
+
+**返回：** `Vector3` - 值为 (0, 0, -1) 的向量
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 back = Vector3::Back();
+```

docs/api/math/vector3/cross.md

@@ -0,0 +1,23 @@
+# Vector3::Cross
+
+```cpp
+static Vector3 Cross(const Vector3& a, const Vector3& b)
+```
+
+计算两个 3D 向量的叉积。结果向量同时垂直于 a 和 b。
+
+**参数：**
+- `a` - 第一个向量
+- `b` - 第二个向量
+
+**返回：** `Vector3` - 叉积结果，垂直于 a 和 b 的向量
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 right(1.0f, 0.0f, 0.0f);
+Vector3 up(0.0f, 1.0f, 0.0f);
+Vector3 forward = Vector3::Cross(right, up);  // (0, 0, 1)
+```

docs/api/math/vector3/dot.md

@@ -0,0 +1,23 @@
+# Vector3::Dot
+
+```cpp
+static float Dot(const Vector3& a, const Vector3& b)
+```
+
+计算两个 3D 向量的点积。
+
+**参数：**
+- `a` - 第一个向量
+- `b` - 第二个向量
+
+**返回：** `float` - 点积结果 a.x * b.x + a.y * b.y + a.z * b.z
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 a(1.0f, 0.0f, 0.0f);
+Vector3 b(0.0f, 1.0f, 0.0f);
+float dot = Vector3::Dot(a, b);  // 0.0f
+```

docs/api/math/vector3/down.md

@@ -0,0 +1,17 @@
+# Vector3::Down
+
+```cpp
+static Vector3 Down()
+```
+
+返回下方向向量 (0, -1, 0)。
+
+**返回：** `Vector3` - 值为 (0, -1, 0) 的向量
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 down = Vector3::Down();
+```

docs/api/math/vector3/forward.md

@@ -0,0 +1,17 @@
+# Vector3::Forward
+
+```cpp
+static Vector3 Forward()
+```
+
+返回前方向向量 (0, 0, 1)。
+
+**返回：** `Vector3` - 值为 (0, 0, 1) 的向量
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 forward = Vector3::Forward();
+```

docs/api/math/vector3/left.md

@@ -0,0 +1,17 @@
+# Vector3::Left
+
+```cpp
+static Vector3 Left()
+```
+
+返回左方向向量 (-1, 0, 0)。
+
+**返回：** `Vector3` - 值为 (-1, 0, 0) 的向量
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 left = Vector3::Left();
+```

docs/api/math/vector3/lerp.md

@@ -0,0 +1,24 @@
+# Vector3::Lerp
+
+```cpp
+static Vector3 Lerp(const Vector3& a, const Vector3& b, float t)
+```
+
+在线性插值两个向量之间。参数 t 会在 [0, 1] 范围内被限制。
+
+**参数：**
+- `a` - 起始向量
+- `b` - 结束向量
+- `t` - 插值因子，0 返回 a，1 返回 b
+
+**返回：** `Vector3` - 插值结果
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 start(0.0f, 0.0f, 0.0f);
+Vector3 end(10.0f, 10.0f, 10.0f);
+Vector3 mid = Vector3::Lerp(start, end, 0.5f);  // (5.0f, 5.0f, 5.0f)
+```

docs/api/math/vector3/magnitude.md

@@ -0,0 +1,25 @@
+# Vector3::Magnitude
+
+```cpp
+static float Magnitude(const Vector3& v)
+float Magnitude() const
+```
+
+计算向量的长度（欧几里得范数）。
+
+**静态版本参数：**
+- `v` - 要计算长度的向量
+
+**实例版本：** 计算当前向量的长度。
+
+**返回：** `float` - 向量长度 sqrt(x * x + y * y + z * z)
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 v(1.0f, 2.0f, 2.0f);
+float len = v.Magnitude();                    // 3.0f
+float len2 = Vector3::Magnitude(v);          // 3.0f
+```

docs/api/math/vector3/movetowards.md

@@ -0,0 +1,24 @@
+# Vector3::MoveTowards
+
+```cpp
+static Vector3 MoveTowards(const Vector3& current, const Vector3& target, float maxDistance)
+```
+
+将当前向量朝目标向量移动指定距离。如果距离已小于 maxDistance，则直接返回目标。
+
+**参数：**
+- `current` - 当前向量
+- `target` - 目标向量
+- `maxDistance` - 最大移动距离
+
+**返回：** `Vector3` - 移动后的位置
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 current(0.0f, 0.0f, 0.0f);
+Vector3 target(10.0f, 0.0f, 0.0f);
+Vector3 moved = Vector3::MoveTowards(current, target, 3.0f);  // (3.0f, 0, 0)
+```

docs/api/math/vector3/normalize.md

@@ -0,0 +1,20 @@
+# Vector3::Normalize
+
+```cpp
+static Vector3 Normalize(const Vector3& v)
+```
+
+将向量归一化为单位长度。如果向量长度接近零，返回零向量。
+
+**参数：**
+- `v` - 要归一化的向量
+
+**返回：** `Vector3` - 归一化后的单位向量
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 dir = Vector3::Normalize(Vector3(3.0f, 4.0f, 0.0f));  // (0.6f, 0.8f, 0)
+```

docs/api/math/vector3/normalized.md

@@ -0,0 +1,18 @@
+# Vector3::Normalized
+
+```cpp
+Vector3 Normalized() const
+```
+
+返回当前向量的归一化副本（单位长度）。不修改原向量。
+
+**返回：** `Vector3` - 归一化后的向量副本
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 v(3.0f, 4.0f, 0.0f);
+Vector3 unit = v.Normalized();  // (0.6f, 0.8f, 0), v 保持不变
+```

docs/api/math/vector3/one.md

@@ -0,0 +1,17 @@
+# Vector3::One
+
+```cpp
+static Vector3 One()
+```
+
+返回单位向量 (1, 1, 1)。
+
+**返回：** `Vector3` - 值为 (1, 1, 1) 的向量
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 unit = Vector3::One();
+```

docs/api/math/vector3/project.md

@@ -0,0 +1,23 @@
+# Vector3::Project
+
+```cpp
+static Vector3 Project(const Vector3& vector, const Vector3& onNormal)
+```
+
+将向量投影到法线向量上。
+
+**参数：**
+- `vector` - 要投影的向量
+- `onNormal` - 投影到的法线向量
+
+**返回：** `Vector3` - 投影结果。如果法线长度为 0，返回零向量。
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 v(1.0f, 1.0f, 0.0f);
+Vector3 normal(1.0f, 0.0f, 0.0f);
+Vector3 projected = Vector3::Project(v, normal);  // (1, 0, 0)
+```

docs/api/math/vector3/projectonplane.md

@@ -0,0 +1,23 @@
+# Vector3::ProjectOnPlane
+
+```cpp
+static Vector3 ProjectOnPlane(const Vector3& vector, const Vector3& planeNormal)
+```
+
+将向量投影到平面上（减去沿平面法线的分量）。
+
+**参数：**
+- `vector` - 要投影的向量
+- `planeNormal` - 平面法线
+
+**返回：** `Vector3` - 平面上的投影向量
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 v(1.0f, 1.0f, 1.0f);
+Vector3 normal(0.0f, 1.0f, 0.0f);  // XZ 平面
+Vector3 projected = Vector3::ProjectOnPlane(v, normal);  // (1, 0, 1)
+```

docs/api/math/vector3/quaternion-multiply.md

@@ -0,0 +1,23 @@
+# Vector3 * Quaternion
+
+```cpp
+Vector3 operator*(const Quaternion& q, const Vector3& v)
+```
+
+用四元数旋转向量。
+
+**参数：**
+- `q` - 旋转四元数
+- `v` - 要旋转的向量
+
+**返回：** `Vector3` - 旋转后的向量
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Quaternion rot = Quaternion::FromEulerAngles(0.0f, 90.0f * DEG_TO_RAD, 0.0f);
+Vector3 forward = Vector3::Forward();
+Vector3 rotated = rot * forward;  // 绕 Y 轴旋转 90 度
+```

docs/api/math/vector3/reflect.md

@@ -0,0 +1,23 @@
+# Vector3::Reflect
+
+```cpp
+static Vector3 Reflect(const Vector3& inDirection, const Vector3& inNormal)
+```
+
+计算向量关于法线的反射方向。
+
+**参数：**
+- `inDirection` - 入射方向向量
+- `inNormal` - 反射表面的法线（应为单位向量）
+
+**返回：** `Vector3` - 反射方向
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 incoming(1.0f, -1.0f, 0.0f);
+Vector3 normal(0.0f, 1.0f, 0.0f);
+Vector3 reflected = Vector3::Reflect(incoming, normal);  // (1, 1, 0)
+```

docs/api/math/vector3/right.md

@@ -0,0 +1,17 @@
+# Vector3::Right
+
+```cpp
+static Vector3 Right()
+```
+
+返回右方向向量 (1, 0, 0)。
+
+**返回：** `Vector3` - 值为 (1, 0, 0) 的向量
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 right = Vector3::Right();
+```

docs/api/math/vector3/sqrmagnitude.md

@@ -0,0 +1,25 @@
+# Vector3::SqrMagnitude
+
+```cpp
+static float SqrMagnitude(const Vector3& v)
+float SqrMagnitude() const
+```
+
+计算向量长度的平方。比 Magnitude 更快，避免了开方运算。
+
+**静态版本参数：**
+- `v` - 要计算长度的向量
+
+**实例版本：** 计算当前向量的长度平方。
+
+**返回：** `float` - 向量长度平方 x * x + y * y + z * z
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 v(1.0f, 2.0f, 2.0f);
+float sqlen = v.SqrMagnitude();                    // 9.0f
+float sqlen2 = Vector3::SqrMagnitude(v);          // 9.0f
+```

docs/api/math/vector3/up.md

@@ -0,0 +1,17 @@
+# Vector3::Up
+
+```cpp
+static Vector3 Up()
+```
+
+返回上方向向量 (0, 1, 0)。
+
+**返回：** `Vector3` - 值为 (0, 1, 0) 的向量
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 up = Vector3::Up();
+```

docs/api/math/vector3/vector3.md

@@ -0,0 +1,69 @@
+# Vector3
+
+3D 向量结构体，用于表示 3D 空间中的点、方向、颜色或法线。
+
+**头文件：** `#include <XCEngine/Math/Vector3.h>`
+
+**命名空间：** `XCEngine::Math`
+
+## 结构体定义
+
+```cpp
+struct Vector3 {
+    float x = 0.0f;
+    float y = 0.0f;
+    float z = 0.0f;
+};
+```
+
+## 静态工厂方法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [Zero()](zero.md) | `Vector3` | 返回 (0, 0, 0) |
+| [One()](one.md) | `Vector3` | 返回 (1, 1, 1) |
+| [Forward()](forward.md) | `Vector3` | 返回 (0, 0, 1)，前方向（Z+） |
+| [Back()](back.md) | `Vector3` | 返回 (0, 0, -1)，后方向 |
+| [Up()](up.md) | `Vector3` | 返回 (0, 1, 0)，上方向 |
+| [Down()](down.md) | `Vector3` | 返回 (0, -1, 0)，下方向 |
+| [Right()](right.md) | `Vector3` | 返回 (1, 0, 0)，右方向 |
+| [Left()](left.md) | `Vector3` | 返回 (-1, 0, 0)，左方向 |
+
+## 静态数学方法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [Dot(a, b)](dot.md) | `float` | 点积 |
+| [Cross(a, b)](cross.md) | `Vector3` | 叉积（垂直于 a 和 b） |
+| [Normalize(v)](normalize.md) | `Vector3` | 归一化向量 |
+| [Magnitude(v)](magnitude.md) | `float` | 向量长度 |
+| [SqrMagnitude(v)](sqrmagnitude.md) | `float` | 长度平方 |
+| [Lerp(a, b, t)](lerp.md) | `Vector3` | 线性插值 |
+| [MoveTowards(current, target, maxDistance)](movetowards.md) | `Vector3` | 朝目标移动 |
+| [Project(vector, onNormal)](project.md) | `Vector3` | 投影到法线上 |
+| [ProjectOnPlane(vector, planeNormal)](projectonplane.md) | `Vector3` | 投影到平面上 |
+| [Angle(from, to)](angle.md) | `float` | 两向量夹角（度） |
+| [Reflect(inDirection, inNormal)](reflect.md) | `Vector3` | 反射 |
+
+## 实例方法
+
+| 方法 | 返回值 | 描述 |
+|------|--------|------|
+| [Magnitude()](magnitude.md) | `float` | 获取向量长度 |
+| [SqrMagnitude()](sqrmagnitude.md) | `float` | 获取长度平方 |
+| [Normalized()](normalized.md) | `Vector3` | 获取归一化副本 |
+
+## 运算符
+
+- 算术: `+`, `-`, `*` (scalar/memberwise), `/` (scalar/memberwise)
+- 复合赋值: `+=`, `-=`, `*=`, `/=`
+- 下标: `operator[]` (0=x, 1=y, 2=z)
+- 比较: `==`, `!=`
+
+## 与 Quaternion 的乘法
+
+[Vector3 * Quaternion](quaternion-multiply.md) - 用四元数旋转向量
+
+## 相关文档
+
+- [Math 模块总览](../math.md) - 返回 Math 模块总览

docs/api/math/vector3/zero.md

@@ -0,0 +1,17 @@
+# Vector3::Zero
+
+```cpp
+static Vector3 Zero()
+```
+
+返回零向量 (0, 0, 0)。
+
+**返回：** `Vector3` - 值为 (0, 0, 0) 的向量
+
+**复杂度：** O(1)
+
+**示例：**
+
+```cpp
+Vector3 origin = Vector3::Zero();
+```