# FreeCAD 1.2 Web/WASM 技术基线

## 执行铁律

- 浏览器测试只执行 Google Chrome（桌面 Chrome 或 Chrome 移动设备仿真）；Firefox、WebKit 和 Safari 不执行、不纳入当前矩阵、不作为发布阻断项。
- 既有 Firefox/WebKit/Safari 记录只作历史追溯，不能作为当前 Chrome 通过或失败的替代证据。
- 每个浏览器任务卡必须明确 Chrome 版本、运行模式、viewport 和证据文件；若 Chrome 不可用，任务应保留首个环境错误并停止，不切换到其他浏览器掩盖缺口。

> 稳定背景文档。执行者通常不需要通读本文件；先读当前任务卡和直接前置证据。
> 上下文预算与状态协议见 [`FREECAD_WEB_CONTEXT_PROTOCOL.md`](FREECAD_WEB_CONTEXT_PROTOCOL.md)；当前续接见 [`FREECAD_WEB_HANDOFF.md`](FREECAD_WEB_HANDOFF.md)。

## 目标与边界

唯一产品基线是当前 checkout 的 FreeCAD 1.2，目标按源码完整对标，不以查看器或少量 Part 功能替代桌面能力。未实现能力保持 `pending`，只有 gate 能晋级里程碑。

必须满足：

1. 每个任务只关闭一个可观察合同，失败可从日志和产物续接。
2. 浏览器主线程只负责 UI/渲染，文档与几何运算在 Worker 串行执行。
3. FreeCAD Document 是权威状态，前端状态只保存投影。
4. FCStd 是主文档格式，OPFS/缓存不改变文件语义。

## 源码与依赖基线

| 项目 | 值 |
|---|---|
| 源码 | `FreeCAD/freecad-source` |
| revision | `4f4e9244e613ea2df06e70027074a562695048cb` |
| CMake | `1.2.0dev` |
| OCCT / Qt / Python / Coin3D | `7.6.3 / 5.15.13 / 3.12.3 / 4.0.2` |
| Emscripten | `3.1.6` |
| 依赖锁定 | `FreeCAD/FreeCADBaseLib/sources.lock.tsv` |

已验证：OCCT、QtCore/QtXml、CPython、PyCXX、XercesC、zlib、Boost 具备 WASM 静态产物；FreeCADBase/App/Part/PartDesign/Sketcher 核心归档可构建；STEP、Worker、Three.js、OPFS、网格缓存通过 P1；Part 类型和 Document 生命周期通过 P2.1/P2.2；FCStd、事务、Undo/Redo 和中断恢复通过 P2.3。

## 目标架构

```text
Browser UI (React/TypeScript + Three.js)
              |
              v
Typed FreeCADWebFacade messages
              |
              v
Dedicated Kernel Worker (Document actor -> C++/OCCT WASM)
              |
              v
OPFS (FCStd, imports, recovery, mesh cache)
```

- 一个文档只由一个 Worker 修改；消息按 request id 在单一队列顺序执行。
- C ABI 只暴露稳定句柄、值类型和错误字符串；JS 不持有原生指针。
- 网格使用 transferable typed arrays；B-Rep 和 Document 留在 Worker。
- 缓存失败不得阻断导入或重算。

## 构建与合同边界

`FREECAD_WEB` 是显式入口，桌面默认配置不变。最小闭包为 `FreeCADBase`、`FreeCADApp`、`Materials`、`Part`、`PartDesign`、`Sketcher`、`Import`、`Measure`。新增模块按“依赖 probe -> 静态注册 -> C ABI contract -> 浏览器 slice -> gate”进入。

运行时合同包括：C++/OCCT 异常固定错误返回、幂等初始化、整数句柄、稳定类型/属性校验、FCStd 临时文件校验后原子替换、导入参数与源文件 hash 绑定。P2 只提供 Document 生命周期所需的嵌入 Python；P4 才建立受限 Python Worker、静态工作台注册和插件包格式，不承诺 PySide/Pivy/桌面动态模块直接可用。

## 风险控制

| 风险 | 必须留下的证据 |
|---|---|
| Python/Qt 隐式依赖 | 链接与运行时 probe |
| 类型重复注册 | 幂等计数与多次调用 smoke |
| FCStd 损坏 | 保存、关闭、重开、对象/属性校验 |
| 拓扑漂移 | 稳定 id、子元素映射、回归模型 |
| 浏览器内存/卡顿 | 初始、增长、峰值、释放和 Worker 性能预算 |
| 工作台遗漏 | 源码生成的 P3 对标矩阵 |

历史调查和早期任务记录：`FreeCAD/docs/archive/`。