# 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 桌面发行版。

本机 oracle 可作为锁定版本的行为参考。`./npmw run probe:freecad-reference` 会通过 `FreeCADCmd` 采集版本、Git 提交、GUI 能力、可导入 Python 模块和核心 TypeId/Property 元数据，输出机器可读报告。模块状态明确区分 `not-built`、`compiled-importable`、`compiled-import-failure` 和 `gui-only-unprobeable`，并分别记录 `compiled`、`importable`、`guiRequired`、`guiAvailable`；当前无界面构建报告 3 个 `compiled-importable`、9 个 `not-built`。完整桌面/工作台对照仍需单独构建 GUI oracle，不能从该报告推断已支持。

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