# Web FreeCAD CAM exact 闭包实施文档

更新时间：2026-08-07

## 1. 验收口径

本轮以 FreeCAD `1.1.1`、提交 `0108fd4b4850cc46e625b60e53cea7a7bbe69f8d` 为 CAM/Path 和 Qt 行为基线。`cnc_wams_gpt6/linuxcnc-master/web` 中已经构建并通过既有回归的 LinuxCNC WebAssembly 是用户指定的实体机床与真实控制器认证权威；它的上游 RS274、canonical command、task/motion、HAL、trajectory planner 和 kinematics 结果决定 G-code 是否被机床接受。

运行介质、源码提交和产物哈希必须保留在报告中，以保证复现性。按照项目验收口径，LinuxCNC WASM 认证通过后不再要求另一台物理设备作为 CAM-32 的阻塞条件。

## 2. 唯一语义链

1. CAD/FreeCAD Path 生成并保存 `Path::Feature` / `Path::FeaturePython` 及 `Path::PropertyPath`，Web 端以确定性 Job/Path 表示承接。
2. OpenCAMLib WASM 执行 drop-cutter/waterline 等刀具与曲面算法，产出受版本和哈希约束的刀位结果。
3. CAMotics 官方源码阶段依据 `GCodeMachine.cpp` 的 `start/changeTool/setFeed/move/end` 语义生成受控 G-code；当前不调用 CAMotics parser，避免出现第二套 G-code 解释口径。
4. G-code 生成完成后才允许调用 LinuxCNC WASM。所有语法、模态、子程序/remap、单位、G93/G94、M428/M429、task/motion、轨迹规划和错误诊断只由 LinuxCNC WASM 决定。
5. 连续五轴程序使用目标机 `XYZBC` 配置、`M428` RTCP、逐段 G93 inverse-time feed 和 `M429` identity 恢复，并由 LinuxCNC 上游 task/motion 与 `xyzbcKinematicsInverse` 完成接受测试；OCCT 在该链路的仿真侧执行实体材料去除。

强制顺序为：`CAD -> OpenCAMLib WASM -> CAMotics source stage -> G-code -> LinuxCNC WASM`。任何绕过 G-code 生成阶段直接调用控制器、或在 Web/CAMotics 中另行解析最终 G-code 的路径，都不属于本项目 CAM 合同。

## 3. 任务分派

| 任务 | Owner | 交付 | 验收门 | 状态 |
| --- | --- | --- | --- | --- |
| XCAM-01 FreeCAD Path 算法 oracle | ORACLE | 原生 Profile 基准、命令序列、边界、长度、稳定哈希 | FreeCAD GUI/Path 实际运行且固定提交 | completed（Profile 基线；其余工序继续） |
| XCAM-02 Qt 动态 oracle | ORACLE+UI | CAM workbench、菜单/工具栏、命令启用、选择状态和 Task 状态 | Xvfb 下真实 Qt action/selection 回放 | completed（56 命令；Task 生命周期继续） |
| XCAM-03 Path FCStd 双向往返 | IO+ORACLE | `Path::Feature`、`Path::FeaturePython`、`Path::PropertyPath` save/open/mutate/save/open | 原生对象、命令与属性不丢失；Web 资源级路径编辑默认保护，FeaturePython 仅显式 opt-in 且不执行脚本 | native verified / safe resource codec verified / operation semantics in_progress |
| XCAM-04 CAM Job 元数据 | CORE+UI+QUALITY | `CAM_Comment`、`CAM_PropertyBag`、`CAM_Compound` 在 Job/JSON/Undo/Redo 中保持一致 | 评论、字符串/数字/布尔属性和复合 Operation 已有边界校验及依赖清理；不代表原生 Path operation-object 或 Python recompute | browser verified / native semantic parity in_progress |
| XCAM-04 OpenCAMLib WASM | KERNEL | 锁定上游提交的 OCL Emscripten 产物和浏览器 Worker | PathDropCutter/Adaptive/Waterline 可执行、可取消、资源有界 | completed |
| XCAM-05 CAMotics 源码阶段 | KERNEL+QUALITY | 锁定官方 CAMotics/C! 源码，按源码运动契约生成 G-code，并构建原生 GUI/TPL、headless CLI 与 Python sidecar | 主链不调用 CAMotics G-code parser；最终解析只走 LinuxCNC WASM；原生 CLI/STL 和 Qt/TPL 冒烟可复跑 | source-stage + native GUI/TPL/CLI completed / browser full-program differential pending |
| XCAM-06 原生实体材料去除 | KERNEL | OCCT cutter sweep/boolean、逐步实体和剩余体积 | BRep 有效、体积单调、资源释放、与 OCL 路径一致 | completed（当前平底刀/直线与采样模型） |
| XCAM-07 LinuxCNC RTCP 与机床认证 | CONTROLLER+QUALITY | XYZBC 连续工具轴、G93、M428/M429、限位/奇异/停机报告 | LinuxCNC WASM RS274、task/motion、HAL、kins 全链通过 | completed（认证机型；泛化安全门继续） |
| XCAM-08 Web Facade/UI 接入 | PLATFORM+UI | CAD→OCL→CAMotics→G-code→LinuxCNC WASM bridge | Chrome 实际 OCL 48 刀位点、65 行 G-code、48 轨迹段并被 LinuxCNC 接受 | completed（认证流程；完整 Qt 对话框 oracle 继续） |
| XCAM-09 exact 差异闭包 | QUALITY | CAM parity 合同、WBS、证据哈希和零未登记差异 | 所有前置门通过后才能提升声明 | pending |

连续执行顺序为 `XCAM-01/02/03 + XCAM-04/05/06 + XCAM-07 -> XCAM-08 -> XCAM-09`。认证闭环固定使用同一份由 OCL 输出驱动的 G-code；LinuxCNC 接受的是这份最终程序，不是旧的网页路径。

## 4. RTCP G-code 合同

目标控制器为 `cnc_wams_gpt6` 的 LinuxCNC WASM，机床配置为 `XYZBC` table-rotary-tilting。程序至少满足：

- 入口使用 `G21 G17 G40 G49 G80 G90 G94` 等明确安全模态，并完成 Tool/Spindle/Coolant 状态设置。
- 非 TCP 的安全定位在 identity kinematics 下进行；执行 `M428` 后才允许 XYZBC RTCP 联动。
- 连续切削段使用 `G93`，每个 `G1`/圆弧切削块具有显式正有限 `F` inverse-time 值。
- B 轴必须落在配置的软件限位内，C 轴展开必须连续；相邻旋转轴跳变、非有限坐标、零时长段、不可达姿态和奇异邻域必须拒绝或产生明确诊断。
- 退出切削前恢复 `G94`，安全抬刀并执行 `M429`；程序结束时主轴和冷却关闭。
- 认证必须由 LinuxCNC WASM 上游解释器生成 canonical motion，并由 task/motion、HAL 和上游 XYZBC kinematics 消费，文本正则检查不能作为接受证据。

## 5. 材料去除合同

主结果由 OCCT 实体布尔生成，输入是 Stock BRep、刀具/刀柄实体和 LinuxCNC canonical motion。每一步记录 operation、motion index、输入/输出 BRep 指纹、去除体积、剩余体积、碰撞和诊断。体积不得增加，空布尔或无效 BRep 必须失败，所有 ShapeHandle/Worker 引用必须归零。

OpenCAMLib 用于 drop-cutter/waterline 等刀具-表面算法，不承担 G-code 解释。CAMotics 固定官方源码提交，源码阶段负责把三轴受控运动写成 G-code；工作区的 CAMotics 1.3 Qt/TPL、`camsim`、`gcodetool`、`planner` 和 Python sidecar 均已构建并通过对应冒烟，另将上游 sweep C++ 编译为可由浏览器实际加载的 standalone WASM。该 WASM 只覆盖 Conic/Spheroid sweep 与包围盒，不包含完整 `camsim`、TPL、Qt 或 parser；它只作为浏览器内核子集证据，不进入规范控制链。最终 G-code 不经过 CAMotics parser，而是直接交给 LinuxCNC WASM；CAMotics 的三轴能力不能代替五轴 LinuxCNC RTCP 运动学认证。

## 6. 证据和声明规则

每个报告必须包含源码提交、构建命令、产物路径、字节数和 SHA-256、运行环境、成功与负例计数、资源释放结果。只有机器可重复执行的报告才能进入 `config/freecad-cam-parity.json`。源码清册、静态字符串或截图不能单独关闭算法、控制器、FCStd 或实体材料去除任务。

## 7. 已通过的主链证据

`config/chrome-cam-linuxcnc-machine-verification.json` 已由 Chrome 150 实际执行：OCL 上游 `PathDropCutter` 以 2 个 CAD 操作平面三角面把 5 个候选点解析为 48 个刀位点；CAMotics 源码阶段随后生成 2758 字节 G-code；LinuxCNC WASM 接受 65 行、138 个块、48 个轨迹段，解析权威和后端均为 `linuxcnc-wasm`。程序包含 `M428/M429`、`G93/G94`、`B5→B15`、`C359→C361`。

这份证据关闭的是选定 `XYZBC table-rotary-tilting` 数字机床案例，不等价于任意机床安全认证、实体执行、完整 FreeCAD Path 算法、浏览器内完整 CAMotics 程序或同输入 simulator differential。
