# FreeCAD Web 移植状态与完成边界

更新时间：2026-08-23

这份报告说明当前项目已经由真实 FreeCAD C++/Python 源码移植到 WASM 的能力、证据位置，以及仍然阻断完整对标的外部条件。它是交接文档，不替代 `docs/current/task-state.json`、任务卡或 JSON 证据。

## 已完成

以下模块已经完成对应 Y gate，并有独立的 native WASM、Facade/Worker、Chrome 或持久化证据：

`Assembly`, `BIM`, `CAM`, `Cloud`, `Draft`, `Fem`, `Help`, `Import`, `Inspection`, `JtReader`, `Material`, `Measure`, `Mesh`, `MeshPart`, `OpenSCAD`, `Part`, `Points`, `Sandbox`。

本轮新增的可复核动作包括：

- PartDesign `inspect/source-inventory`：8 个 native 注册类型、错误恢复、Facade/Worker、Chrome 151 回放。
- PartDesign `python-api`：真实 `makeFilletArc` Python 导出和 2 个生成 binding 单元、Facade/Worker、Chrome 回放。
- Points `save/reopen`：真实 `Points::Feature` 三点 FCStd 保存、关闭、重开、对象/边界校验、Facade/Worker、Chrome 回放。

对应证据位于 `docs/p6/partdesign-action-02-*`、`docs/p6/partdesign-action-03-*` 和 `docs/p6/points-action-04-*`。

## 当前阻断

### Sketcher / PartDesign restore

真实 FCStd 保存成功，但 GUI-free WASM 的 `Document::restore` 稳定返回：

```text
map::at: key not found
```

已验证的恢复尝试包括：移除 Sketcher constraint、关闭 `UseHasher`、使用 `restore(delaySignal=false)`，均未改变结果。证据：

- `docs/p6/sketcher-action-04-kernel.json`
- `docs/p6/sketcher-action-04-kernel-r2.json`
- `docs/p6/sketcher-action-04-kernel-r3.json`
- `docs/p6/partdesign-action-04-kernel-r1.json`

在共享 `Document::restore`/ElementMap 修复前，不得把这两个模块的 save/reopen 或 Y gate 写成通过。

### 缺失 Web probe 或 GUI 依赖

以下模块已有源码边界，但当前配置没有可链接的 GUI-free Web runtime probe，或依赖 Qt/PySide/FreeCADGui：

`Plot`, `ReverseEngineering`, `Robot`, `Show`, `Spreadsheet`, `Start`, `Surface`, `TechDraw`, `TemplatePyMod`, `Test`, `Tux`, `Web`。

每个模块的首个阻断、复现命令和恢复动作均保存在对应 `docs/p6/*-runtime.json` 与 `docs/tasks/p6/*/*-R1.md`。

## 架构合同

- 内核、计算、文件格式、Python module 和持久化必须由 FreeCAD 原生源码执行。
- TypeScript 只负责 Worker、Facade、消息 envelope、取消/重复请求和 UI 适配。
- Chrome 证据固定为 Google Chrome、`headless-new`、`1440x900`、DPR 1，并要求外部请求与运行时异常为 0。
- `docs/current/task-state.json` 是唯一任务状态源；`nextTask.md` 只是续接入口。

## 复现与恢复顺序

1. 运行 `python3 tools/validate_web_context.py` 和 `python3 tools/prepare_web_task_context.py`。
2. 只读取当前 manifest 的 `mode=read` 文件。
3. 优先修复共享 `Document::restore`/ElementMap，再重跑 Sketcher 与 PartDesign 原始 fixture。
4. 为缺失 probe 的模块补充真实 C ABI/WASM target；GUI-only 模块需要明确 GUI/PySide 依赖闭包，不能用静态 JS 替代。
5. 每个动作完成 C-G 后再关闭动作卡，最后由 Y gate 改变模块状态。

当前账本在 `FW-P6-SKT-ACT-04-C-R1` 恢复卡停留，校验器通过但没有依赖满足的 planned 叶子。任何继续工作都必须先解决上述 native 或外部依赖阻断。