# ViewDesignEngine 开发者指南

欢迎来到 ViewDesignEngine (VDE) 开发者文档。本指南面向希望理解 VDE 内部架构、贡献代码或基于 VDE 构建应用的开发者。

## 文档导航

| 文档 | 说明 |
|------|------|
| [架构概览](architecture.md) | 模块依赖关系图、数据流、分层架构设计 |
| [API 总览](api-overview.md) | 公开 API 接口一览、命名空间规范、核心类型 |
| [构建指南](building.md) | 从源码构建、Docker 环境、CMake 选项、依赖管理 |
| [测试指南](testing.md) | 测试框架、编写测试、运行测试、覆盖率 |
| [贡献指南](contributing.md) | 代码规范、提交流程、Code Review、分支策略 |
| [插件系统设计](plugin-system.md) | 插件架构、生命周期、动态加载、清单文件 |

## 快速开始

```bash
# 克隆仓库
git clone ssh://git@localhost:22/hm/ViewDesignEngine.git
cd ViewDesignEngine

# Docker 构建（推荐）
docker run --rm -v $PWD:/ws vde-builder:latest bash -c \
  "cd /ws && cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j\$(nproc)"

# 本地构建
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)

# 运行测试
cd build && ctest --output-on-failure
```

## 项目结构

```
ViewDesignEngine/
├── CMakeLists.txt          # 顶层 CMake
├── cmake/                  # CMake 模块 (CompilerSettings 等)
├── include/vde/            # 公开头文件
│   ├── foundation/         #   基础数学、I/O、公差
│   ├── core/               #   几何核心、CAM
│   ├── curves/             #   曲线曲面
│   ├── mesh/               #   网格处理
│   ├── spatial/            #   空间索引
│   ├── boolean/            #   布尔运算
│   ├── collision/          #   碰撞检测
│   ├── brep/               #   B-Rep 建模
│   ├── sdf/                #   SDF 隐式建模
│   ├── sketch/             #   草图约束
│   └── plugin/             #   插件系统 (v6.0+)
├── src/                    # 实现文件（按模块分目录）
├── tests/                  # 单元测试
├── bench/                  # 性能基准
├── examples/               # 示例程序
├── python/                 # Python 绑定
└── docs/                   # 文档
```

## 关键概念

### 命名空间

所有 VDE 代码位于 `vde::` 命名空间下，按模块分子命名空间：

```cpp
namespace vde::foundation { /* 基础设施 */ }
namespace vde::core        { /* 几何核心 */ }
namespace vde::curves      { /* 曲线曲面 */ }
namespace vde::mesh        { /* 网格处理 */ }
namespace vde::spatial     { /* 空间索引 */ }
namespace vde::boolean      { /* 布尔运算 */ }
namespace vde::collision   { /* 碰撞检测 */ }
namespace vde::brep        { /* B-Rep 建模 */ }
namespace vde::sdf         { /* SDF 隐式建模 */ }
namespace vde::sketch      { /* 草图约束 */ }
namespace vde::plugin      { /* 插件系统 */ }
```

### 依赖关系

- **L0 foundation**: 零上游依赖（仅 Eigen）
- **L1 core**: 依赖 foundation
- **L2 curves**: 依赖 core
- **L3 mesh**: 依赖 core + brep
- **L4 spatial**: 依赖 core
- **L5 boolean/collision**: 依赖 L1-L4
- **brep**: 依赖 curves + mesh + collision
- **sdf**: 依赖 core + mesh
- **plugin**: 依赖 foundation（独立于其他模块）

### 设计原则

1. **零开销抽象** — 模板与编译期多态，避免不必要的虚函数
2. **数据驱动** — SoA 布局优化缓存命中率
3. **不可变优先** — 几何实体默认不可变，变换返回新实体
4. **RAII 资源管理** — 智能指针管理所有资源
5. **单一依赖** — 仅依赖 Eigen，不引入 Boost

## 相关文档

- [项目开发计划](../00-开发计划.md)
- [系统架构设计](../02-概要设计/01-系统架构设计.md)
- [CHANGELOG](../../CHANGELOG.md)
- [API 参考手册](../API-REFERENCE.md)