# 架构说明

MoonCam 的核心输入是分段运动程序与机构尺寸，核心输出是采样分析结果及交换文件。核心运行不依赖浏览器、Node.js、Python 或 CAD。

## 数据流

```text
Program → MotionMesh → Scan → Analysis → report / checked_export
                       ↑         ↑
                    Geometry  crossing_report
```

- `motion.mbt`、`program.mbt`：三种解析运动规律、程序闭合校验、二分段定位与时间导数。
- `geometry.mbt`：旋转坐标系中的压力角、曲率与偏置因子，及真实接触轮廓坐标。
- `analysis.mbt`：按段构建 O(N+S) 运动网格。标量路径不构造坐标；完整路径返回同一遍计算的指标和坐标。
- `topology.mbt`：主跨度轴包围盒分桶、带误差界的方向符号、交叉与不确定状态，以及访问预算。
- `search.mbt`：复用粗细运动网格，按有限基圆网格寻找第一个通过复核的点。细网格只扫描一遍，可能为最终拒绝的候选分配坐标，这是当前明确的成本取舍。
- `export.mbt`：生成 CSV、SVG、DXF；外部自建点数组应调用 `checked_export`，原始格式函数要求输入已经有效。
- `api.mbt`：严格 JSON 输入、字段错误位置、按需输出、统一 schema 版本与 UTF-8 上限。类型化 `Session` 保存最近一次成功计算的点数组，导出直接复用该数组；下一次请求开始时清空旧缓存。

`contract.mbt` 集中 schema 版本、三层上限、错误码和状态/退出码映射；公开 contract_json 供宿主与文档生成使用，CI 检查契约文档与公共签名是否同步。

上述模块全部为 MoonBit。`bridge/` 仅导出编译后接口。`bin/` 负责宿主文件读写与退出码；`web/` 负责 DOM、交互和 Worker 消息，不重写运动学、几何、搜索或导出算法。`web/engine.js` 是忽略提交的编译产物。`web/segments.mjs` 只编辑表格与显示错误，独立的 validate 消息交给 MoonBit 的 `validate_segments_json`，不触碰分析会话。校验、计算、导出共享单调请求号，校验另有编辑令牌，迟到校验不会覆盖新输入。

## 状态与资源边界

`CrossingCheck` 区分未检查、完成、几何不确定、失败。只有局部约束通过且完成状态的交叉数为零才会接受。相切、重叠或方向符号无法可靠确定时，不会解释成零交叉。搜索发现不确定几何时返回类型化错误，不宣称网格无解。

分桶并不消除所有最坏情况。超过契约规定的桶内线段对访问预算会返回失败；这限制了计算量，但也可能拒绝本来可判定的复杂输入。检查仍然针对采样折线，不证明连续轮廓无干涉。

核心库、JSON 分析与搜索的分辨率上限及搜索复核倍数统一见[接口契约](接口契约.md)，由 MoonBit 自动生成。这些不同上限分别约束库调用、宿主响应成本和搜索成本。逐段向上取整后，实际区间数可能多于名义分辨率。

网页同时校验 Worker 实例编号和请求编号；参数编辑计数用于标记过期结果。Worker 不可用时采用同一 MoonBit 编译引擎的主线程兼容模式；此时无法保证 20 秒强制中断，页面会明确提示。

## 验证与演进

`*.generated.mbti` 是有意版本管理的公共接口快照；CI 重新生成后检查差异。四个后端执行同一组 MoonBit 测试。整数坐标二次遍历参考实现用于差分验证，固定种子的生成案例用于回归。24,000 边横窄/纵窄轮廓的访问计数及恶意重叠预算测试约束复杂度回退。

CI 固定工具链 `0.10.16+b1a0e846e`，另外记录高分辨率和 128 段的端到端性能数据。时间结果保存为 artifact，并设置宽松的严重退化耗时门槛；主要复杂度护栏使用确定性的访问次数。独立 Python 数值与 DXF 读取器只用于开发验证。

设计理由与代价见[设计取舍](设计取舍.md)，公共入口见[公共 API](公共API.md)，固定回归见[判定验收](判定验收.md)。

## 位置与诊断数据流

`location.mbt` 提供统一段界查询及角度、采样点、边的位置；`program.mbt` 的运动求值复用同一查询。`analysis.mbt` 扫描时记录极值点下标；`diagnostics.mbt` 组合阈值、余量和位置，并逐档执行采样比较。`topology.mbt` 保存受限边对证据；`api.mbt` 通过同一位置模型扩展边端点信息，网页只选择和绘制这些编号。详见[位置、诊断与采样比较](位置诊断与采样比较.md)。