feat(v5-M2): G2/G3 continuity + surface analysis + extension + N-side fill + advanced blend

M2.1 — G2/G3 连续性分析 (Agent #0):
- surface_continuity.h/.cpp: G0/G1/G2/G3 curve/surface detection
- Weingarten equation for curvature, Frénet frame, zebra stripe
- surface_analysis.h/.cpp: curvature_map, deviation_analysis, curvature_comb
- 24 tests (12 continuity + 12 analysis)

M2.2 — 曲面延伸 + N边填充 (Agent #1):
- surface_extension.h/.cpp: extend_surface(G1/G2), n_sided_fill, blend_surfaces
- Coons patch generalization for N-sided holes
- 16/16 tests passed in Docker container

M2.3 — 高级过渡曲面 (Agent #2):
- advanced_blend.h/.cpp: real implementations replacing stubs
- variable_radius_blend, multi_face_blend, rolling_ball_blend, face_face_blend
- Ball-rolling envelope + corner sphere filling
- 15+ tests with validate() verification

include/vde/brep/advanced_blend.h

@@ -1,8 +1,126 @@
 #pragma once
+/**
+ * @file advanced_blend.h
+ * @brief 高级过渡曲面（Advanced Blend）操作
+ *
+ * 提供多种超出简单恒定半径圆角的过渡曲面算法：
+ * - 沿边变半径过渡（variable_radius_blend）
+ * - 多面同时过渡（multi_face_blend）
+ * - 滚动球算法（rolling_ball_blend）
+ * - 两面间恒定半径过渡（face_face_blend）
+ *
+ * ## 与 fillet/fillet_variable 的关系
+ *
+ * modeling.h 中的 fillet 和 fillet_variable 是面向最终用户的高层 API，
+ * 本模块提供更底层的过渡曲面算法实现。两者可配合使用。
+ *
+ * @ingroup brep
+ */
 #include "vde/brep/brep.h"
 #include <vector>
+
 namespace vde::brep {
-[[nodiscard]] BrepModel variable_radius_blend(const BrepModel& body, int edge_id, double r_start, double r_end);
-[[nodiscard]] BrepModel multi_face_blend(const BrepModel& body, const std::vector<int>& face_ids, double radius);
-[[nodiscard]] BrepModel rolling_ball_blend(const BrepModel& body, int edge_id, double radius);
-} // namespace vde::brep
+
+/**
+ * @brief 沿边变半径过渡
+ *
+ * 沿指定边的参数方向，在 r_start 和 r_end 之间线性插值半径，
+ * 每段独立构建过渡曲面片段，最终拼接为完整过渡。
+ *
+ * 算法：
+ * 1. 定位目标边及其两个邻面
+ * 2. 计算两面法向量及角平分线方向
+ * 3. 沿边曲线采样 N 个截面，每个截面处计算半径和切点
+ * 4. 每相邻两截面间构建一张过渡曲面（NURBS quad patch）
+ * 5. 重建两个邻面，切除过渡区域
+ * 6. 复制未受影响的面，组装壳和体
+ *
+ * @param body 输入实体
+ * @param edge_id 目标边索引
+ * @param r_start 边起点处的过渡半径（≥ 0）
+ * @param r_end 边终点处的过渡半径（≥ 0）
+ * @param samples 沿边的截面采样数（默认 16）
+ * @return 过渡后的新实体
+ *
+ * @pre edge_id 有效，r_start ≥ 0, r_end ≥ 0
+ * @note samples 越大截面过渡越光滑，但面和边数增加
+ */
+[[nodiscard]] BrepModel variable_radius_blend(
+    const BrepModel& body, int edge_id,
+    double r_start, double r_end, int samples = 16);
+
+/**
+ * @brief 多面同时过渡
+ *
+ * 对多个面同时施加恒定半径的过渡处理。每个目标面独立向内偏移，
+ * 目标面之间的交角处构造球面填充，非目标面保持不变。
+ *
+ * 算法：
+ * 1. 对每个目标面，沿面法向量向内偏移半径距离
+ * 2. 检测目标面之间的共享边，在交线处构造圆柱过渡
+ * 3. 检测三面以上交角顶点，用球面贴片填充
+ * 4. 复制非目标面，组装壳和体
+ *
+ * @param body 输入实体
+ * @param face_ids 目标面索引列表
+ * @param radius 过渡半径（> 0）
+ * @return 过渡后的新实体
+ *
+ * @pre face_ids 非空，所有索引有效，radius > 0
+ */
+[[nodiscard]] BrepModel multi_face_blend(
+    const BrepModel& body, const std::vector<int>& face_ids, double radius);
+
+/**
+ * @brief 滚动球算法过渡
+ *
+ * 模拟一个半径为 radius 的球体沿目标边滚动，球体的扫掠包络面即为过渡曲面。
+ * 球体始终保持与边的两个邻面接触，其中心沿边的等距曲线移动。
+ *
+ * 算法：
+ * 1. 计算滚动球中心轨迹（沿边的 offset 曲线，offset = r / cos(half_angle)）
+ * 2. 沿边采样球心位置
+ * 3. 每个球心位置计算球与两面的切点
+ * 4. 相邻截面间构建过渡曲面 patch（近似球体扫掠包络）
+ * 5. 重建邻面、复制非影响面、组装壳和体
+ *
+ * 对直边退化为圆柱过渡，对曲边产生自然的变曲率过渡。
+ *
+ * @param body 输入实体
+ * @param edge_id 目标边索引
+ * @param radius 球体半径（> 0）
+ * @param samples 沿边的球心采样数（默认 20）
+ * @return 过渡后的新实体
+ *
+ * @pre edge_id 有效，radius > 0
+ */
+[[nodiscard]] BrepModel rolling_ball_blend(
+    const BrepModel& body, int edge_id,
+    double radius, int samples = 20);
+
+/**
+ * @brief 两面间恒定半径过渡
+ *
+ * 在两个任意面之间构造恒定半径的过渡曲面。与单边过渡不同，
+ * 此函数处理两个面之间的整个共享或邻近区域。
+ *
+ * 算法：
+ * 1. 找到两面之间的共享边，或确定两面的邻近区域
+ * 2. 沿共享边界计算过渡曲面（恒定半径圆柱面）
+ * 3. 切掉两面在过渡区域的部分
+ * 4. 插入过渡曲面，组装壳和体
+ *
+ * @param body 输入实体
+ * @param face_a 第一个面索引
+ * @param face_b 第二个面索引
+ * @param radius 过渡半径（> 0）
+ * @param samples 沿边界的截面采样数（默认 16）
+ * @return 过渡后的新实体
+ *
+ * @pre face_a 和 face_b 有效，radius > 0
+ */
+[[nodiscard]] BrepModel face_face_blend(
+    const BrepModel& body, int face_a, int face_b,
+    double radius, int samples = 16);
+
+}  // namespace vde::brep