# 项目定位与范围

## 一句话定位

MoonBit CAD Sketch 是面向 MoonBit 应用开发者的小型二维参数化草图约束求解库：将点、线、圆及设计关系转换为非线性方程，求解坐标与半径，并提供尺寸编辑后的重新求解和约束诊断。

模块名为 `mik1e80/cad_sketch`。核心库使用纯 MoonBit 实现，仅依赖 MoonBit core，支持 wasm、wasm-gc、JS 和 native。当前源码版本为 `0.2.1`，发布状态以 [README](QUICK_START.md#安装与版本) 为准。

## 面向谁，解决什么问题

| 目标用户 | 具体需求 | 本项目提供的能力 |
| --- | --- | --- |
| 参数化零件工具开发者 | 改宽度、孔距、对称轴或半径后，按已有设计关系更新关联几何 | 点、线、圆建模；距离、方向、对称、相切等 24 种约束；修改约束后重新求解 |
| 草图编辑器和工程工具开发者 | 在自己的界面中连接几何、参数编辑与诊断 | 稳定的草图内句柄、约束启停、逐约束残差、局部自由度及求解状态 |
| 几何与机构教学工具开发者 | 展示几何关系、参数变化和机构构型 | 可检查的求解结果、轨迹图、四杆机构连续角度驱动案例与回归测试 |

这些用户需要把设计关系表达为约束。例如，两孔关于一条直线对称且等半径时，可以组合圆心的 `Mirror` 与圆的 `EqualRadius`；移动对称轴后继续求解，无需在应用中另写一套孔位联动公式。

## 核心价值

- **在 MoonBit 应用内完成求解**：核心求解过程不依赖 C/C++ 求解器、FFI 或 JavaScript 数学库。
- **按关系编辑几何**：尺寸、方向、对称和相切关系共同参与求解，支持修改已有约束及临时启停。
- **让结果可检查**：返回每条约束的残差、求解状态和局部自由度；调用者可以将诊断映射回草图对象。

这里的价值来自当前接口与实现，不包含尚未测量的性能优势或对任意草图的收敛保证。变量建模、自动微分、阻尼迭代与 QR 求解详见 [技术路径说明](ARCHITECTURE.md)。

## 典型使用流程与现有证据

1. 创建 `Sketch`，添加点、线、圆，并设置接近目标构型的初始几何。
2. 添加定位和设计关系，保存需要编辑的约束句柄。
3. 调用 `solve()` 检查结果，或使用 `solve_and_apply()` 在全部约束达到容差时更新几何。
4. 使用 `set_constraint()` 修改尺寸，再次求解；使用 `set_constraint_enabled()` 暂停或恢复某条关系。
5. 读取状态和逐约束残差，定位当前未满足的关系；若本次未成功应用，保留上一次成功几何以供继续编辑。

| 入口 | 已有验证内容 |
| --- | --- |
| [公开接口示例](../README.mbt.md) | 带尺寸线段的重复求解、冲突约束启停、直线轴对称 |
| [基础示例](../examples/basic/main.mbt) | 矩形改尺寸、三角形、两圆外切与矛盾约束 |
| [编辑示例](../cmd/edit_demo/main.mbt) | 中心对称、偏移、长度比例、内切圆、冲突恢复与解析坐标 |
| [镜像孔位示例](../examples/mirror_holes/main.mbt) | 等半径孔位、移动对称轴后的联动、冲突时保留几何 |
| [参数化安装板](SHOWCASE.md) | 同一草图修改板宽、孔半径与孔心边距，生成前后对比图；独立核对四孔坐标、句柄和失败恢复 |
| [四杆机构案例](../examples/four_bar/README.md) | 固定支点、25 个往返角度驱动姿态、分支与杆长检查、轨迹图和 CSV；原 21 步回归保留在 numerics_wbtest.mbt |

## 当前能力边界

- **几何和关系**：点、线段、圆及 24 种等式约束。点在线上、点线距离、线圆相切和镜像轴按无限延伸直线计算。
- **规模**：最多 256 个标量变量、512 条线、512 条现存约束。点占两个变量，圆半径另占一个变量；禁用约束仍占名额，永久删除释放名额，累计创建编号不复用。这是输入上限，实际性能需由 Benchmark 测量。
- **编辑行为**：提供尺寸修改、约束启停和[永久删除](CONSTRAINT_LIFECYCLE.md)，保留其他关系的稳定编号。每次求解重新线性化，使用稠密矩阵，尚无稀疏增量求解、几何对象删除或拖拽优先级。
- **收敛条件**：局部非线性迭代依赖初值、构型、尺度和容差。未收敛不证明无解；当前未满足关系也不是经过证明的最小冲突集。
- **诊断含义**：`local_dof` 是返回构型下雅可比的一阶数值估计，不能证明全局刚性；欠约束时也不保证结果离初值最近。
- **应用交付**：核心库提供建模、求解和诊断，命令行示例展示典型编辑流程。完整 CAD 编辑器、模型持久化、DXF 导入导出、三维几何、圆弧、样条和不等式约束均在核心库当前范围之外。应用界面、模型存储和文件互转由集成方实现。

本库适用于可以表达为小型二维几何等式系统的应用。若需要完整 CAD 工作流、大型装配、任意初值全局求解或软约束优先级，应先评估相应专用工具。相关项目的概要见 [README 的生态对比](ECOSYSTEM.md)，接口差异与来源快照见 [生态对比详解](ECOSYSTEM.md)，引用与来源见 [第三方说明](../THIRD_PARTY_NOTICES.md)。

## 几何扩展优先级

本轮开发以 `Point`、`Line`、`Circle` 为核心几何范围。已有安装板和四杆机构案例用于展示约束建模、参数编辑与连续重新求解；400 模型配置套件持续验证稳定性，四档 Benchmark 提供限定模型的规模与计时数据，接下来优先完善包与版本交付。

| 优先级 | 范围 | 本轮安排 |
| --- | --- | --- |
| P0：核心交付 | 点、线段、圆及现有约束、编辑与诊断 | 巩固现有行为，完成下表中的批量稳定性验证、Benchmark 和包与版本交付 |
| P1：可选扩展 | `Arc`（圆弧） | 仅在 P0 交付完成且时间允许时评估；当前未实现，不作为本轮必做项，时间不足可跳过 |
| 暂缓 | `Ellipse`、`Bezier`、`Spline`、`NURBS`、`Polygon` 独立几何类型 | 本轮不新增这些类型及配套约束 |

这里的 `Polygon` 指独立几何类型；当前仍可组合点和线段建立矩形等闭合轮廓。圆弧是否启动开发，届时需先明确建模、约束、编辑和验证范围；列为 P1 不代表已支持或已承诺实现。

## 后续交付标准

参数化零件案例和首批批量验证已按下表交付；后续继续完善测量、验证证据与分发：

| 工作 | 完成标准 |
| --- | --- |
| 完整参数化零件案例 | 已提供 [四孔安装板 Showcase](SHOWCASE.md)：尺寸与设计关系、求解前后图形、冲突恢复、可运行入口与独立结果校验 |
| 批量稳定性验证 | 已提供 [Validation Suite](VALIDATION.md)：六组共 400 个固定种子模型配置、四后端独立残差 / 解析检查、成功率与失败分类；由维护者按需运行完整验证以复核限定模型范围 |
| Benchmark | 已提供 [四档规模实测](BENCHMARK.md)：20～200 变量与约束、迭代、独立残差、状态、同机计时及原始数据；只声明已测模型与 JS release 范围 |
| 包与版本交付 | `0.2.1` 通过 Mooncakes 分发，安装与复现见 [发布说明](PUBLISHING.md)；对应 GitHub tag / Release 为 `v0.2.1` |

当前定位工作的完成标准是：README 和包说明能清楚交代目标用户、解决的问题、使用入口及能力边界；后续成果分别以可运行案例、测量数据和实际发布记录验收。