docs: update math API docs

docs/api/math/box/box.md

@@ -1,44 +1,65 @@
 # Box
 
-带变换的包围盒结构体（支持 OBB 语义，取决于方法）。
+**命名空间**: `XCEngine::Math`
 
-**头文件：** `#include <XCEngine/Math/Box.h>`
+**类型**: `struct`
 
-**命名空间：** `XCEngine::Math`
+**头文件**: `XCEngine/Math/Box.h`
 
-## 结构体定义
+**描述**: 轴对齐盒体，用于碰撞检测和视锥体裁剪
+
+## 概述
+
+`Box` 是一个轴对齐包围盒（AABB）结构体，支持可选的变换矩阵以实现定向包围盒（OBB）语义。盒体由中心点 `center` 和半长 `extents` 定义，`transform` 矩阵可用于 `Contains` 和 `Intersects(Sphere)` 方法以执行真正的 OBB 检测。
+
+**注意：**
+- `Contains` 和 `Intersects(Sphere)` 方法会将点/球心变换到盒体局部空间（使用 `transform` 的逆矩阵）进行检测
+- `GetMin` / `GetMax` 返回的是未应用 `transform` 的局部空间角点（即 `center ± extents`）
+- `Intersects(Box)` 目前使用 AABB 简化算法，未考虑旋转
+
+## 结构体成员
+
+| 成员 | 类型 | 描述 | 默认值 |
+|------|------|------|--------|
+| `center` | `Vector3` | 盒体中心点 | `Vector3::Zero()` |
+| `extents` | `Vector3` | 从中心到每个面的距离（实际尺寸 = extents * 2） | `Vector3::Zero()` |
+| `transform` | `Matrix4` | 变换矩阵，用于 OBB 检测 | 单位矩阵 |
+
+## 公共方法
+
+| 方法 | 描述 |
+|------|------|
+| [`Box()`](constructor.md) | 默认构造（各量为零） |
+| [`Box(center, extents)`](constructor.md) | 从中心和半长构造 |
+| [`GetMin`](getmin.md) | 获取局部空间最小点 |
+| [`GetMax`](getmax.md) | 获取局部空间最大点 |
+| [`Contains`](contains.md) | 点是否在盒内（使用 transform） |
+| [`Intersects(Sphere)`](intersects.md) | 与球体相交 |
+| [`Intersects(Box)`](intersects-box.md) | 与另一个盒相交（AABB 检测） |
+| [`Intersects(Ray, t)`](intersects-ray.md) | 与射线相交 |
+
+## 使用示例
 
 ```cpp
-struct Box {
-    Vector3 center = Vector3::Zero();
-    Vector3 extents = Vector3::Zero();
-    Matrix4x4 transform = Matrix4x4::Identity();
-};
+#include <XCEngine/Math/Box.h>
+#include <XCEngine/Math/Vector3.h>
+#include <XCEngine/Math/Sphere.h>
+
+using namespace XCEngine::Math;
+
+Box box(Vector3(0.0f, 0.0f, 0.0f), Vector3(1.0f, 1.0f, 1.0f));
+
+Vector3 min = box.GetMin();
+Vector3 max = box.GetMax();
+
+if (box.Contains(Vector3(0.5f, 0.5f, 0.5f))) {
+}
+
+Sphere sphere(Vector3(2.0f, 0.0f, 0.0f), 1.0f);
+if (box.Intersects(sphere)) {
+}
 ```
 
-**成员：**
-- `center` - 包围盒中心点
-- `extents` - 包围盒半长（各轴向的半径）
-- `transform` - 变换矩阵（用于 OBB 检测）
-
-**注意：** `Contains` 方法会使用 `transform` 进行真正的 OBB 检测。`Intersects(Box)` 目前使用 AABB 简化算法，未考虑旋转。
-
-## 构造函数
-
-- `Box()` - 默认构造
-- `Box(const Vector3& center, const Vector3& extents)` - 从中心和半长构造
-
-## 实例方法
-
-| 方法 | 返回值 | 描述 |
-|------|--------|------|
-| [GetMin()](getmin.md) | `Vector3` | 局部空间最小点 |
-| [GetMax()](getmax.md) | `Vector3` | 局部空间最大点 |
-| [Contains(point)](contains.md) | `bool` | 点是否在盒内（使用 transform） |
-| [Intersects(Sphere)](intersects.md) | `bool` | 与球体相交 |
-| [Intersects(Box)](intersects-box.md) | `bool` | 与另一个盒相交（AABB 检测） |
-| [Intersects(Ray, t)](intersects-ray.md) | `bool` | 与射线相交 |
-
 ## 相关文档
 
 - [Math 模块总览](../math.md) - 返回 Math 模块总览