# Web FreeCAD 接续执行状态

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

## 1. 当前目标

按 FreeCAD `1.1.1` 全功能对标方案持续推进 F0-F9 阶段门，完成实现、测试、兼容矩阵、发布门禁并同步云仓库。当前仍是 experimental 核心 Facade/OCCT 阶段，不能宣称已达到 FreeCAD 全功能兼容。

## 2. 仓库状态

- 分支：`main`
- 云仓库：`http://154.8.160.151:3000/wangdequan/Web_FreeCAD_Bitbybit.git`
- 最近已推送里程碑：`81fcc69 docs: record multi-transform milestone`
- 最近已推送里程碑的完整门禁：`./npmw run verify` 通过
- 当前原生 oracle 里程碑验证：FreeCAD 1.1.1 源码构建成功，5/5 Part 黄金回放、`./npmw run verify`、diff/JSON 校验全部通过
- 生产构建：通过
- 本地开发地址：`http://127.0.0.1:5173/`
- 兼容真值表：`config/compatibility-matrix.json`
- 总体方案：`docs/freecad-full-parity-plan.zh-CN.md`

## 3. 本轮已完成并推送

1. 重计算根因诊断、修复分支重算与诊断树。
2. Linear Pattern、Polar Pattern 和基础 Hole 的 experimental OCCT 执行链路。
3. 稳定拓扑签名、版本化 TopoRef、迁移、PropertyLinkSub 与保守拓扑历史回退。
4. Sketcher 版本化 solver provider 协议、能力探测、取消/过期 generation 隔离和回放合同。
5. 椭圆/B-spline 领域模型；基础 TypeScript solver 对未支持曲线返回明确诊断。
6. 外部草图几何、稳定 TopoRef、持久化与 `topo-ref` DAG 依赖边。
7. Vector、Placement、LinkList/StringList 结构化属性合同；Placement 深拷贝、校验、撤销、持久化和 UI 编辑器。
8. 对象级 Placement 重算：基本体/特征 Shape 生成后执行平移与轴角旋转；恒等变换跳过额外 Shape；变换失败释放临时 Shape 并保留上一次有效缓存；保存后恢复的 Placement 可再次驱动重算。
9. TSN generation 写回：重算成功后采集面/边/点签名快照与保守历史；迁移 LinkSub/草图外部几何；歧义或删除引用标脏所有者并生成可定位诊断；schema v6 保存对象拓扑快照。
10. TopoRef 候选替换事务：属性面板/诊断页从源对象当前同 kind 拓扑候选中原子替换 LinkSub 或外部几何引用，重建 DAG、标脏重算并支持 Undo/Redo。
11. Mirrored whole-shape：Facade 暴露 OCCT 平面法向镜像，PartDesign Task 支持 XY/XZ/YZ 原点平面与可选 Fuse，重算释放 union 临时副本并写回 Shape/拓扑 generation。
12. MultiTransform whole-shape：新增结构化有序 Linear/Polar/Mirrored 步骤属性、Task/属性编辑器、最多 6 步和 100 实例校验；重算按顺序组合全部实例，失败与成功均释放中间 Shape，并保留最近有效缓存。

相关提交按新到旧：

- `293cff6` structured placement properties
- `a8f902c` stable sketch external geometry
- `6786261` advanced sketch curves
- `e0b4817` versioned sketch solver protocol
- `4d94109` conservative topology history fallback
- `d3d88b2` LinkSub topology references
- `9def470` topology reference migration
- `1ed3527` basic hole
- `ce3b81c` polar pattern
- `8995b90` linear pattern
- `aeafc6c` recompute diagnostic repair tree

## 4. 已确认限制

- 锁定的 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 历史。
- Placement 已进入文档属性，并接入 Facade 的对象级 Shape 重算；尚未完整映射到 Body/Tip、Support、AttachmentOffset 或所有特征执行器的 FreeCAD 局部坐标链语义。
- FCStd 仍以安全预检、metadata/proxy 和只读报告为主；本轮新增对象属性名、FreeCAD 类型、XML 元素和值的字段级 `Document.xml` 投影，但尚未双向原生往返。

## 5. 下一步执行顺序

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` 源码提取 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 等工作台。
8. 最后通过跨浏览器、性能、内存、安全、可访问性、离线/PWA、升级回滚和发布差异报告门禁。

## 6. 接续操作

```bash
cd /home/mes123456/working_Web_FreeCAD_Bitbybit
git status --short
git log -5 --oneline
./npmw run verify
```

每个独立里程碑必须：

1. 更新实现与聚焦测试。
2. 更新 `config/compatibility-matrix.json` 和两份实施方案中的真实状态。
3. 运行 `./npmw run verify`、`git diff --check` 和 JSON 校验。
4. 单独提交并推送 `main`，不得把凭据写入仓库。

## 7. 2026-08-03 P2 接续进展

本轮已完成 schema v5 迁移运行器、最近 5 版文档检查点、`loadCheckpoint()`、配额预检、资源清扫计划/API 和 1000 次写队列压力实现。完整门禁已通过，并由提交 `6bfbdf5` 推送到云仓库。后续 TSN 里程碑把 schema 提升到 v6，以 `objects.topology_json` 保存 generation 拓扑快照；真实浏览器 v5→v6 升级仍需补证。

证据边界：Node/fallback 证明迁移合同、队列、检查点与纯资源策略；真实浏览器 SQLite v4→v5 升级、OPFS 孤儿清扫、QuotaExceeded、大文件与崩溃注入仍是 P2/P8 后续任务，不能因本轮测试而标记完整 G4/G5。

## 8. 2026-08-03 Placement 里程碑快照

Placement 里程碑涉及实现、测试、兼容矩阵和三份状态/方案文档：

- `src/facade/recomputeEngine.ts`：Shape 生成成功后读取对象 `Placement`，通过 `geometry.applyPlacement()` 执行平移/轴角旋转；恒等 Placement 不创建额外 Shape；成功后释放局部 Shape，缓存只提交变换后的句柄。
- `tests/facade.test.ts`：新增非恒等 Placement 与恒等 Placement 的执行器测试。
- `docs/continuation-status.zh-CN.md`、`config/compatibility-matrix.json` 及两份实施方案：记录本里程碑的能力边界和验证证据。

已完成的当前工作区验证：

```text
./npmw run test:facade  -> 61/61 通过
./npmw run build        -> 通过
```

完整 `./npmw run verify`、`git diff --check` 和 `jq empty config/compatibility-matrix.json` 均已通过；Placement 已作为独立里程碑提交并推送到远端 `main`。

1. 浏览器 OCCT 包围盒黄金证据若无法自动化，保持 P3-03 为 `IN PROGRESS`。
2. TSN generation 历史写回已进入当前工作区；提交后推进候选替换事务与下一批 PartDesign 特征，不把签名回退误标为 OCCT 原生历史。

## 9. 2026-08-03 TSN generation 写回快照

- `geometry.topology()` 同时返回可序列化的面/边/点签名条目；几何执行器只在 generation 被接受且拓扑采集成功后提交 Shape 和 `ObjectTopologySnapshot`。
- 每个对象快照记录 generation、文档版本、迁移 matches 和 `signature-fallback` 历史；拓扑采集失败释放本轮 Shape，最近有效缓存不被覆盖。
- 重算提交遍历 `App::PropertyLinkSub` 与 Sketch 外部几何：稳定引用写回新 generation；歧义/删除引用不强绑，所有者保持 dirty/warning 并产生 `TOPOLOGY_REFERENCE_AMBIGUOUS/DELETED` 诊断。
- schema v6 新增 `objects.topology_json`，fallback 保存/加载已验证快照深克隆；真实 SQLite/OPFS v5→v6 升级尚未进行浏览器实证。
- 完整 `./npmw run verify`、diff/JSON 校验均通过；里程碑已由 `ffbe2c6` 推送。

这仍不是 OCCT/FreeCAD 原生历史：签名来自三角网格，缺少曲面/曲线参数、邻接图和 Boolean 的逐输入原生历史。候选替换事务/UI 已在下一里程碑补齐，但 3D 候选预选与高亮尚未实现，因此 F3/TSN-03/07/09 不能标记完成。

## 10. 2026-08-03 TopoRef 候选替换快照

- 新增 Facade `resolveTopologyReference()` 事务，按所有者、PropertyLinkSub/ExternalGeometry 名称和候选 persistentId 定位引用；候选必须存在于源对象最新拓扑快照且 kind 一致。
- 用户明确选择后写入 stable TopoRef 和最新 generation，重建 `topo-ref` DAG 边，标脏依赖闭包，更新文档版本并进入 Undo/Redo 与自动保存。
- 属性面板对 ambiguous/deleted LinkSub 显示候选菜单；诊断页对 LinkSub 和草图外部几何显示候选替换控件。非法候选拒绝，不修改文档。
- 完整 `./npmw run verify`、diff/JSON 校验通过；Chrome 桌面/移动布局无重叠，SwiftShader 延时截图确认 OCCT canvas 非空；提交和推送仍待执行。

尚未完成 3D 面/边/点候选预选与高亮，也没有真实 OCCT 浏览器黄金回放，因此 TSN-09/F3 仍保持进行中。候选替换里程碑已由 `56903db` 推送。

## 11. 2026-08-03 Mirrored whole-shape 快照

- `geometry.mirror()` 对文档/Shape 句柄、原点和非零法向做 Facade 校验，再调用 Bitbybit `mirrorAlongNormal()`。
- `PartDesign::Mirrored` 文档对象保存 Base、Plane 与 Fuse；Task 更新 Body.Tip 和 DAG。重算按 XY/XZ/YZ 映射法向，Fuse 时 union Base 与镜像副本，并始终释放临时副本。
- 当前是整 Shape 镜像，不是 FreeCAD 对选中特征历史的镜像；平面固定经过文档原点，未接 DatumPlane/Sketch axis/TopoRef 支持，也未证明单实体规则。
- 完整 `./npmw run verify`、diff/JSON 校验通过；里程碑已由 `4aa6ca4` 推送。

## 12. 2026-08-03 MultiTransform whole-shape 快照

- `App::PropertyMultiTransform` 保存最多 6 个有序步骤；每个步骤使用稳定 ID 和 Linear/Polar/Mirrored 判别联合，不解析自由字符串。Facade 写入边界校验枚举、数值、唯一 ID 和笛卡尔组合后的 100 实例上限。
- Task 面板与 Data 属性面板共用步骤编辑器，可添加、删除、切换类型并编辑 Count/Length/Direction、Count/Angle/Axis 或 Plane；提交绑定 Base、更新 Body.Tip，并进入 Undo/Redo、自动保存和深拷贝持久化。
- 重算从 Base whole Shape 开始，每一步作用于前一步的全部实例，最终 union；成功或中途失败都释放镜像/平移/旋转副本，失败不覆盖上一次成功缓存。接受的 generation 继续走统一拓扑采集和写回。
- 合同测试覆盖 Mirrored→Linear 的 6 实例组合、参数映射、完整临时句柄回收、故障注入、最近有效缓存保留、100 实例拒绝、任务提交、深拷贝、Undo/Redo 和 fallback 持久化。

当前实现不是 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` 消费的类型化历史合同。

## 14. 2026-08-03 全功能范围账本与 Bitbybit 构建轨道

新增 [FreeCAD 1.1.1 全功能对标主任务账本](freecad-complete-parity-backlog.zh-CN.md)，以锁定源码 `src/Mod` 的 34 个模块和 `App/Base/Gui/Main` 通用能力为完整范围。账本把任务拆成 `INV`、`BASE`、`BYB`、`CORE`、`TSN`、`SK`、`PART`、`PD`、`FC`、各工作台任务和 `QA/REL` 门禁；源码中的 Sandbox/模板/测试设施以及 Python、宏、插件、偏好、打印和剪贴板均必须有明确能力等级，不得隐藏在“其他”中。

几何实现改为 Bitbybit 优先：先复用 Bitbybit 的 OCCT Worker、建模、IO、三角化、缓存和资源生命周期；公开 API 不足时，从锁定的 Bitbybit/OCCT 源码扩展绑定并用 Emscripten 构建自有 WASM provider。对应 `BYB-01..08` 要求来源提交、补丁、ABI/消息协议、SBOM/许可证、产物 hash、句柄回收和 Bitbybit↔自构建 provider↔FreeCAD 三方黄金差分。React 仍只能通过 `BitBybitWebCadFacade` 访问几何。

兼容矩阵新增 `sourceScope`（34 个模块）和 `geometryBuildStrategy`，并把 AddonManager、Cloud、Fem、Help、Idf、Import、JtReader、Material、Measure、MeshPart、OpenSCAD、Plot、Points、ReverseEngineering、Robot、Show、Start、Web 及开发/测试目录登记为 `scope-only/unsupported`，直到各自任务与证据完成。现有 Part/PartDesign/Sketcher/持久化/FCStd 等状态不提升，仍按实验或只读边界执行。

本机 `FreeCADCmd` reference probe 已接入 `./npmw run probe:freecad-reference`：实测报告为 FreeCAD 1.1.1、commit `0108fd4b4850cc46e625b60e53cea7a7bbe69f8d`、`guiUp=false`；当前构建可加载 `Part`、`Material`、`Measure`，Sketcher/PartDesign/TechDraw/Spreadsheet/Draft/Mesh/Fem/CAM/Assembly 明确 unavailable。探针会采集核心 TypeId 和 Property 元数据，作为 `INV-02` 和后续黄金夹具的输入；完整桌面工作台行为仍需启用对应 FreeCAD 原生模块后再回放。

本轮已把 `geometry.topologyHistory()` provider 接入 `createFacadeGeometryRecomputeExecutor`：对有 Base/Tool/Profile 拓扑输入的特征，若 Worker 提供原生记录，则使用 `captureNativeTopologyHistory()` 按 kind 和 source/result index 生成 `occt-native` 历史；provider 缺失、无输入或不支持时继续使用 `signature-fallback`。新增原生关系映射、删除、重复记录和索引越界测试，完整门禁 68/68 通过。该接线不等于 OCCT 原生历史已可用，真实 Bitbybit/OCCT 自构建绑定仍由 `BYB-04..07` 完成。

新增 `check:bitbybit-history` 绑定面审计并纳入 `./npmw run verify`。审计结果明确记录当前 npm 绑定的原生历史缺口，防止 `occt-native` 合同在没有 Generated/Modified/IsDeleted 实现时被误报为完成。

BYB-01/02 证据已锁定：本地 Bitbybit 源码快照为 `d3f52bd1fcf78148b60800d69ed6b42e53f4ad06`（版本 `1.1.1`），记录于 `config/compatibility-matrix.json`；门禁会同时校验源码提交与安装包版本。

本轮已完成 BYB-04 的第一版实际编译：`native/occt-history` 从缓存 OCCT `bb75017e915f6509a4bfa8b551f853352754c2da`（8.0.0）构建 `TKBO`、`TKDESTEP`、`TKXSBase`、`TKDE` 和 Embind WASM，`./npmw run test:occt-history` 通过，`shapeToStep -> booleanHistoryFromStep(cut)` smoke case 返回 42 条原生关系记录。`mapNativeOcctHistoryRecords` 与 `createNativeOcctStepHistoryBridge` 已把 provider 协议接入 Facade 类型边界。该 provider 当前仍是独立 WASM 实例；跨 Bitbybit 主 WASM 只能通过 STEP 文本序列化交换，不能直接传递指针。

## 15. 2026-08-03 原生 OCCT 历史 + STEP 跨 WASM 桥接

- `native/occt-history` 现从 OCCT `bb75017e...` 编译 `TKBO`、`TKDESTEP`、`TKXSBase` 和 `TKDE`，Embind 暴露 `Generated`、`Modified`、`IsDeleted`、`STEPControl_Reader/Writer`、`shapeToStep` 与 `booleanHistoryFromStep`。
- 原生 smoke 已验证 `shapeToStep(makeBox()) -> STEP text -> booleanHistoryFromStep()`，`cut` 返回 42 条历史记录；最终 wasm 在 Node 22.23.2 可实例化。
- 由于当前 Emscripten/OCCT 大型静态链接的 wasm 异常控制流限制，依赖库固定 `-O0 -fexceptions`，Embind wrapper 固定 `-O2 -fexceptions`；产物 hash 记录在兼容矩阵并由 `check:bitbybit-history` 校验。
- `createNativeOcctStepHistoryBridge()` 已加入 Facade：它只把 Bitbybit `exportStep()` 的文本交给原生 provider，禁止传递跨 WASM ShapeHandle；重算器仅对 `Part::Fuse/Cut/Common` 注入明确 operation，其余特征继续签名回退。

该里程碑仍不是默认 GeometryRuntime，也没有把所有 PartDesign 特征切换到原生 provider；本轮已补齐 `BitbybitGeometryRuntime.configureNativeHistory()`，显式配置后 Boolean 重算会通过 STEP 和协调器消费原生记录。浏览器真实 WASM 实例化、STEP 精度/单位策略和 Bitbybit↔原生↔FreeCAD 三方黄金差分仍是 `BYB-05..08`、`TSN-03..10` 后续门禁。

## 16. 2026-08-03 原生历史协议与故障隔离

- 新增 `NATIVE_OCCT_HISTORY_PROTOCOL_VERSION = 1`，请求携带 `documentId/documentVersion/operationId` 和两份 ISO-10303-21 STEP 文本，响应携带 provider 能力、原生历史和上下文回显。
- `DirectNativeOcctHistoryProvider` 绑定已编译 Embind 模块；`NativeOcctHistoryCoordinator` 统一处理 AbortSignal、超时、取消、stale 文档版本和并发 generation，未把任何 ShapeHandle 放进消息协议。
- Facade 测试新增协议上下文、STEP 格式拒绝、timeout/cancel/stale 覆盖；完整测试数更新为 72/72。

该协议已完成 BYB-05 的类型/合同层，并新增 `NativeOcctHistoryWorkerProvider`/Worker 入口；构建脚本会把产物发布到 `/native/occt-history/`，`BitbybitGeometryRuntime` 可显式配置该 provider 并把 STEP 历史接入 Facade 重算。跨浏览器真实 WASM 实例化、Worker 崩溃恢复和三方黄金差分仍需单独验证，不能把 Node 原生 smoke 当作浏览器证据。

本轮文档变更验证必须使用项目包装器：

```bash
./npmw run verify
git diff --check
jq empty config/compatibility-matrix.json
```

## 17. 2026-08-03 本机 FreeCAD 参考与后续安排

再次执行 `./npmw run probe:freecad-reference` 已确认锁定 oracle 为 FreeCAD `1.1.1`、提交 `0108fd4b4850cc46e625b60e53cea7a7bbe69f8d`。当前缓存构建 `guiUp=false`，可加载 `Part/Material/Measure`；其余工作台是构建缺失证据，不是对应 Web 功能的行为 oracle。

新增 [FreeCAD 1.1.1 全功能对标执行路线图](freecad-reference-execution-roadmap.zh-CN.md)，按 R0 参考环境、R1 几何/拓扑、R2 Sketcher、R3 参数化核心、R4 FCStd、R5-R8 工作台与平台长尾、R9 发布门禁连续执行。近期先完成完整桌面 O2 oracle、机器清册差分、真实浏览器原生历史三方黄金，再进入 planegcs 与 PartDesign 完整闭环。