test: add reproducible FreeCAD golden oracle

2026-08-03 03:20:37 -04:00
parent 81fcc69a74
commit 2ce261b982
27 changed files with 678 additions and 12 deletions
--- a/docs/continuation-status.zh-CN.md
+++ b/docs/continuation-status.zh-CN.md
@@ -1,6 +1,6 @@
 # Web FreeCAD 接续执行状态

-更新时间：2026-08-03（MultiTransform whole-shape 里程碑）
+更新时间：2026-08-03（FreeCAD 1.1.1 原生黄金 oracle 里程碑）

 ## 1. 当前目标

@@ -10,9 +10,9 @@

 - 分支：`main`
 - 云仓库：`http://154.8.160.151:3000/wangdequan/Web_FreeCAD_Bitbybit.git`
- 最近已推送里程碑：`b09c5aa feat: add structured multi-transform`
+- 最近已推送里程碑：`81fcc69 docs: record multi-transform milestone`
 - 最近已推送里程碑的完整门禁：`./npmw run verify` 通过
- 当前 MultiTransform 里程碑验证：`./npmw run verify` 通过（Facade 67/67），diff/JSON 校验通过
+- 当前原生 oracle 里程碑验证：FreeCAD 1.1.1 源码构建成功，5/5 Part 黄金回放、`./npmw run verify`、diff/JSON 校验全部通过
 - 生产构建：通过
 - 本地开发地址：`http://127.0.0.1:5173/`
 - 兼容真值表：`config/compatibility-matrix.json`
@@ -49,7 +49,7 @@

 ## 4. 已确认限制

- 仓库没有 FreeCAD C++ 源码、Emscripten 工程或 planegcs WASM 产物；`SK-03` 不能标记完成。现有 `typescript-basic` solver 仅用于协议与基础模型验证。
+- 锁定的 FreeCAD 1.1.1 C++ 源码可由脚本获取到忽略目录并完成无界面 Part 原生构建；尚无 FreeCAD/planegcs Emscripten 工程或 planegcs WASM 产物，`SK-03` 不能标记完成。现有 `typescript-basic` solver 仅用于协议与基础模型验证。
 - Pattern 与 MultiTransform 当前复制整个 Shape，不是 FreeCAD 局部特征历史。
 - Hole 固定原点/法向，尚无面定位、沉孔、锪孔、螺纹和完整孔标准。
 - 拓扑历史来自签名保守回退，不是 OCCT/FreeCAD 原生 Generated/Modified/Deleted 历史。
@@ -61,7 +61,7 @@
 1. 补齐 P2 浏览器实证门禁：真实 SQLite v4→v5 升级、OPFS 孤儿清扫、QuotaExceeded、大文件和崩溃注入；合同层与 fallback 测试已由 `6bfbdf5` 完成。
 2. 补齐 P3-03 浏览器 OCCT 包围盒/体积黄金测试，并验证 Placement 撤销、保存和恢复的真实 Worker 路径；Node/fallback 合同已通过。
 3. 为 ambiguous/deleted TopoRef 补 3D 候选高亮，并增加真实 OCCT/SQLite 浏览器回放；候选替换 Facade 事务和属性/诊断 UI 已进入当前里程碑。
-4. 在获得 FreeCAD `1.1.1` 源码/构建输入后完成 `SK-03` planegcs WASM POC；此前继续补充回放夹具、约束分类和 Sketch 编辑事务。
+4. 基于已锁定的 FreeCAD `1.1.1` 源码提取 planegcs 最小依赖图，完成 `SK-03` Emscripten/WASM POC；同时扩充回放夹具、约束分类和 Sketch 编辑事务。
 5. 扩展 PartDesign：推进 Loft/Pipe/Groove、Thickness/Draft，以及 Mirrored/MultiTransform/Pattern/Hole 的局部特征历史与完整语义。
 6. 完成 FCStd 原生对象/属性/Shape 双向映射和 STEP/IGES/STL/Web CAD 包导入导出。
 7. 按核心优先级完成 TechDraw、Spreadsheet、Draft、Assembly、BIM、Mesh、Surface、FEM、CAM 等工作台。
@@ -145,3 +145,12 @@ Placement 里程碑涉及实现、测试、兼容矩阵和三份状态/方案文
 当前实现不是 FreeCAD Transform feature history 的完全等价实现：它组合并融合整个 Base Shape，未实现局部特征列表、Datum/TopoRef 轴面、单实体过滤或 OCCT 原生历史。下一执行点是 Additive/Subtractive Loft 的结构化截面合同与 whole-shape experimental 执行边界。

 本里程碑不得声称 P3-03、F3 或完整 FreeCAD 兼容已经通过。当前对象 Placement 是 Shape 生成后的对象级变换，尚未证明 FreeCAD 对 Body/Tip、Support、AttachmentOffset 和局部坐标链的完整等价语义。
+
+## 13. 2026-08-03 FreeCAD 原生黄金 oracle 快照
+
+- 官方 `1.1.1` 标签已在线核验到提交 `0108fd4b4850cc46e625b60e53cea7a7bbe69f8d`；`fetch:freecad-source` 只接受该提交并使用 detached checkout。
+- `configure:freecad-native` 和 `build:freecad-native` 已在 Debian trixie 上完成 Release、无 GUI、Part/Material/Measure 最小构建；产物报告 `FreeCAD 1.1.1 Revision: 14556 (Git)`，哈希和工具版本记录在 `config/freecad-native-build.json`。
+- 新增声明式黄金契约、FreeCAD Python driver、CLI 回放器和比较器。Box、Cylinder、Sphere、Cone、穿孔 Cut 共 5/5 场景通过有效性、拓扑、体积/面积和包围盒对比。
+- 全部 Node/npm 操作均使用 `./npmw`；依赖、构建、回放和 CI 边界已写入 `docs/freecad-baseline-and-golden.zh-CN.md`。
+
+本轮只完成 P0-01/P0-03 的首批可复现基线。依赖容器 digest、完整 FreeCAD 工作台构建、100 个黄金文件、50 个错误文件、GUI 行为和 Web OCCT 双端差分尚未完成，F0/G0 保持进行中。下一执行点是读取 FreeCAD/OCCT 原生 Generated/Modified/Deleted 历史接口并形成可供 Web `TopoRef` 消费的类型化历史合同。
--- a/docs/freecad-baseline-and-golden.zh-CN.md
+++ b/docs/freecad-baseline-and-golden.zh-CN.md
@@ -0,0 +1,84 @@
+# FreeCAD 基线与黄金回放
+
+## 1. 已锁定基线
+
+- FreeCAD：`1.1.1`
+- 官方标签提交：`0108fd4b4850cc46e625b60e53cea7a7bbe69f8d`
+- 本地源码：`.cache/freecad/FreeCAD`
+- 本地构建：`.cache/freecad/build-native`
+- 本地安装：`.cache/freecad/install-native`
+- 构建清单：`config/freecad-native-build.json`
+- 黄金清单：`fixtures/freecad-golden/manifest.json`
+
+源码、构建和安装目录均在 `.cache/` 下，不进入 Git。仓库保存精确提交、构建参数、工具版本、产物哈希和回放契约；当前产物是用于几何对照的无界面 Part oracle，不是完整 FreeCAD 桌面发行版。
+
+## 2. Debian trixie 依赖
+
+本次实测使用 GCC `14.2.0`、CMake `3.31.6`、Ninja `1.12.1`、Python `3.13.5`、Qt `6.8.2`、OCCT `7.8.1` 和 SWIG `4.3.0`。安装命令：
+
+```bash
+sudo apt-get update
+sudo apt-get install -y \
+  qt6-base-dev qt6-tools-dev qt6-svg-dev \
+  libocct-foundation-dev libocct-modeling-data-dev \
+  libocct-modeling-algorithms-dev libocct-visualization-dev \
+  libocct-ocaf-dev libocct-data-exchange-dev \
+  libxerces-c-dev libeigen3-dev libfmt-dev libyaml-cpp-dev \
+  libicu-dev zlib1g-dev libtbb-dev swig
+```
+
+## 3. 可复现构建
+
+所有项目脚本统一经 `./npmw` 使用仓库锁定的 Node/npm 运行时：
+
+```bash
+./npmw run check:freecad-source
+./npmw run fetch:freecad-source
+./npmw run configure:freecad-native
+FREECAD_BUILD_JOBS=4 ./npmw run build:freecad-native
+```
+
+`configure:freecad-native` 会拒绝非锁定提交，并配置 Release、`BUILD_GUI=OFF`、`BUILD_PART=ON`。Sketcher、PartDesign、TechDraw、Assembly、FEM、CAM 等非当前 oracle 所需模块均显式关闭。Qt6 翻译工具通过 `config/freecad-native-bootstrap.cmake` 在无界面配置中补充加载。
+
+构建完成后检查版本：
+
+```bash
+.cache/freecad/install-native/bin/FreeCADCmd --version
+```
+
+预期为 `FreeCAD 1.1.1 Revision: 14556 (Git)`。当前已验证二进制 SHA-256 为 `14b8e8c94472249c657426ee312f6f6d05b62e328dfe2794d20c81c95379bfbc`；不同主机工具链生成的产物哈希变化必须先更新构建清单并重新执行全部黄金回放，不能静默接受。
+
+## 4. 黄金回放
+
+执行契约单元测试和真实 FreeCAD 对照：
+
+```bash
+./npmw run test:golden
+./npmw run test:golden:freecad
+```
+
+回放器按以下顺序定位 oracle：`FREECAD_CMD`、仓库本地构建、系统 `FreeCADCmd`、系统 `freecadcmd`。也可显式指定：
+
+```bash
+FREECAD_CMD=/absolute/path/to/FreeCADCmd ./npmw run test:golden:freecad
+```
+
+当前五个场景覆盖 Box、Cylinder、Sphere、Cone 和穿孔 Cut。每个场景比较 FreeCAD 版本、空/有效状态、顶层 Shape 类型、Solid 数、面/边/点数（声明时）、体积、面积（声明时）及包围盒，并分别应用标量与线性容差。穿孔 Cut 的 FreeCAD 1.1.1 实测顶层是含一个 Solid 的 `Compound`，契约保留这一原生行为。
+
+输出完整机器可读报告或只执行单个场景：
+
+```bash
+./npmw run test:golden:freecad -- --json
+./npmw run test:golden:freecad -- --scenario=part-cut-through-hole
+```
+
+## 5. 常规门禁与边界
+
+```bash
+./npmw run check:baseline
+./npmw run verify
+```
+
+`check:baseline` 在本地 oracle 存在时校验其 SHA-256；干净检出没有 `.cache/` 时仍校验所有锁文件、黄金契约和 Web OCCT WASM 哈希。`verify` 不强制编译 FreeCAD，也不把缺失桌面 oracle 误报为回放通过；CI 若承担 FreeCAD 对照职责，必须单独执行 `test:golden:freecad`。
+
+当前只完成 P0-01/P0-03 的第一批可复现基础设施和 5 个成功几何场景。依赖镜像摘要、完整工作台构建、100 个黄金文件、50 个错误文件、GUI 行为回放和浏览器 OCCT 差分仍未完成，因此不得将 F0 或完整 FreeCAD 兼容标记为通过。
--- a/docs/freecad-full-parity-plan.zh-CN.md
+++ b/docs/freecad-full-parity-plan.zh-CN.md
@@ -247,9 +247,9 @@

 | ID | 任务 | 交付物 | 验收标准 |
 |---|---|---|---|
-| P0-01 | 固定 FreeCAD 源码、编译器和依赖镜像 | lock、容器、构建日志 | 同一输入产生相同版本信息 |
+| P0-01 | `IN PROGRESS`：已固定 FreeCAD 源码提交、原生编译器/依赖版本、无界面 Part 构建脚本与产物哈希；依赖镜像 digest 尚未完成 | lock、容器、构建日志 | 同一输入产生相同版本信息 |
 | P0-02 | 生成 UI/命令/对象/Property/工作台 manifest | JSON manifest | 每条能力有来源和等级 |
-| P0-03 | 建立 100 个黄金文件、50 个错误文件、回放脚本 | fixtures、expected | 桌面结果可复现 |
+| P0-03 | `IN PROGRESS`：声明式契约、FreeCADCmd driver/比较器和首批 5 个 Part 成功样例已通过；100 个黄金文件与 50 个错误文件尚未达到 | fixtures、expected | 桌面结果可复现 |
 | P0-04 | 固定浏览器能力矩阵和 COOP/COEP | browser matrix | Chrome/Firefox/Safari 最新两个版本有结果 |
 | P0-05 | 许可证、供应链、WASM 安全评审 | SBOM、许可证清单 | 无未知二进制和高风险漏洞 |
 | API-01 | Facade API 版本化和 JSON Schema | `src/facade` 合同 | 破坏性变更有迁移和弃用期 |
@@ -293,7 +293,7 @@
 ## 14. 下一轮实际执行顺序

 1. 使用项目本地 Node 运行时完成 P0-RT、依赖安装和验证，清除引擎警告。
-2. 完成 P0-01/P0-03：FreeCAD 提交、构建容器、manifest 和黄金模型目录。
+2. 继续完成 P0-01/P0-03：在已验证的提交、原生构建和 5 个黄金样例上补齐 digest 锁定构建容器、100 个黄金文件、50 个错误文件和 GUI 回放。
 3. 实现 `DAG-01..DAG-06` 与 `EXU-01..EXU-06`，让属性修改从“Touched 标记”升级为可解释的依赖重算。
 4. 实现 `TSN-02..TSN-07`，再把附着、Pocket up-to-face、测量和 TechDraw 选择切换到 `TopoRef`。
 5. 编译/验证 `SK-03`，然后按基础约束→高级约束→编辑器→PartDesign 轮廓的顺序推进。
--- a/docs/web-cad-implementation-plan.zh-CN.md
+++ b/docs/web-cad-implementation-plan.zh-CN.md
@@ -985,6 +985,8 @@ SQLite 是运行时的主存储，不要求项目包直接暴露数据库内部

 阶段时长是日历周估算，不是简单相加的人周。UI-0 至 UI-3 必须先于真实功能接入；阶段 2、5、6 可并行，阶段 4 和 7 的深度受 POC 结论影响；阶段 9-11 是实现“完整 FreeCAD 官方核心覆盖”不可省略的后续计划。以需求、交互和技术决策已能及时确认作为前提，建议采用以下排期口径：

+当前 P0 实证：FreeCAD `1.1.1` 精确提交已由脚本获取并完成无界面 Part 原生构建，Box/Cylinder/Sphere/Cone/Cut 五个声明式黄金场景通过 `FreeCADCmd` 回放。完整命令见 `docs/freecad-baseline-and-golden.zh-CN.md`，Node/npm 操作统一使用 `./npmw`。该证据尚未覆盖 digest 锁定容器、GUI、完整工作台、100 个成功样例和 50 个错误样例，因此只计为 P0-01/P0-03 进行中。
+
 | 交付层级 | 建议团队 | 预计周期 | 范围 |
 |---|---:|---:|---|
 | 全量前端页面设计 | 4-6 人 | 13-22 个日历周 | FreeCAD 页面盘点、设计系统、全部工作台静态页面、状态、原型和 Facade 映射 |