# 设计取舍

本文记录当前实现的选择及其代价，不扩展申报承诺。架构与数据流见[架构说明](架构说明.md)，可执行契约见[接口契约](接口契约.md)。

## 采样结论的边界

按段采样能保留运动规律接缝，工作量与名义分辨率和段数相关，适合课程设计和方案初选。它不能证明两采样点之间没有压力角极值、回环或全局滚轮干涉。

`measure` 只检查局部指标，不构造坐标。完整 `analyze` 还做折线检查。局部通过与确定零交叉同时满足才接受；检查未完成或几何不确定时保守地不接受。这可能拒绝本来安全的近退化轮廓，代价是不会把无法确定的情形伪装成通过。

## 数值判定

方向符号使用局部坐标差、归一化和浮点误差过滤，不以绝对世界坐标决定交叉容差。归一化乘积出现下溢风险时返回不确定。首尾闭合校验与导出共用局部跨度的相对容差，不再设与原点相关的绝对容差地板。

这不是精确算术。超大平移使 Double 无法表达原始细节时，原始几何无法恢复；坍缩或零长边会失败。相切、重叠和近退化目前共同进入不确定状态，不声称提供精确接触类型证明。固定验收覆盖可表示范围内的缩放和平移，以及细节丢失后不误报通过的案例。

## 搜索与计算成本

基圆搜索依次访问有限网格，不能在没有曲率约束单调性证明时换成二分搜索。结果是第一个通过粗筛、双倍分辨率复核与拓扑检查的网格点，不是连续最优。

粗筛使用标量路径。细网格只扫一遍，同时获得指标与坐标；因此细网格最终拒绝的候选也可能产生一批废弃坐标。保留这一取舍以避免所有成功候选重复计算。

分桶沿最大跨度轴进行，对普通密集采样轮廓有利，但长包围盒大量重叠时仍可能退化。访问预算限制极端输入的成本，触发预算时返回检查失败，可能放弃本来可求解的输入。性能测试使用访问次数作为确定性护栏；耗时仅作观测。

## 上限、错误与兼容

库、JSON 分析、搜索的分辨率上限分别面向离线库调用、宿主响应和细网格复核成本，有意不同。数值来自 `contract.mbt`；文档和宿主从 `contract_json` 读取，CI 检查文档是否过期。

基础库保留 `Result[T, String]`，避免大范围修改既有调用；稳定分类通过 `SearchError`、`ErrorCode` 和 JSON `error_code` 提供。字段路径尽量定位到具体项，程序整体闭合等组合约束不能伪装成单字段问题。输入校验后的数值失败使用 calculation_failed，不再混为 invalid_input。

schema 版本与包版本分开。当前保持 schema 2；新增 indeterminate 状态要求调用方保守处理未知状态。顶层 sample_count 暂留兼容，推荐 sampling.sample_count。公共接口快照有意提交，构建产物不提交。0.3.0 整理上述增量能力，发布包通过 .moonignore 聚焦核心库；标签在实际发布并完成独立安装验证后创建。

## 输出与宿主

JSON 仅生成请求的重输出。MoonBit Session 保存上次成功请求的点数组，按需生成文件内容；新请求先清空缓存，失败后不会继续导出旧结果。CSV 的角导数与 JSON 的时间导数采用明确不同字段，避免隐式单位切换。

原始导出函数假定数据已验证；自建点数组使用 checked_export。导出通过只表示格式输入有效，不代表轮廓可行；失败轮廓也需要导出诊断。DXF 科学计数法已通过 ezdxf，商业 CAD 仍需实际验收。

网页的 Worker、消息编号、DOM 和文件下载是宿主职责，核心算法仍由 MoonBit 执行。没有模块 Worker 时，同一编译引擎可在主线程降级运行，代价是页面可能暂停响应，不能承诺强制超时中断。既有 stdin / 批量仅作为辅助入口保留，本轮不继续扩展。

## 统一位置与采样比较

位置查询和运动求值共用段查询。指标下标在扫描过程中直接保存，按严格更差更新，等高时保留首点。段标识跨分辨率保留含义，点号和边号不作跨网格身份。闭合点归首段，闭合前的末边归末段，避免点属性与边区间混用。

采样比较默认关闭。开启后对同一尺寸做三档完整检查，复用已有档位并只保留其他档摘要，代价是额外两档计算。只报告数值差、位置与状态，不设置任意“收敛通过”阈值。对称极值换段不单独标为异常。

边对证据有数量上限，但判断与计数不因展示截断而提前停止；不输出未经计算的交点。检查失败则丢弃部分证据，要求调用方查看完整状态。

## 表格和 JSON 使用同一校验

网页默认按行编辑运动段，各段独立保存运动规律。JavaScript 负责 DOM 和数字输入序列化，空白数字传为 null，交给 MoonBit 判错，避免空白被隐式转换成零。总量与程序接受条件全部由同一 MoonBit 解码器和 program 构造器计算。150 ms 防抖只减少输入时的往返，不改变校验条件。

高级 JSON 导入先通过同一校验才替换表格；非法草稿不覆盖已有输入。分段校验不修改分析缓存，编辑后仍允许保存上次结果，并通过过期提示说明对应关系。搜索也不自动覆盖输入参数，教程要求用户明确填入候选后重新复核。

## 报告编码失败与兼容模式成本

报告使用的边证据和诊断位置原则上来自同一次分析，但编码器仍显式处理查询失败。内部编号或位置不一致时返回带原始定位原因的 internal_error，不用 unwrap 将错误升级为 panic，也不省略损坏证据后继续给出通过报告。

三档比较会复用已完成的一档，再完整分析另外两档；4000 分辨率对应 1000、2000、4000，不是连续执行三次 4000。无 Worker 的主线程兼容模式取消并禁用比较，并在构造请求时再次阻止启用。页面持续说明单档同步计算也可能阻塞、定时器不能强制中断；希望比较时应使用支持模块 Worker 的浏览器，或通过 CLI 执行比较请求。

简化拓扑入口与详细入口的选择见[公共 API](公共API.md)，近舍入与下溢用例的环境限定见[判定验收](判定验收.md)。