feat: establish reproducible FreeCAD web compatibility baseline

docs/freecad-cam-path-native-oracle.zh-CN.md

@@ -0,0 +1,49 @@
+# FreeCAD CAM Path 原生 Oracle 实施说明
+
+更新时间：2026-08-07
+
+这份说明覆盖浏览器 CAM 对标所需的三类原生证据：FreeCAD Path 算法回放、Qt CAM 工作台动态状态、以及 `Path::Feature` / `Path::FeaturePython` 的 FCStd 保存与恢复。当前 Web 编辑边界是经 FreeCAD 重开验证的原生 `Path::Feature` 命令资源子集；Python-backed 对象仍只读且不执行代码。
+
+## 参考环境
+
+- FreeCAD：1.1.1，源码提交 `0108fd4b4850cc46e625b60e53cea7a7bbe69f8d`
+- 构建：`.cache/freecad/install-desktop/bin/FreeCAD`
+- GUI：通过 `xvfb-run` 启动，`GuiUp=true`
+- Qt：运行时采集为 6.8.2
+- CAM 模块：`PathApp.so`、`PathGui.so`、`PathSimulator.so` 均来自桌面构建
+
+## 已完成的原生证据
+
+| 能力 | 证据 | 状态 |
+| --- | --- | --- |
+| 原生 Profile 算法 | `Mod/CAM/CAMTests/test_profile.fcstd`，真实 `Path.Op.Profile` 覆盖工具补偿和无补偿两种场景；每种生成 32 条命令，其中 20 条切削命令；命令按 0.01 mm 数值容差规范化并锁定 SHA-256 | verified-2-scenarios |
+| 原生 Helix 算法 | `Mod/CAM/CAMTests/test_holes00.fcstd`，0.9 mm 刀具、9 个 base 子元素，覆盖 Inside/Outside 与 Climb/Conventional 四种组合；每种包含 1260 条原生 G2 或 G3 弧命令并验证 CW/CCW 方向 | verified-4-scenarios |
+| Qt 动态 oracle | 激活 `CAMWorkbench`，读取 56 个实时 `CAM_*` 命令、QAction 文本/图标/快捷键/注册状态、菜单和工具栏；并通过真实 `setEdit()`、QDialogButtonBox OK/Cancel、14 个 Task 字段和关闭回放验证 Job/Profile Task 生命周期 | verified |
+| 原生 Path FCStd | 创建 `Path::Feature` 与 `Path::FeaturePython`，保存、重开、修改路径和属性、再次保存并重开；`Path::PropertyPath`、5/6 条命令和标签均被 FreeCAD 恢复 | verified |
+| Web Path 编辑与透明往返 | Facade 对 `Path::Feature` 解码/重写 `.nc` 资源；显式 `allowFeaturePython` 时也可对 `Path::FeaturePython` 只改 `.nc` 资源，追加命令后由 FreeCAD 重开验证 5→6 条；脚本和 XML 仍保持不执行/不改写 | verified-safe-resource-only-opt-in |
+
+结构化结果在 [`config/freecad-cam-path-oracle.json`](../config/freecad-cam-path-oracle.json)。生成和校验脚本分别是 [`scripts/run-freecad-cam-path-oracle.ts`](../scripts/run-freecad-cam-path-oracle.ts)、[`scripts/freecad-cam-path-oracle.py`](../scripts/freecad-cam-path-oracle.py) 和 [`scripts/check-freecad-cam-path-oracle.mjs`](../scripts/check-freecad-cam-path-oracle.mjs)。
+
+## 复跑和门禁
+
+```bash
+./npmw run probe:freecad-cam-path
+./npmw run check:freecad-cam-path
+./npmw run test:freecad-cam-path-report
+```
+
+`probe` 会在 `.cache/freecad/cam-path-oracle/` 生成源档案、变更档案和 Web 透明副本。报告中的 FCStd 完整性哈希是重开后 Path 对象语义哈希；运行时仍比较透明副本和源档案的完整字节。Profile 命令使用 0.01 mm 规范化，避免 OCCT 在 1e-6 mm 级别的浮点抖动造成假差异。连续两次完整 probe 的报告语义结果稳定。
+
+## 任务安排
+
+| 任务 | 交付物 | 当前状态 | 后续验收 |
+| --- | --- | --- | --- |
+| ORA-CAM-PATH-01 | Profile/Helix 等 Path 算法原生 fixture 与规范化黄金 | in_progress（Profile 2 场景 + Helix 4 场景） | 继续扩展 Drilling、Pocket、Surface 等工序的输入、失败和版本黄金 |
+| ORA-CAM-PATH-02 | Qt 工作台命令、QAction、菜单、工具栏、选择上下文和 TaskPanel 生命周期采集器 | completed（56 命令 + Job/Profile 生命周期） | 扩展更多工序的字段/校验/焦点黄金 |
+| ORA-CAM-PATH-03 | 原生 `Path::Feature` / `Path::FeaturePython` FCStd 双向保存恢复 | completed（native-native） | 增加 Job、ToolController、SetupSheet 和 Dress-up 对象 |
+| ORA-CAM-PATH-04 | Web Facade `Path::PropertyPath` 结构化解码/编码与可编辑事务 | completed（Path::Feature + FeaturePython 安全资源 opt-in） | 扩展 Job/Operation 对象、属性/重算语义和 Undo/Redo；不宣称完整 operation-object 语义 |
+| ORA-CAM-PATH-05 | FreeCAD Path 与 OpenCamLib/CAMotics 的连续差分 | pending | 版本锁定、同一 stock/tool/path 输入、体积/碰撞/时间差分 |
+
+## 明确边界
+
+当前 Web Facade 对 `Path::Feature` 提供结构化 `Path::PropertyPath` 解码/编码；对 `Path::FeaturePython` 只有显式 `allowFeaturePython: true` 才开放同样的资源级编辑。两者都只允许修改已有 native `.nc` 资源的命令列表，资源路径、版本和 Center 元数据保持不变；XML、脚本和 Python 代码从不执行或改写，编辑后由 FreeCAD 重开验证。算法 oracle 当前只覆盖 2 个 Profile 场景和 4 个 Helix 场景；完整 Path 操作对象、FeaturePython 属性/重算语义、其余工序算法、Undo/Redo 和全量 Qt Task 行为仍未达到 exact parity，整体报告的 `exactParityClaim=false`。