test: add reproducible FreeCAD golden oracle

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 兼容标记为通过。