diff --git a/Doxyfile b/Doxyfile
new file mode 100644
index 0000000..20ba4ae
--- /dev/null
+++ b/Doxyfile
@@ -0,0 +1,42 @@
+# Doxyfile for ViewDesignEngine
+# Generated 2026-07-24
+PROJECT_NAME           = "ViewDesignEngine"
+PROJECT_NUMBER         = "3.1.0"
+PROJECT_BRIEF          = "高性能 CAD 计算几何引擎"
+OUTPUT_DIRECTORY       = docs/api
+CREATE_SUBDIRS         = NO
+ALLOW_UNICODE_NAMES    = YES
+OUTPUT_LANGUAGE        = Chinese
+OPTIMIZE_OUTPUT_FOR_C  = NO
+
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = NO
+EXTRACT_PACKAGE        = NO
+EXTRACT_STATIC         = YES
+EXTRACT_LOCAL_CLASSES  = NO
+HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_CLASSES     = NO
+
+SOURCE_BROWSER         = YES
+INLINE_SOURCES         = NO
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION    = YES
+REFERENCES_LINK_SOURCE = YES
+
+ALPHABETICAL_INDEX     = YES
+GENERATE_HTML          = YES
+HTML_OUTPUT            = html
+HTML_TIMESTAMP         = YES
+GENERATE_TREEVIEW      = YES
+TREEVIEW_WIDTH         = 280
+GENERATE_LATEX         = NO
+GENERATE_XML           = NO
+
+INPUT                  = include docs/mainpage.h
+RECURSIVE              = YES
+FILE_PATTERNS          = *.h
+EXCLUDE_PATTERNS       = */detail/*
+
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+PREDEFINED             = VDE_EXPORT=
diff --git a/docs/mainpage.h b/docs/mainpage.h
new file mode 100644
index 0000000..ea04004
--- /dev/null
+++ b/docs/mainpage.h
@@ -0,0 +1,121 @@
+/**
+ * @mainpage ViewDesignEngine API 参考文档
+ *
+ * ViewDesignEngine 是一个高性能 C++17 计算几何引擎，覆盖从底层数学工具到
+ * B-Rep 拓扑建模、SDF 隐式建模、可微分几何、工业格式互操作的全栈能力。
+ *
+ * @section features 主要功能
+ * - **基础数学**: 点/向量/变换/AABB/公差系统
+ * - **曲线曲面**: Bézier / B-Spline / NURBS、自适应细分
+ * - **网格处理**: 半边数据结构、Delaunay、简化、平滑、修复、Marching Cubes
+ * - **空间索引**: BVH (SAH)、Octree、KD-Tree、R-Tree (STR)
+ * - **布尔运算**: 2D Sutherland-Hodgman、3D 网格布尔、B-Rep 布尔
+ * - **碰撞检测**: GJK/EPA、SAT、射线-三角形
+ * - **B-Rep 建模**: 边界表示、STEP/IGES 导入导出、fillet/chamfer/shell
+ * - **SDF 隐式建模**: 15+ 图元、CSG 表达式树、自动微分、梯度优化
+ * - **格式支持**: STEP、IGES、glTF/GLB、STL、OBJ、PLY
+ *
+ * @section modules 模块组织
+ *
+ * | 模块 | 命名空间 | 说明 |
+ * |------|---------|------|
+ * | @ref foundation | vde::foundation | 数学类型、公差、I/O、序列化 |
+ * | @ref core | vde::core | 点/线/面、变换、多边形、Voronoi、ICP |
+ * | @ref curves | vde::curves | NURBS 曲线曲面、细分 |
+ * | @ref mesh | vde::mesh | 半边网格、三角剖分、质量、修复 |
+ * | @ref spatial | vde::spatial | BVH、Octree、KD-Tree、R-Tree |
+ * | @ref boolean | vde::boolean | 2D/3D 布尔、多边形偏移 |
+ * | @ref collision | vde::collision | GJK、SAT、射线、三角交线 |
+ * | @ref brep | vde::brep | B-Rep 建模、STEP/IGES、布尔、验证 |
+ * | @ref sdf | vde::sdf | 隐式图元、CSG 树、自动微分、优化 |
+ * | @ref sketch | vde::sketch | 2D 约束求解 |
+ * | @ref capi | vde::capi | C API 绑定 |
+ *
+ * @section quickstart 快速开始
+ *
+ * @code{.cpp}
+ * #include <vde/sdf/sdf_primitives.h>
+ * #include <vde/sdf/sdf_operations.h>
+ *
+ * // 创建一个光滑并集: 球 + 盒子
+ * using namespace vde::core;
+ * auto f = [](double x, double y, double z) {
+ *     double d1 = vde::sdf::sphere(Point3D(x,y,z), 1.5);
+ *     double d2 = vde::sdf::box(Point3D(x,y,z), Point3D(1,1,1));
+ *     return vde::sdf::op_smooth_union(d1, d2, 0.3);
+ * };
+ *
+ * // 求值
+ * double val = f(0, 0, 0);  // SDF 值
+ * @endcode
+ *
+ * @section build 构建
+ *
+ * @code
+ * cmake -B build && cmake --build build -j$(nproc)
+ * cd build && ctest --output-on-failure
+ * @endcode
+ *
+ * 依赖: CMake ≥ 3.16, C++17 编译器, Eigen 3 (自动下载)
+ *
+ * @see https://github.com/.../ViewDesignEngine
+ */
+
+// ── Module group definitions ──
+
+/**
+ * @defgroup foundation 基础模块 (vde::foundation)
+ * @brief 数学类型、公差系统、精确谓词、文件 I/O、序列化
+ *
+ * 提供整个引擎使用的底层基础设施。
+ */
+
+/**
+ * @defgroup core 核心模块 (vde::core)
+ * @brief 点/向量/变换、多边形、凸包、Voronoi、ICP、距离计算
+ */
+
+/**
+ * @defgroup curves 曲线曲面模块 (vde::curves)
+ * @brief Bézier、B-Spline、NURBS 曲线与曲面的求值、求导、细分
+ */
+
+/**
+ * @defgroup mesh 网格模块 (vde::mesh)
+ * @brief 半边网格、Delaunay 2D/3D、简化、平滑、修复、参数化、Marching Cubes
+ */
+
+/**
+ * @defgroup spatial 空间索引模块 (vde::spatial)
+ * @brief BVH (SAH)、Octree、KD-Tree、R-Tree (STR bulk-loading)
+ */
+
+/**
+ * @defgroup boolean 布尔运算模块 (vde::boolean)
+ * @brief 2D Sutherland-Hodgman 裁剪、3D 网格布尔、多边形偏移
+ */
+
+/**
+ * @defgroup collision 碰撞检测模块 (vde::collision)
+ * @brief GJK/EPA、SAT、Möller-Trumbore 射线-三角形、三角-三角交线
+ */
+
+/**
+ * @defgroup brep B-Rep 模块 (vde::brep)
+ * @brief 边界表示建模、STEP/IGES 导入导出、布尔运算、验证、fillet/chamfer/shell
+ */
+
+/**
+ * @defgroup sdf SDF 模块 (vde::sdf)
+ * @brief 隐式建模：15+ 图元、CSG 树、自动微分、梯度优化、SDF→Mesh
+ */
+
+/**
+ * @defgroup sketch 草图模块 (vde::sketch)
+ * @brief 2D 约束求解器
+ */
+
+/**
+ * @defgroup capi C API 模块 (vde::capi)
+ * @brief 纯 C 接口，支持 FFI / 跨语言绑定
+ */
diff --git a/include/vde/spatial/spatial_index.h b/include/vde/spatial/spatial_index.h
index 99122a9..f780559 100644
--- a/include/vde/spatial/spatial_index.h
+++ b/include/vde/spatial/spatial_index.h
@@ -1,3 +1,19 @@
+/**
+ * @file spatial_index.h
+ * @brief 空间索引抽象基类
+ *
+ * 定义所有空间加速结构的统一接口。子类通过不同策略实现
+ * 空间划分与加速查询，在构建效率与查询性能之间做权衡。
+ *
+ * 子类包括：
+ * - BVH:  层次包围盒，适合静态三角形网格
+ * - Octree: 八叉树，适合均匀分布点云
+ * - KDTree: k-d 树，适合维度无关的中规模数据
+ * - RTree:  R 树，适合动态插入删除场景
+ *
+ * @ingroup spatial
+ */
+
 #pragma once
 #include "vde/core/aabb.h"
 #include "vde/core/line.h"
@@ -11,17 +27,91 @@ using core::Point3D;
 using core::Ray3Dd;
 using core::Triangle3D;
 
+/**
+ * @brief 空间索引抽象基类
+ *
+ * 所有空间加速结构（BVH、Octree、KDTree、RTree）的公共接口。
+ * 模板参数 T 为被索引对象类型，需提供以下辅助函数：
+ * - get_position(T) → Point3D  （空间位置）
+ * - get_aabb(T)    → AABB3D   （包围盒，用于范围查询）
+ * - ray_hits_item(T, Ray3Dd) → bool（与射线求交）
+ *
+ * @tparam T 被索引的空间对象类型
+ *
+ * @note 本类为纯虚接口，不可直接实例化
+ */
 template <typename T>
 class SpatialIndex {
 public:
     virtual ~SpatialIndex() = default;
+
+    /**
+     * @brief 批量构建索引
+     *
+     * 清空已有数据，将 items 全部插入并重建索引结构。
+     * 各子类实现不同的构建策略：
+     * - BVH: SAH 启发式自顶向下划分
+     * - KDTree: 中值分割递归构建
+     * - Octree: 自适应八等分递归剖分
+     * - RTree: 批量插入后优化重组
+     *
+     * @param items 待索引的对象数组
+     */
     virtual void build(const std::vector<T>& items) = 0;
+
+    /**
+     * @brief 插入单个对象
+     *
+     * 将 item 加入索引。部分结构（如 BVH）仅支持一次性 build，
+     * 插入后可能需要重建。
+     *
+     * @param item 待插入的空间对象
+     */
     virtual void insert(const T& item) = 0;
+
+    /**
+     * @brief 删除单个对象
+     *
+     * @param item 待删除的空间对象
+     * @return true 删除成功；false 对象不存在
+     */
     virtual bool remove(const T& item) = 0;
+
+    /**
+     * @brief 范围查询：返回与 AABB 相交的所有对象
+     *
+     * @param range 查询的轴对齐包围盒
+     * @return 与 range 相交的对象列表
+     */
     virtual std::vector<T> query_range(const AABB3D& range) const = 0;
+
+    /**
+     * @brief K 近邻查询：返回距 point 最近的 k 个对象
+     *
+     * @param point 查询点
+     * @param k 需要返回的对象数量
+     * @return 按距离升序排列的 k 个最近对象
+     */
     virtual std::vector<T> query_knn(const Point3D& point, size_t k) const = 0;
+
+    /**
+     * @brief 射线查询：返回与射线相交的所有对象
+     *
+     * @param ray 查询射线
+     * @return 按命中距离升序排列的相交对象列表
+     */
     virtual std::vector<T> query_ray(const Ray3Dd& ray) const = 0;
+
+    /**
+     * @brief 清空索引中所有数据
+     */
     virtual void clear() = 0;
+
+    /**
+     * @brief 当前索引中的对象数量
+     *
+     * @return 对象计数
+     */
     virtual size_t size() const = 0;
 };