docs: reorganize documentation — developer-friendly structure

New structure:
- docs/index.md — main navigation
- docs/getting-started.md — 5-minute quick start
- docs/guides/module-manual.md — all 11 modules with file listing
- docs/guides/api-usage.md — API reference with code examples
- docs/guides/ — architecture, building, testing, contributing
- docs/reference/ — competitive analysis, gap analysis, versioning
- docs/api/ — Doxygen generated HTML
- docs/archive/ — historical development plans

Old development plans archived. Clean 4-directory layout.

docs/getting-started.md

@@ -0,0 +1,79 @@
+# 快速入门
+
+> 5 分钟跑起 ViewDesignEngine
+
+## 1. 编译
+
+```bash
+# Docker（推荐，开箱即用）
+docker run --rm -v $(pwd):/ws -w /ws vde-builder:latest \
+  bash -c "cmake -B build && cmake --build build -j$(nproc)"
+
+# 本地（需要 CMake 3.16+, GCC 11+/Clang 16+, Eigen3）
+cmake -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build -j$(nproc)
+```
+
+## 2. 运行测试
+
+```bash
+cd build && ctest --output-on-failure -E Benchmark
+```
+
+## 3. 第一个程序
+
+```cpp
+#include <vde/brep/modeling.h>
+#include <vde/brep/brep_boolean.h>
+#include <vde/foundation/io_step.h>
+#include <iostream>
+
+using namespace vde::brep;
+
+int main() {
+    // 创建两个实体
+    auto box = make_box(2, 2, 2);       // 2×2×2 立方体
+    auto sphere = make_sphere(1.5, 32);  // 半径1.5球体
+
+    // 布尔并集
+    auto result = brep_union(box, sphere);
+
+    // 验证结果
+    auto report = validate(result);
+    std::cout << "Faces: " << result.num_faces()
+              << " Valid: " << report.valid << std::endl;
+
+    // 导出 STEP
+    export_step_file(result, "output.step");
+
+    return 0;
+}
+```
+
+编译运行：
+```bash
+g++ -std=c++17 -I include -L build/src \
+    my_program.cpp -lvde_brep -lvde_curves -lvde_foundation \
+    -lvde_core -o my_program
+./my_program
+```
+
+## 4. 核心头文件速查
+
+| 功能 | 头文件 | 关键 API |
+|------|--------|---------|
+| 创建基本体 | `vde/brep/modeling.h` | `make_box`, `make_cylinder`, `make_sphere` |
+| 布尔运算 | `vde/brep/brep_boolean.h` | `brep_union`, `brep_intersection`, `brep_difference` |
+| 拓扑修复 | `vde/brep/brep_heal.h` | `heal_topology`, `heal_gaps` |
+| 验证 | `vde/brep/brep_validate.h` | `validate` |
+| STEP 读写 | `vde/foundation/io_step.h` | `import_step_file`, `export_step_file` |
+| 网格转换 | `vde/brep/brep.h` | `body.to_mesh()` |
+| SDF 建模 | `vde/sdf/sdf_tree.h` | SDF 隐式曲面 |
+| CAM 加工 | `vde/core/cam_strategies.h` | `roughing_toolpath`, `finishing_toolpath` |
+| 装配体 | `vde/brep/assembly.h` | `Assembly`, `AssemblyNode` |
+
+## 5. 下一步
+
+- [模块说明书](guides/module-manual.md) — 了解所有模块的能力
+- [API 使用手册](guides/api-usage.md) — 详细 API 使用示例
+- [examples/](../examples/) — 完整可运行示例

docs/guides/api-usage.md

@@ -0,0 +1,267 @@
+# API 使用手册
+
+> 常用 API 速查与代码示例
+
+## 命名约定
+
+```cpp
+namespace vde::brep   { /* B-Rep 建模 */ }
+namespace vde::curves { /* 曲线曲面 */ }
+namespace vde::mesh   { /* 网格处理 */ }
+namespace vde::core   { /* 基础类型 */ }
+namespace vde::foundation { /* IO格式 */ }
+
+// 基础类型
+using core::Point3D;    // 3D点，.x() .y() .z()
+using core::Vector3D;   // 3D向量，.dot() .cross() .norm() .normalized()
+using core::AABB3D;     // 包围盒，.min() .max() .extent() .intersects() .expand()
+```
+
+---
+
+## B-Rep 建模
+
+### 创建基本体
+
+```cpp
+#include <vde/brep/modeling.h>
+using namespace vde::brep;
+
+auto box     = make_box(2, 3, 4);         // 宽×深×高
+auto cyl     = make_cylinder(1.5, 6, 32); // 半径, 高度, 分段
+auto sphere  = make_sphere(2, 32, 16);    // 半径, u分段, v分段
+
+// 查询
+size_t n_faces = box.num_faces();
+auto bb = box.bounds();                   // AABB3D
+auto mesh = box.to_mesh(0.01);            // HalfedgeMesh
+```
+
+### 布尔运算
+
+```cpp
+#include <vde/brep/brep_boolean.h>
+
+auto result_union        = brep_union(a, b);
+auto result_intersection = brep_intersection(a, b);
+auto result_difference   = brep_difference(a, b);
+```
+
+### 拓扑修复与验证
+
+```cpp
+#include <vde/brep/brep_heal.h>
+#include <vde/brep/brep_validate.h>
+
+heal_topology(body);           // 一站式修复
+heal_gaps(body, 1e-6);        // 合并临近顶点
+heal_orientation(body);       // 统一面方向
+
+auto report = validate(body);  // 验证
+// report.valid, report.errors, report.warnings
+```
+
+### 直接建模
+
+```cpp
+#include <vde/brep/direct_modeling.h>
+
+push_pull(body, face_id, 5.0);   // 挤出5mm
+tweak_face(body, face_id, 2.0);  // 面偏移2mm
+move_face(body, face_id, transform);
+scale_body(body, {2, 1, 1});     // X方向放大2倍
+mirror_body(body, plane);        // 镜像
+```
+
+---
+
+## 曲线曲面
+
+### NURBS 曲面操作
+
+```cpp
+#include <vde/curves/nurbs_surface.h>
+#include <vde/curves/generative_surfaces.h>
+using namespace vde::curves;
+
+// 创建
+auto ruled  = NurbsSurface::ruled(curve1, curve2);
+auto rev    = NurbsSurface::revolve(profile, origin, axis, M_PI);
+
+// 求值
+Point3D p = surf.evaluate(0.5, 0.5);
+Vector3D n = surf.normal(0.5, 0.5);
+
+// 生成曲面
+auto swept = sweep_surface(profile, path, SweepMode::Explicit);
+auto lofted = loft_surface(sections);       // 放样
+auto netted = net_surface(u_curves, v_curves); // 网格面
+```
+
+### 曲面编辑
+
+```cpp
+#include <vde/curves/surface_editing.h>
+
+auto matched = match_surface(target, reference, edge, Continuity::G2);
+auto edited  = control_point_edit(surf, {0,0}, new_pos);
+```
+
+### 曲面分析
+
+```cpp
+#include <vde/curves/surface_analysis.h>
+#include <vde/curves/surface_continuity.h>
+
+auto cmap = curvature_map(surf, 64, 64);     // 曲率图
+auto zebra = zebra_stripe(surf, light_dir);   // 斑马纹
+auto cont = surface_continuity(a, b, edge);   // 连续性分析
+```
+
+---
+
+## 格式 IO
+
+### STEP/IGES
+
+```cpp
+#include <vde/foundation/io_step.h>
+#include <vde/foundation/io_iges.h>
+
+auto body = import_step_file("input.step");
+auto body = import_step_string(step_data);
+export_step_file(body, "output.step");
+
+auto body = import_iges_file("input.igs");
+export_iges_file(body, "output.igs");
+```
+
+### 工业格式
+
+```cpp
+#include <vde/foundation/industrial_formats.h>
+using namespace vde::io;
+
+auto body  = import_parasolid_xt("model.x_t");  // Parasolid XT
+auto body  = import_acis_sat("model.sat");       // ACIS SAT
+auto body  = import_jt("model.jt");              // JT
+auto body  = import_ifc("building.ifc");         // IFC
+export_jt(body, "output.jt");
+```
+
+### 网格格式
+
+```cpp
+// STL/OBJ/PLY/glTF/3MF 均在 foundation 模块
+#include <vde/foundation/io_stl.h>
+#include <vde/foundation/io_gltf.h>
+
+export_stl_binary(mesh, "output.stl");
+export_gltf(mesh, "output.glb");   // glTF Binary
+```
+
+---
+
+## CAM 加工
+
+```cpp
+#include <vde/core/cam_strategies.h>
+#include <vde/core/cam_5axis.h>
+using namespace vde::core;
+
+Tool tool{ToolType::ENDMILL, 10.0, 4, 50.0};  // 直径10mm 4刃
+
+// 3轴
+auto rough = roughing_toolpath(body, tool, RoughingParams{});
+auto finish = finishing_toolpath(body, tool, FinishingParams{});
+auto drill = drilling_toolpath(points, tool, {5, 10, 15});
+
+// 5轴
+auto swarf = swarf_machining(surface, tool, SwarfParams{});
+auto m5 = multi_axis_finishing(surface, tool, MultiAxisParams{});
+
+// 后处理
+FanucPost post;
+auto gcode = post.generate(toolpath);
+```
+
+---
+
+## 装配体
+
+```cpp
+#include <vde/brep/assembly.h>
+#include <vde/brep/constraint_solver.h>
+
+Assembly assy{"robot_arm"};
+assy.root().add_part("base", make_box(10, 10, 2));
+auto* arm = assy.root().add_subassembly("arm", Transform3D::Translation(0,0,2));
+arm->add_part("link", make_cylinder(0.5, 8));
+
+// 约束
+ConstraintGraph graph;
+graph.add_constraint("base", "arm", ConstraintType::Coincident, ...);
+solve_constraints(graph);
+```
+
+---
+
+## 网格处理
+
+```cpp
+#include <vde/mesh/halfedge_mesh.h>
+#include <vde/mesh/mesh_simplify.h>
+#include <vde/mesh/marching_cubes.h>
+
+// 简化
+auto simplified = simplify_mesh(mesh, 0.5);  // 保留50%面
+
+// 平滑
+auto smoothed = laplacian_smooth(mesh, 10);
+
+// SDF → Mesh
+auto mesh = marching_cubes(sdf_function, bounds, 64);
+
+// FEA网格
+auto tets = tetrahedral_mesh(body, TetraParams{});
+auto hex = mapped_hex_mesh(body, source_face, target_face);
+```
+
+---
+
+## 点云/逆向工程
+
+```cpp
+#include <vde/mesh/point_cloud.h>
+#include <vde/mesh/reverse_engineering.h>
+
+PointCloud cloud;
+cloud.load_ply("scan.ply");
+cloud.voxel_downsample(0.5);
+cloud.estimate_normals(16);
+
+auto mesh = point_cloud_to_mesh(cloud);
+auto surf = mesh_to_nurbs_surface(mesh);
+```
+
+---
+
+## 性能调优
+
+```cpp
+#include <vde/core/performance_tuning.h>
+
+// 设置线程数
+set_parallel_threads(8);
+
+// 使用内存池
+ObjectPool<Point3D> pool;
+auto* p = pool.acquire();
+pool.release(p);
+
+// 事务
+Transaction txn;
+txn.begin();
+// ... 操作 ...
+txn.commit();  // 或 txn.rollback();
+```

docs/guides/module-manual.md

@@ -0,0 +1,125 @@
+# 模块功能说明书
+
+> ViewDesignEngine v1.0.0-beta.1 · 11 模块
+
+## foundation — 基础设施 + 格式 IO
+
+| 文件 | 功能 |
+|------|------|
+| `tolerance.h/cpp` | 容差系统（全局/局部/PerFace/ToleranceChain/自适应） |
+| `exact_predicates.h/cpp` | GMP精确谓词（orient2d/3d, in_sphere, point_in_polygon/polyhedron） |
+| `io_step.h/cpp` | STEP AP203/214/242 导入导出 |
+| `io_iges.h/cpp` | IGES 5.3 导入导出 |
+| `io_obj/io_stl/io_ply.h/cpp` | OBJ/STL/PLY 网格格式 |
+| `io_gltf.h/cpp` | glTF 2.0 / GLB 导出 |
+| `io_3mf.h/cpp` | 3MF 3D打印格式 |
+| `industrial_formats.h/cpp` | Parasolid XT/SAT/JT/IFC/PDF3D |
+
+## core — 几何核心 + CAM + 性能
+
+| 文件 | 功能 |
+|------|------|
+| `polygon.h/cpp` | 多边形操作、三角剖分、凸包、简化 |
+| `distance.h/cpp` | 点/线/面/体距离计算 |
+| `convex_hull.h/cpp` | 2D/3D 凸包 |
+| `icp.h/cpp` | 迭代最近点配准 |
+| `cam_toolpath.h/cpp` | 基础CAM刀路（轮廓/型腔） |
+| `cam_strategies.h/cpp` | 高级CAM（粗/精/钻+刀库+8后处理） |
+| `cam_5axis.h/cpp` | 5轴加工（侧刃/3+2/机床运动学） |
+| `cam_advanced.h/cpp` | 自适应/摆线/残料/清根/HSM |
+| `cam_optimization.h/cpp` | 切屑减薄/恒接触/刀具寿命/进给优化 |
+| `simd_vector.h` | SIMD向量（SSE/AVX/NEON自适应） |
+| `concurrent_data.h/cpp` | 无锁数据结构（Queue/Stack/HashMap） |
+| `transaction.h/cpp` | 事务/Command/UndoManager |
+| `performance_tuning.h/cpp` | NUMA/缓存对齐/内存池集成 |
+| `topology_compression.h/cpp` | B-Rep拓扑压缩/Edgebreaker |
+
+## curves — 曲线曲面
+
+| 文件 | 功能 |
+|------|------|
+| `nurbs_curve.h/cpp` | NURBS曲线（求值/导数/节点操作） |
+| `nurbs_surface.h/cpp` | NURBS曲面（ruled/revolve/tessellate） |
+| `nurbs_operations.h/cpp` | 高级NURBS（trim/blend/offset/extrude） |
+| `surface_continuity.h/cpp` | G0-G3连续性分析 |
+| `surface_analysis.h/cpp` | 曲率图/斑马纹/高光线/反射线/等照度/拐点线/棋盘格 |
+| `surface_extension.h/cpp` | 曲面延伸/N边填充/过渡 |
+| `generative_surfaces.h/cpp` | Sweep(3模式)/Loft/Net Surface |
+| `surface_editing.h/cpp` | Match Surface(G0-G3)/曲面编辑 |
+| `control_point_edit.h/cpp` | 控制点编辑 |
+| `curve_tools.h/cpp` | 投影/偏移/连接/螺旋线/等参线 |
+| `class_a_surfacing.h/cpp` | A级曲面（G3过渡/能量最小化/曲率优化） |
+| `advanced_intersection.h/cpp` | 鲁棒SSI（三阶段）/自交检测 |
+| `surface_intersection.h/cpp` | 曲面-曲面/曲线-曲面求交 |
+| `iga_prep.h/cpp` | IGA分析准备（节点插入/升阶/Bezier提取） |
+
+## mesh — 网格处理
+
+| 文件 | 功能 |
+|------|------|
+| `halfedge_mesh.h/cpp` | 半边数据结构 |
+| `delaunay_2d.h/cpp` | 2D Delaunay三角剖分 |
+| `delaunay_3d.h/cpp` | 3D Delaunay四面体剖分 |
+| `mesh_simplify.h/cpp` | QEM网格简化 |
+| `mesh_smooth.h/cpp` | Laplacian/Taubin/HC/Bilateral平滑 |
+| `mesh_boolean.h/cpp` | 网格布尔运算 |
+| `mesh_quality.h/cpp` | 网格质量评估 |
+| `marching_cubes.h/cpp` | Marching Cubes等值面提取 |
+| `mesh_lod.h/cpp` | LOD网格生成 |
+| `fea_mesh.h/cpp` | FEA网格（四面体/边界层/六面体） |
+| `reverse_engineering.h/cpp` | 逆向工程（点云→网格→NURBS） |
+| `point_cloud.h/cpp` | 点云处理（降采样/法线估计/滤波） |
+| `visualization_quality.h/cpp` | AO/边高亮/法线可视化 |
+
+## spatial + boolean + collision — 空间索引与运算
+
+| 文件 | 功能 |
+|------|------|
+| `bvh.h/cpp` | BVH (SAH构建) |
+| `octree.h/cpp` | 八叉树 |
+| `kd_tree.h/cpp` | KD-Tree (kNN/射线) |
+| `r_tree.h/cpp` | R-Tree (STR bulk-loading) |
+| `boolean_2d.h/cpp` | 2D布尔（Sutherland-Hodgman） |
+| `boolean_mesh.h/cpp` | 3D网格布尔（并/交/差/对称差） |
+| `gjk.h/cpp` | GJK/EPA碰撞检测 |
+| `ray_intersect.h/cpp` | Möller-Trumbore射线-三角形 |
+
+## brep — B-Rep 核心
+
+| 文件 | 功能 |
+|------|------|
+| `brep.h/cpp` | B-Rep数据结构（V/E/L/F/S/B + TrimmedSurface） |
+| `modeling.h/cpp` | 高层建模（make_box/cylinder/sphere/extrude等） |
+| `brep_boolean.h/cpp` | SSI布尔运算 |
+| `brep_heal.h/cpp` | 拓扑修复（gaps/slivers/orientation/topology） |
+| `brep_validate.h/cpp` | B-Rep验证 |
+| `tolerant_modeling.h/cpp` | 容错建模 |
+| `direct_modeling.h/cpp` | 直接建模（push_pull/tweak/move/replace/offset） |
+| `ffd_deformation.h/cpp` | FFD自由变形 |
+| `sheet_metal.h/cpp` | 钣金（展开/法兰/K-factor） |
+| `advanced_blend.h/cpp` | 高级过渡（变半径/多面/滚动球） |
+| `feature_recognition.h/cpp` | 特征识别（孔/槽/倒圆/凸台） |
+| `defeature.h/cpp` | 去特征化 |
+| `gdt.h/cpp` | GD&T 14种符号 |
+| `auto_dimensioning.h/cpp` | 自动标注 |
+| `pmi_mbd.h/cpp` | PMI/MBD 3D标注 |
+| `drawing_standards.h/cpp` | ISO/ANSI/JIS制图标准 |
+| `assembly.h/cpp` | 装配体 |
+| `constraint_solver.h/cpp` | 3D约束求解（Newton-Raphson） |
+| `interference_check.h/cpp` | 干涉检查 |
+| `motion_simulation.h/cpp` | 运动仿真 |
+| `explode_view.h/cpp` | 爆炸视图 |
+| `assembly_lod.h/cpp` | 大装配LOD |
+| `assembly_patterns.h/cpp` | 装配阵列 |
+| `quality_feedback.h/cpp` | 设计规则检查/可制造性/成本/质量评分 |
+| `euler_op.h/cpp` | 欧拉操作（6原语） |
+
+## sdf — 隐式建模
+
+| 文件 | 功能 |
+|------|------|
+| `sdf_primitives.h/cpp` | 15+隐式图元 |
+| `sdf_tree.h/cpp` | CSG树操作 |
+| `sdf_to_mesh.h/cpp` | SDF→Mesh转换 |
+| `sdf_optimize.h/cpp` | 梯度优化 |
+| `sdf_torch.h/cpp` | Torch集成 |

docs/index.md

@@ -0,0 +1,59 @@
+# ViewDesignEngine 文档
+
+> v1.0.0-beta.1 · C++17 B-Rep 几何引擎 · Apache 2.0
+
+## 快速导航
+
+| 你想做什么？ | 去看 |
+|-------------|------|
+| 快速上手编译运行 | [快速入门](getting-started.md) |
+| 了解每个模块能做什么 | [模块说明书](guides/module-manual.md) |
+| 学习如何使用 API | [API 使用手册](guides/api-usage.md) |
+| 查看代码示例 | [教程](guides/) + [examples/](../examples/) |
+| 了解架构和贡献 | [架构概览](guides/architecture.md) · [贡献指南](guides/contributing.md) |
+| 了解与竞品的差距 | [竞品分析](reference/27-竞品分析.md) · [严谨差距分析](reference/30-严谨差距分析.md) |
+| 查看 API 详细定义 | [Doxygen API 文档](api/html/index.html) |
+| 了解版本号规则 | [版本管理规范](reference/VERSIONING.md) |
+| 查看更新历史 | [CHANGELOG](../CHANGELOG.md) |
+
+## 项目简介
+
+ViewDesignEngine 是一个 C++17 全栈 B-Rep 几何引擎，对标 Parasolid/ACIS。
+
+```
+11 模块 · 129 源文件 · 0 编译错误 · Apache 2.0
+```
+
+### 核心能力
+
+| 领域 | 能力 |
+|------|------|
+| **B-Rep** | 拓扑建模、SSI布尔、容错建模、直接建模、钣金、FFD |
+| **曲面** | NURBS、G0-G3连续、Sweep/Loft/Net、曲面分析 |
+| **网格** | Delaunay、QEM、MC、FEA网格、逆向工程 |
+| **格式** | STEP/IGES/XT/SAT/JT/IFC/glTF/STL/OBJ/PLY/3MF |
+| **CAM** | 3轴/5轴加工、HSM、刀库、8种后处理器 |
+| **工程图** | 投影/剖视、HLR、自动标注、GD&T、PMI/MBD |
+| **装配** | 约束求解、干涉检查、运动仿真、大装配LOD |
+
+### 目录结构
+
+```
+docs/
+├── index.md              ← 你在这里
+├── getting-started.md    ← 5分钟快速上手
+├── api/                  ← Doxygen 生成的 API 文档
+├── guides/               ← 开发者指南
+│   ├── module-manual.md  ← 模块功能说明书
+│   ├── api-usage.md      ← API 使用手册
+│   ├── architecture.md   ← 架构概览
+│   ├── building.md       ← 构建指南
+│   ├── testing.md        ← 测试指南
+│   └── contributing.md   ← 贡献指南
+├── reference/            ← 参考资料
+│   ├── 27-竞品分析.md
+│   ├── 30-严谨差距分析.md
+│   ├── API-REFERENCE.md
+│   └── VERSIONING.md
+└── archive/              ← 历史开发计划
+```