# 接口定义

## 目录

1. [命名约定](#1-命名约定)
2. [核心接口抽象](#2-核心接口抽象)
   - 2.1 空间索引接口
   - 2.2 曲线求值接口
   - 2.3 网格数据结构接口
   - 2.4 布尔运算接口
3. [稳定 C API（可选）](#3-稳定-c-api可选)
4. [错误处理约定](#4-错误处理约定)

---

## 1. 命名约定

| 元素 | 风格 | 示例 |
|------|------|------|
| 命名空间 | snake_case | `vde::core` |
| 类/结构体 | PascalCase | `HalfedgeMesh` |
| 函数/方法 | snake_case | `compute_convex_hull()` |
| 变量 | snake_case | `vertex_count` |
| 成员变量 | snake_case_ | `vertices_` |
| 常量 | UPPER_SNAKE_CASE | `MAX_ITERATIONS` |
| 枚举值 | kPascalCase | `kSuccess` |
| 宏前缀 | VDE_ | `VDE_VERSION_MAJOR` |

---

## 2. 核心接口抽象

### 2.1 空间索引接口

```cpp
namespace vde::spatial {

template <typename T>
class SpatialIndex {
public:
    virtual ~SpatialIndex() = default;
    virtual void build(const std::vector<T>& items) = 0;
    virtual void insert(const T& item) = 0;
    virtual bool remove(const T& item) = 0;
    virtual std::vector<T> query_range(const AABB3D& range) const = 0;
    virtual std::vector<T> query_knn(const Point3D& point, size_t k) const = 0;
    virtual std::vector<T> query_ray(const Ray3Dd& ray) const = 0;
    virtual void clear() = 0;
    virtual size_t size() const = 0;
};

}
```

### 2.2 曲线求值接口

```cpp
namespace vde::curves {

template <typename T, size_t Dim>
class CurveBase {
public:
    virtual ~CurveBase() = default;
    virtual int degree() const = 0;
    virtual std::pair<double, double> domain() const = 0;
    virtual Point<T, Dim> evaluate(double t) const = 0;
    virtual Vector<T, Dim> derivative(double t, int order = 1) const = 0;
    virtual const std::vector<Point<T, Dim>>& control_points() const = 0;
};

}
```

### 2.3 网格数据结构接口

```cpp
namespace vde::mesh {

class MeshBase {
public:
    virtual ~MeshBase() = default;
    virtual size_t num_vertices() const = 0;
    virtual size_t num_faces() const = 0;
    virtual const Point3D& vertex(size_t idx) const = 0;
    virtual std::vector<size_t> vertex_faces(size_t idx) const = 0;
    virtual Vector3D face_normal(size_t idx) const = 0;
    virtual Vector3D vertex_normal(size_t idx) const = 0;
    virtual bool is_boundary_vertex(size_t idx) const = 0;
    virtual void update_normals() = 0;
};

}
```

### 2.4 布尔运算接口

```cpp
namespace vde::boolean {

enum class BooleanOp { Union, Intersection, Difference, SymDiff };

template <typename GeometryType>
class BooleanEngine {
public:
    virtual ~BooleanEngine() = default;
    virtual GeometryType execute(
        const GeometryType& a, const GeometryType& b, BooleanOp op) = 0;
    virtual void set_tolerance(double tol) = 0;
};

}
```

---

## 3. 稳定 C API（可选）

为跨语言绑定提供纯 C 接口：

```c
// 创建与销毁上下文
vde_ctx_t vde_engine_create(void);
void vde_engine_destroy(vde_ctx_t ctx);

// 布尔运算
vde_mesh_t vde_boolean_union(vde_ctx_t ctx, vde_mesh_t a, vde_mesh_t b);

// 网格简化
vde_mesh_t vde_mesh_simplify(vde_ctx_t ctx, vde_mesh_t m, double ratio);
```

---

## 4. 错误处理约定

- 所有公开 API 返回值使用 `Result<T>` 类型（`std::expected<T, ErrorCode>` 的兼容实现）
- 错误码枚举定义于 `vde/foundation/error_codes.h`
- 内部实现可使用断言（`assert`），但公开 API 不抛异常
- `using Result<T> = tl::expected<T, ErrorCode>;`

| 错误码 | 说明 |
|--------|------|
| `kSuccess` | 操作成功 |
| `kInvalidArgument` | 非法参数 |
| `kInvalidGeometry` | 非法几何（退化/非流形） |
| `kDegenerateCase` | 退化情况 |
| `kNotImplemented` | 未实现 |
| `kNumericalError` | 数值计算错误 |