# 系统架构设计

## 目录

1. [整体架构](#1-整体架构)
2. [模块层次](#2-模块层次)
3. [数据流](#3-数据流)
4. [设计原则](#4-设计原则)

---

## 1. 整体架构

```
┌─────────────────────────────────────────────────────────┐
│                    公开 API 层                           │
│      （C++ 头文件，稳定 ABI，Doxygen 文档）               │
├─────────────────────────────────────────────────────────┤
│  ┌─────────┐ ┌──────────┐ ┌────────┐ ┌──────────────┐  │
│  │  几何   │ │ 曲线曲面 │ │ 网格   │ │   空间索引   │  │
│  │  核心   │ │   建模   │ │ 处理   │ │              │  │
│  └────┬────┘ └────┬─────┘ └───┬────┘ └──────┬───────┘  │
│       │           │           │              │           │
│  ┌────┴───────────┴───────────┴──────────────┴───────┐  │
│  │                 CSG 布尔引擎                       │  │
│  └────────────────────────┬──────────────────────────┘  │
│  ┌────────────────────────┴──────────────────────────┐  │
│  │                  碰撞检测层                        │  │
│  └────────────────────────────────────────────────────┘  │
├─────────────────────────────────────────────────────────┤
│                    基础设施层                            │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐   │
│  │  数学库  │ │ 公差系统 │ │   I/O    │ │ 内存管理 │   │
│  │ (Eigen)  │ │          │ │(OBJ/STL) │ │          │   │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘   │
└─────────────────────────────────────────────────────────┘
```

---

## 2. 模块层次

| 层级 | 模块 | 命名空间 | 职责 |
|------|------|---------|------|
| L0 基础设施 | foundation | `vde::foundation` | 数学库封装、精确谓词、内存管理、I/O |
| L1 几何核心 | core | `vde::core` | 基本几何类型、变换、距离计算、凸包 |
| L2 曲线曲面 | curves | `vde::curves` | Bezier/B-Spline/NURBS 曲线与曲面 |
| L3 网格处理 | mesh | `vde::mesh` | 网格数据结构、剖分、简化、平滑 |
| L4 空间索引 | spatial | `vde::spatial` | BVH、Octree、KD-Tree、R-Tree |
| L5 布尔运算 | boolean | `vde::boolean` | 2D/3D CSG 布尔运算 |
| L5 碰撞检测 | collision | `vde::collision` | GJK、SAT、射线相交 |

**依赖规则**：
- 上层可依赖下层，下层不依赖上层
- 同层模块间通过接口抽象解耦
- L5 层（布尔运算/碰撞检测）依赖 L1-L4

---

## 3. 数据流

```
输入数据 (OBJ/STL/STEP)
    │
    ▼
[ I/O 解析 ] ──► 几何核心（基本实体）
    │
    ▼
[ 曲线曲面建模 ] ──► 离散化 ──► [ 网格处理 ]
    │                              │
    ▼                              ▼
[ CSG 布尔 ] ◄──────────── [ 空间索引 ]
    │
    ▼
输出数据 (OBJ/STL/B-Rep)
```

---

## 4. 设计原则

1. **零开销抽象**：模板与编译期多态，不引入不必要的虚函数开销
2. **数据驱动**：使用 SoA（数组结构体）布局优化缓存命中率
3. **不可变优先**：几何实体默认不可变，变换操作返回新实体
4. **RAII 资源管理**：所有资源由智能指针管理
5. **异常安全**：提供基本保证以上，核心路径提供强保证
6. **单一依赖**：仅依赖 Eigen，不引入 Boost 等重型库