Web_FreeCAD_Bitbybit/docs/freecad-full-parity-plan.zh-CN.md

# 完整 FreeCAD 对标实施方案

> 本文是“功能完全对标 FreeCAD”的工程基线和任务分解，不把当前已有的页面、MockFacade 或少量 OCCT 特征误报为完成。所有“支持”都必须经过锁定版本 FreeCAD 的行为黄金测试和文件互操作测试。

## 1. 目标与边界

### 1.1 目标

以 FreeCAD `1.1.1` 官方发布标签为首个兼容基线，精确源码提交为 `0108fd4b4850cc46e625b60e53cea7a7bbe69f8d`。实现可在浏览器运行的 CAD 应用：React 负责 FreeCAD 风格界面，Three.js 最新锁定版本负责三维显示，Bitbybit 是唯一入口，FreeCAD/OCCT 业务逻辑在 WASM Worker 中运行，SQLite WASM + OPFS 负责项目、文档、对象、事务和资源存储。

### 1.2 唯一入口原则

对 React 和页面公开的唯一业务入口是 `BitBybitWebCadFacade`。页面不得直接导入 Three.js、OCCT、OCCT Worker、SQLite 或 OPFS；这些实现只能由 Facade 适配器和 Worker 使用。新增工作台、命令、属性、文件格式和诊断，必须先扩展版本化 Facade 合同，再接入页面。

### 1.3 “完整对标”的可验收定义

| 等级 | 含义 | 允许的产品表述 |
|---|---|---|
| `exact` | 与基线 FreeCAD 在输入、状态、结果、错误、选择和持久化语义上逐项一致 | “已对标” |
| `compatible` | 结果和核心交互一致，允许明确记录的浏览器呈现差异 | “兼容” |
| `read-only` | 可读取、可显示、可导出，但不能安全编辑和重算 | “只读” |
| `proxy` | 保留未知对象、属性或 Shape 资产，不能保证语义重算 | “代理” |
| `unsupported` | 有意拒绝并生成结构化诊断 | “不支持” |

没有黄金测试、差异报告和迁移策略的功能，不得标记为 `exact` 或 `compatible`。浏览器限制必须体现为能力矩阵和用户可见诊断，不能静默删除 FreeCAD 行为。

## 2. 当前差距与解决策略

| 领域 | 当前切片 | 达到对标还缺少的核心能力 | 主任务包 |
|---|---|---|---|
| 拓扑命名 | 有 `SubshapeRef` 类型和句柄生命周期 | 历史映射、持久名称、歧义检测、版本迁移 | TSN |
| Sketcher | 有轮廓输入验证 | 几何/约束模型、Planegcs 求解、编辑器交互、外部几何 | SK |
| Expression/单位 | Property metadata 可声明单位 | 词法/语法、Quantity、维度检查、引用、循环和 locale | EXU |
| 依赖 DAG/重算 | 有事务和版本号 | Link 图、SCC、调度、取消、增量结果、错误传播 | DAG |
| Part/PartDesign | 已有部分 Primitive/Boolean/Pad/Pocket/Revolution | 完整特征、Body/Tip、附着、模式、失败恢复 | PD/PART |
| 工作台 | manifest 和界面骨架 | Draft、TechDraw、Spreadsheet、Assembly、BIM、CAM、FEM、Mesh 等业务 | WB |
| 文件 | 项目 schema v1、资源对象 | FCStd 读写、BREP/GuiDocument、扩展/代理、格式导入导出 | FC |
| 质量 | Facade Node 测试和部分浏览器矩阵 | FreeCAD 对照回放、几何黄金、压力、跨浏览器和安全门禁 | QA |

## 3. 总体架构与不可破坏的约束

### 3.1 分层

1. **Presentation**：React 页面、FreeCAD 菜单/工具栏、Combo View、Tasks、Property editor、Report view、快捷键和无障碍。
2. **Facade**：`App/Gui/Workbench/Command/Selection/Task/Project/Viewport` 合同、权限、前置条件、请求上下文、诊断、事件和版本。
3. **Domain kernel**：Document、DocumentObject、Property、Link、Expression、Sketch、Feature、Body/Tip、事务、DAG、重算。
4. **Geometry**：Bitbybit OCCT API 和必要的 FreeCAD/OCCT C++ 模块 WASM 化；B-Rep 句柄仅在 Worker 内部存在。
5. **Workers**：几何、求解、重算、持久化各自独占 Worker；消息带 `requestId`、`documentId`、`documentVersion`、取消和诊断。
6. **Persistence**：SQLite WASM OPFS 单写者、项目迁移、资源内容寻址、事务日志、恢复和导入导出。

### 3.2 领域不变量

- 对象 UUID、内部名称和子形状名称永不使用显示 Label 代替。
- 所有长度、角度、面积、体积在内部使用有维度的 Quantity；数据库保存规范单位和原始表达式。
- 任何重算结果只有在请求版本仍等于当前文档版本时才能提交；过期结果必须丢弃。
- 依赖循环、求解冲突、拓扑歧义和未知文件对象必须显式失败并保留诊断。
- Undo/Redo、自动保存和资源引用计数必须以同一事务边界提交。
- Worker 结果不可直接改变 React 状态，必须经 Facade 校验和事件投影。

## 4. 专项一：稳定子形状命名（TSN）

### 4.1 目标

实现与 FreeCAD 特征历史可比的 `TopoRef`：面、边、顶点、壳、实心体和 Compound 在特征重算、参数编辑、保存/加载、布尔操作和导出后仍能被稳定引用；无法唯一判断时返回 `ambiguous`，绝不把错误的面静默绑定给另一个面。

### 4.2 技术措施

1. 在 OCCT Worker 内保留每次特征的输入 Shape、输出 Shape、历史对象和拓扑签名；使用 `Generated/Modified/Deleted` 历史关系生成映射。
2. 为每个子形状计算规范签名：拓扑类型、几何类型、解析几何参数、几何中心/长度/面积/体积、邻接度数、方向、局部坐标和量化容差。签名必须区分“用于匹配的特征”与“仅用于诊断的数值”。
3. 采用分层命名：`documentId/objectUuid/featureRevision/subshapeKind/localOrdinal`，再绑定跨版本映射记录；不使用 OCCT transient hash 或三角网格索引作为持久 ID。
4. 对对称、重复和布尔切分结果建立候选集合和评分；最高分不超过唯一阈值时返回歧义，并在 UI 的选择/任务面板显示候选。
5. 保存 `TopoRef` 的来源特征版本、签名、映射算法版本和容差；加载旧版本先迁移，迁移失败保留原引用和报告。
6. 将面/边选择、附着、Fillet/Chamfer、Pocket up-to-face、TechDraw 投影、测量和表达式引用全部改用 `TopoRef`。

### 4.3 任务分解

| ID | 任务与交付物 | 前置 | 验收 |
|---|---|---|---|
| TSN-01 | 从基线 FreeCAD 采集拓扑命名、选择和错误行为 | P0 | 30 个模型有输入/输出映射 |
| TSN-02 | 定义 `TopoRef`、状态和迁移 JSON Schema | P1 | exact/ambiguous/deleted 均可序列化 |
| TSN-03 | OCCT 历史捕获适配器 | P3 | Pad/Pocket/Boolean 产生 Generated/Modified/Deleted 集 |
| TSN-04 | 规范几何/邻接签名库 | TSN-02 | 相同 B-Rep 重放签名稳定，网格精度变化不影响 |
| TSN-05 | 一对一匹配和评分算法 | TSN-03/04 | 平移、参数编辑和重算保持引用 |
| TSN-06 | 对称/重复拓扑歧义检测 | TSN-05 | 低置信度拒绝错误绑定并给出候选 |
| TSN-07 | 布尔与多实体历史映射 | TSN-03 | Union/Cut/Common 后选择引用可迁移 |
| TSN-08 | 引用持久化、版本迁移和回滚 | FC-02 | 保存/加载后 UUID 与状态不变 |
| TSN-09 | Facade 选择、附着和任务 API 接入 | TSN-02 | React 无内部拓扑 API 导入 |
| TSN-10 | 拓扑黄金回放与随机变异测试 | QA-02 | 100 个黄金模型、1000 次参数变异通过 |

## 5. 专项二：Sketcher 求解器（SK）

### 5.1 目标

达到 FreeCAD Sketcher 的约束建模和交互语义：几何创建/编辑、约束、自由度、冗余/冲突诊断、拖拽、外部几何、支持的曲线类型、B-spline、块约束、构造几何、投影和编辑事务。

### 5.2 技术路线

- 优先将 FreeCAD Sketcher 的 `planegcs`/相关 C++ 求解器以独立 WASM 模块编译，固定编译器、Emscripten、浮点和异常策略；Bitbybit Facade 只调用类型化求解服务。
- 若某一模块无法直接编译，先做等价 C++/WASM 端口并建立逐案例差异报告；禁止用页面 JavaScript 中的近似求解器冒充兼容。
- 求解 Worker 采用确定性输入排序、固定容差、最大迭代次数和取消点；输出几何、自由度、约束状态、冲突集合、残差和诊断。

### 5.3 任务分解

| ID | 任务与交付物 | 前置 | 验收 |
|---|---|---|---|
| SK-01 | 采集 Sketcher 几何/约束/快捷键/错误 manifest | P0 | 覆盖所有基线命令和约束类型 |
| SK-02 | 定义 Sketch 文档对象、几何索引和构造标志 | P1 | SQLite/Facade 可往返 |
| SK-03 | 编译 planegcs 求解器 WASM POC | P0-RT | 直线/圆/弧约束结果与 FreeCAD 一致 |
| SK-04 | 确定性求解协议和 Worker 生命周期 | SK-03 | 取消/过期版本不会提交 |
| SK-05 | 基础几何 API：点、线、圆、弧、椭圆、B-spline | SK-02 | 编辑/撤销/重做完整 |
| SK-06 | 基础约束：Coincident、Horizontal、Vertical、Distance、Angle | SK-04/05 | 自由度和残差黄金一致 |
| SK-07 | 高级约束：Tangent、Equal、Symmetric、Block、Diameter、Radius | SK-06 | 冲突/冗余分类一致 |
| SK-08 | 外部几何、构造几何和投影 | TSN-09 | 选择引用可稳定重算 |
| SK-09 | 拖拽、自动约束、约束编辑器和任务面板 | SK-06 | 鼠标/键盘回放与桌面行为一致 |
| SK-10 | B-spline 编辑、节点/权重和约束限制 | SK-07 | 支持范围明确，无静默降级 |
| SK-11 | Sketch 支持 Pad/Pocket/Revolution 和附着面 | TSN-07/DAG-07 | 轮廓修改触发正确重算 |
| SK-12 | Sketch 黄金文件和求解压力套件 | SK-01..11 | 500 个模型、冲突/欠约束/过约束覆盖 |

## 6. 专项三：Expression 与单位系统（EXU）

### 6.1 目标

与 FreeCAD Quantity/Expression 语义对齐：单位后缀、复合单位、维度检查、对象/属性引用、Spreadsheet 别名、函数、常量、locale 显示、表达式错误和循环诊断。数据库必须同时保留规范 Quantity 与用户输入表达式。

### 6.2 技术措施

1. 词法、解析、类型检查和求值在独立 Worker 完成；UI 只显示 token、候选和诊断。
2. 采用有理数/高精度数值表示可精确保存单位换算；几何内核边界再转换为固定精度浮点。
3. 单位注册表包含维度向量、规范单位、别名、比例/偏移转换和显示格式；所有单位表有版本号。
4. 表达式解析产生依赖边，和对象 Link 一起进入统一 DAG；禁止通过字符串扫描绕开依赖和循环检测。
5. 序列化使用规范 locale（`.` 小数、显式单位 ID），显示 locale 只在 Presentation 层转换。

### 6.3 任务分解

| ID | 任务与交付物 | 前置 | 验收 |
|---|---|---|---|
| EXU-01 | 采集 FreeCAD 单位 schema、表达式函数和错误 | P0 | 建立可机器读取清单 |
| EXU-02 | Quantity/Unit/Dimension 类型与 SQLite schema | P1/FC-02 | 长度、角度、面积、体积可往返 |
| EXU-03 | 表达式 tokenizer/parser AST | EXU-01 | 运算符优先级和函数错误一致 |
| EXU-04 | 维度推导、转换和舍入规则 | EXU-02/03 | `mm+inch`、角度/长度混用按基线拒绝 |
| EXU-05 | 对象属性、Spreadsheet alias 和子形状引用 | TSN-02/DAG-02 | 引用重命名不丢失 |
| EXU-06 | 循环、未知符号、过期引用诊断 | DAG-04 | 错误包含对象/属性/表达式位置 |
| EXU-07 | locale 显示、自动完成和属性编辑器 | EXU-03 | 显示变化不改变规范序列化 |
| EXU-08 | 表达式迁移、导入导出和黄金测试 | FC-05 | 1000 条表达式跨版本一致 |

## 7. 专项四：依赖 DAG 与重计算（DAG）

### 7.1 目标

实现 FreeCAD 文档对象的依赖、Touched/Copy/Recompute 状态和事务语义：Link、Expression、子形状、Body/Tip、外部文档和视图依赖都进入统一有向图；重算按稳定拓扑序执行，循环和失败按对象传播。

### 7.2 技术措施

- 图节点为 `DocumentObject` 的计算版本，边包含 Link、Expression、TopoRef、Container 和 View 依赖类型。
- 每次参数事务生成 immutable snapshot、dirty set 和 recompute generation；使用 Tarjan/Kosaraju 检测 SCC，循环节点不运行几何。
- 调度器按依赖层级把可并行节点分发给 Geometry/Solver Worker；结果带 generation 和输入 hash，只有匹配时提交。
- 一个节点失败不覆盖上一次有效 Shape；下游进入 `UpstreamFailed`，Report view 可定位根因。
- Undo/Redo 恢复参数、图、状态和 Shape 资源引用；保存只提交已确认版本。

### 7.3 任务分解

| ID | 任务与交付物 | 前置 | 验收 |
|---|---|---|---|
| DAG-01 | Link/Expression/TopoRef 统一边模型 | TSN-02/EXU-05 | 图可解释每条边的来源 |
| DAG-02 | 对象注册、删除传播和反向索引 | P4-01 | 删除前显示受影响对象 |
| DAG-03 | Touched/Up-to-date/Error 状态机 | P4-04 | 状态转换与 FreeCAD 回放一致 |
| DAG-04 | SCC 循环检测和诊断 | DAG-01 | 循环不进入 OCCT/Sketch 求解 |
| DAG-05 | 稳定拓扑排序和并行层 | DAG-04 | 相同输入顺序可复现 |
| DAG-06 | generation、取消和过期结果丢弃 | P1-03 | 快速连续编辑不回写旧结果 |
| DAG-07 | Body/Tip、容器、Feature 链和支持映射 | DAG-05/TSN-07 | PartDesign 链正确显示 Tip |
| DAG-08 | 失败保留、下游传播和恢复 | DAG-07 | 修复上游后仅重算必要节点 |
| DAG-09 | 事务/Undo/Redo/Autosave 原子提交 | P2-04 | 崩溃恢复不出现半个图 |
| DAG-10 | DAG 可视化、诊断和性能计数器 | DAG-08 | 用户可定位耗时/失败节点 |
| DAG-11 | 1000 对象、长链、宽图、随机图基准 | DAG-01..10 | 记录内存、吞吐、取消和尾延迟 |

## 8. 专项五：核心业务对象与剩余工作台（WB）

### 8.1 共通实施规则

每个工作台都必须完成四份资产：`workbench-manifest.json`（菜单、命令、快捷键、任务面板和前置条件）、对象/属性 schema、Facade API、FreeCAD 黄金回放集。只有页面按钮存在而命令状态、选择过滤、重算和文件兼容未完成时，状态仍为 `ui-only`。

### 8.2 工作台分解

| 工作台 | 业务范围 | 主要任务 | 进入条件 |
|---|---|---|---|
| PartDesign | Body、基准、草图、Pad/Pocket、Dress-up、Pattern、Boolean、Additive/Subtractive | PD-01..PD-18：附着、支持面、两长度、Draft、Fillet/Chamfer、Hole、Pattern、Thickness、Tip | SK、TSN、DAG |
| Part | 原语、布尔、管道、阵列、变换、检查/修复、导入导出 | PART-01..PART-16：ShapeBinder、CompSolid、Refine、Make compound、容差和修复 | TSN、DAG |
| Sketcher | 见 SK 专项 | SK-01..SK-12 | Solver WASM |
| Draft | 2D 绘图、尺寸、阵列、图层、Working Plane、BIM 辅助 | DRAFT-01..DRAFT-14：吸附、网格、文本、样条、偏移和参数化 | EXU、DAG |
| TechDraw | 页面、视图、投影、尺寸、模板、SVG/PDF 导出 | TD-01..TD-15：隐藏线、剖视、链接视图、模板兼容和打印比例 | TSN、FC |
| Spreadsheet | 单元格、公式、别名、格式、链接和导出 | SS-01..SS-10：表达式依赖、循环、CSV/XLSX 边界和大表性能 | EXU、DAG |
| Assembly | 组件、连接器、约束、求解、变体、BOM | ASM-01..ASM-16：组件链接、joint solver、装配树、碰撞和导出 | DAG、TSN |
| BIM/Arch | 结构/建筑对象、材料、楼层、墙/梁/窗、IFC | BIM-01..BIM-20：属性集、族、空间、IFC2x3/IFC4 映射和代理 | FC、EXU |
| FEM | 材料、网格、边界、求解器、结果 | FEM-01..FEM-18：网格接口、求解器 WASM 构建、结果场和单位 | EXU、WB 安全门 |
| Mesh | 网格导入、修复、布尔、简化、分析和导出 | MESH-01..MESH-14：法向、非流形、误差、LOD 和大网格 Worker | FC、QA |
| Surface | 曲面创建、偏移、放样、填充、修剪、缝合 | SURF-01..SURF-14：NURBS/BSpline 参数、边界和缝合容差 | OCCT 扩展、TSN |
| CAM | Job、刀具、路径、后处理、仿真和 G-code | CAM-01..CAM-20：刀具库、碰撞、后处理器沙箱、单位和输出黄金 | FEM/Mesh 可选，安全门 |
| Inspection/Measure | 测量、剖切、偏差、标注和报告 | INSP-01..INSP-10：TopoRef 选择、精度、报告和导出 | TSN、EXU |
| Raytracing/Robot/其他 | 基线版本清单中的其余官方模块 | WB-REST-01..WB-REST-20：逐模块决定 WASM 端口或明确不支持 | P0 manifest |

### 8.3 工作台交付顺序

先完成 `PartDesign + Part + Sketcher + TechDraw + Spreadsheet` 的参数化闭环，再做 Draft/Assembly/BIM/Mesh/Surface，最后处理 FEM/CAM/Raytracing 等需要额外数值库或后处理器的模块。每个工作台在进入下一层前必须通过对象创建、编辑、重算、撤销、保存、加载和导出七项门禁。

## 9. 专项六：文件兼容与迁移（FC）

### 9.1 兼容范围

1. **FCStd 读取**：ZIP 容器、`Document.xml`、`GuiDocument.xml`、BRep/Shape 资源、缩略图、对象属性、Expression、Link、视图状态和未知扩展。
2. **FCStd 写入**：生成 FreeCAD 1.1.1 可打开的最小等价文件；写入前完成 schema、内核和工作台能力检查。
3. **项目格式**：继续维护 `.webcad` manifest、SQLite schema、OPFS 资源包和迁移版本；FCStd 与 `.webcad` 不混用语义。
4. **交换格式**：STEP/IGES/BREP、STL/OBJ/PLY、SVG/PDF、DXF、glTF、IFC、CSV；每种格式记录精度、颜色、单位、拓扑和只读限制。
5. **未知对象**：保留原始 XML/资源和 proxy Shape，显示兼容报告；禁止执行 FCStd 中的 Python、宏或任意代码。

### 9.2 任务分解

| ID | 任务与交付物 | 前置 | 验收 |
|---|---|---|---|
| FC-01 | 采集 FCStd 文件结构和 FreeCAD 读写样例 | P0 | 每个核心对象有最小/复杂样例 |
| FC-02 | `.webcad`/SQLite schema v2 与迁移框架 | P2 | 迁移可回滚、旧版本可读 |
| FC-03 | ZIP 安全读取、大小/路径/压缩比限制 | FC-01 | zip bomb、路径穿越、恶意 XML 被拒绝 |
| FC-04 | Document/GuiDocument XML 映射 | P4/DAG | 树、属性、视图状态可往返 |
| FC-05 | BRep/Shape 资源读写和精度策略 | P3 | 体积、拓扑数和几何容差有报告 |
| FC-06 | Expression/Unit/Link/TopoRef 序列化 | EXU/TSN/DAG | 保存后可重算或明确 proxy |
| FC-07 | 未知对象/扩展 proxy 和差异报告 | FC-04 | 不丢原始资源、不假称可编辑 |
| FC-08 | STEP/IGES/BREP 导入导出 | PART | 100 个模型几何黄金通过 |
| FC-09 | Mesh/DXF/SVG/PDF/glTF/IFC/CSV 适配 | WB | 单位、颜色、精度和失败诊断正确 |
| FC-10 | FreeCAD↔WebCAD round-trip 测试 | FC-04..09 | 读→改→写→读的语义差异可解释 |
| FC-11 | 大文件、损坏文件和中断恢复 | FC-03 | 2 GB 级别按能力矩阵降级，不崩溃 |

## 10. 实施阶段与依赖

| 阶段 | 必须完成的结果 | 依赖 | 阶段门 |
|---|---|---|---|
| F0 基线冻结 | FreeCAD 提交/构建容器、Bitbybit/OCCT、Three、SQLite、浏览器、许可证和黄金样例 | 无 | G0：版本、来源、SBOM 完整 |
| F1 Facade/文档核心 | DocumentObject、Property、事务、选择、任务、诊断和 schema | F0 | G1：React 仅能通过 Facade 编译 |
| F2 表达式/单位/DAG | Quantity、Expression、统一依赖图、SCC、重算和恢复 | F1 | G2：1000 对象图和循环/错误黄金通过 |
| F3 稳定拓扑命名 | 历史映射、歧义、安全引用和迁移 | F2 + OCCT | G3：参数编辑/布尔/保存加载引用稳定 |
| F4 Sketcher | Solver WASM、约束、编辑器、外部几何和轮廓输出 | F2/F3 | G4：欠约束/冲突/拖拽/回放通过 |
| F5 Part/PartDesign 闭环 | Body/Tip、基准、特征、附着、DAG、Undo、FCStd | F3/F4 | G5：核心参数化建模闭环 |
| F6 TechDraw/Spreadsheet/Draft | 页面、投影、公式表、2D 参数化 | F2/F3/F5 | G6：核心生产文档可保存导出 |
| F7 Assembly/BIM/Mesh/Surface | 工作台对象、求解/几何和互操作 | F3/F5/F6 | G7：各工作台七项门禁 |
| F8 FEM/CAM/其余模块 | 数值库、后处理器、仿真和明确能力矩阵 | F0/F7 | G8：每个模块 exact/compatible/read-only/proxy |
| F9 发布验收 | 全量回放、跨浏览器、性能、安全、迁移和回滚 | F0..F8 | G9：无未解释的 unsupported 核心路径 |

## 11. 详细任务包（跨领域共通）

| ID | 任务 | 交付物 | 验收标准 |
|---|---|---|---|
| P0-01 | 固定 FreeCAD 源码、编译器和依赖镜像 | lock、容器、构建日志 | 同一输入产生相同版本信息 |
| P0-02 | 生成 UI/命令/对象/Property/工作台 manifest | JSON manifest | 每条能力有来源和等级 |
| P0-03 | 建立 100 个黄金文件、50 个错误文件、回放脚本 | fixtures、expected | 桌面结果可复现 |
| P0-04 | 固定浏览器能力矩阵和 COOP/COEP | browser matrix | Chrome/Firefox/Safari 最新两个版本有结果 |
| P0-05 | 许可证、供应链、WASM 安全评审 | SBOM、许可证清单 | 无未知二进制和高风险漏洞 |
| API-01 | Facade API 版本化和 JSON Schema | `src/facade` 合同 | 破坏性变更有迁移和弃用期 |
| API-02 | 统一请求上下文、取消、进度和诊断 | protocol types | 过期结果无法提交 |
| API-03 | 事件溯源与状态投影 | event log/reducer | 刷新后状态可重建 |
| APP-01 | Document/Object/Property 完整模型 | schema + adapter | Data/View、只读、隐藏、枚举、Link 全覆盖 |
| APP-02 | Transaction/Undo/Redo/Autosave 原子化 | transaction service | 崩溃点恢复无半提交 |
| APP-03 | Body/Container/Group/Link/Extension | object types | 树与依赖图一致 |
| GEO-01 | OCCT C++/WASM 构建和版本隔离 | build scripts | 资源、符号、许可证可追溯 |
| GEO-02 | Shape 生命周期、引用计数和 Worker 回收 | handle service | 长会话无不可控增长 |
| GEO-03 | B-Rep→Three 网格、选择和增量缓存 | viewport adapter | 选择不重建无关对象 |
| GEO-04 | 几何精度、容差和确定性 | tolerance policy | 体积/面积/拓扑黄金稳定 |
| QA-01 | 单元/属性/解析器/图算法测试 | tests | 分支和错误分类达标 |
| QA-02 | FreeCAD CLI/GUI 回放对照器 | comparator | 差异含输入、版本、对象和数值 |
| QA-03 | 浏览器 E2E、视觉和几何黄金 | Playwright fixtures | 三浏览器能力结果可审计 |
| QA-04 | 性能/内存/取消/恢复压力 | benchmark reports | P95、峰值内存、失败率达门槛 |
| QA-05 | 安全测试和 fuzzing | corpus/reports | 文件、表达式、Worker 消息不可越权 |

## 12. 每个功能的开发模板

1. 在基线 manifest 登记 FreeCAD 命令、对象、属性、选择前置和错误。
2. 先写 Facade 类型、请求上下文、诊断和事件，再写 Worker/domain 实现。
3. 添加最小成功、失败、取消、Undo/Redo、保存/加载和过期结果测试。
4. 建立 FreeCAD 对照 fixture，记录几何容差、单位、拓扑和状态差异。
5. 接入 React 页面和 FreeCAD 风格任务面板；页面不直接访问内部实现。
6. 更新 SQLite migration、`.webcad`/FCStd 映射、兼容矩阵和文档。
7. 通过阶段门后才把状态从 `experimental` 提升为 `compatible` 或 `exact`。

## 13. 质量门禁与发布阻断条件

发布必须同时满足：`./npmw run verify`、Facade-only 依赖守卫、所有核心黄金回放、FCStd round-trip、跨浏览器 OPFS/Worker、几何精度、长会话内存、安全 fuzzing 和许可证检查。下列任一项阻断发布：

- 旧版本/未知对象被静默删除或当作可编辑对象；
- 过期 Worker 结果覆盖新版本文档；
- 子形状歧义被强行绑定；
- Expression 单位错误、循环或 locale 转换被静默吞掉；
- FCStd 读取后保存造成未报告的对象、属性、Shape 或视图丢失；
- 任一页面绕过 `BitBybitWebCadFacade` 导入内部 Worker、OCCT、Three 或 SQLite；
- 性能/内存超出能力矩阵而没有明确降级和诊断。

## 14. 下一轮实际执行顺序

1. 使用项目本地 Node 运行时完成 P0-RT、依赖安装和验证，清除引擎警告。
2. 完成 P0-01/P0-03：FreeCAD 提交、构建容器、manifest 和黄金模型目录。
3. 实现 `DAG-01..DAG-06` 与 `EXU-01..EXU-06`，让属性修改从“Touched 标记”升级为可解释的依赖重算。
4. 实现 `TSN-02..TSN-07`，再把附着、Pocket up-to-face、测量和 TechDraw 选择切换到 `TopoRef`。
5. 编译/验证 `SK-03`，然后按基础约束→高级约束→编辑器→PartDesign 轮廓的顺序推进。
6. 以 PartDesign 核心闭环为第一条完整垂直链，随后接入 FCStd 读写和 round-trip。
7. 按工作台表逐个实现并验收，任何暂未端口的模块保持 `read-only/proxy/unsupported`，不提前宣称完整。

## 15. 完成定义

“完整 FreeCAD 对标”只有在 F0-F9 全部阶段门通过、核心与扩展工作台均有兼容等级、稳定子形状命名/Sketcher/Expression/单位/DAG/重算/FCStd 均有黄金报告、跨浏览器和安全门禁通过，并且发布文档列出所有差异后才能使用。当前仓库仍处于核心 Facade、OCCT 几何和属性编辑的进行中阶段，下一工作目标按第 14 节执行。

## 16. 已实现切片与剩余边界

本轮已完成 `EXU-02..EXU-06` 的基础版本：Quantity 以 mm/deg 等规范单位保存，表达式支持四则运算、对象属性引用和维度错误；已完成 `DAG-01..DAG-06` 的领域版本：Link/Expression 边、下游传播、SCC 循环检测、稳定拓扑计划、generation 和 recompute 状态已进入 Facade 与 SQLite schema v3。还未把每个 DAG 节点接入真实 OCCT/Sketcher 计算 Worker，因此当前是可验证的业务调度层，不是完整几何重算。

TSN 已完成面/边/顶点量化签名、唯一/重复候选判定和匹配 API，并挂接到 Bitbybit `MeshAsset`。重复候选使用唯一候选 ID，一旧多新明确保持 ambiguous；面匹配可跨纯平移迁移。版本化 TopoRef JSON 只保存对象、种类、持久 ID、拓扑版本、generation、状态、签名和候选，显式拒绝 transient `faceIndex/edgeIndex/vertexIndex/subshapeIndex`。它仍没有 OCCT 历史 `Generated/Modified/Deleted` 信息、曲线/曲面参数签名、邻接图和跨特征布尔历史映射；TSN-03、TSN-07 与完整 TSN-08 仍是 FreeCAD 稳定子形状命名的必要任务。

Sketcher 已有 Facade 事务模型和基础求解器适配器：Sketch 几何/约束快照进入 `DocumentObjectSnapshot`，新增几何、约束和求解会更新 `ConstraintStatus`、历史、自动保存与 SQLite schema v4；基础约束现覆盖 Diameter、Symmetric、Tangent。该适配器的职责是验证数据模型和提供可替换协议；它不宣称已经等价于 FreeCAD `planegcs`。SK-03 的 planegcs WASM、SK-07 的完整约束分类、SK-09 的交互回放和 SK-10 的 B-spline 仍是兼容门禁。

Bitbybit 的 OCCT `filletEdges` 与 `chamferEdges` 已进入 Geometry Facade，支持全边或显式索引、参数验证、句柄版本和 Worker 隔离。由于 OCCT 瞬时边索引不是持久命名，当前接口仍不能作为 FreeCAD PartDesign 的长期选边引用；必须等 TSN 的边级 `TopoRef`、历史映射和参数化重算完成后，才能标记为 `compatible`。

Geometry Facade 还接入了 Bitbybit IO 的 STEP 和 ASCII STL 导出，作为 FC-08/FC-09 的第一条交换格式垂直切片。导出数据仍只代表当前 Shape；对象树、Expression、Sketch 约束、TopoRef 和重算历史必须由 FCStd/.webcad 格式任务独立保存，不能因“能导出 STEP”而宣称参数化文件兼容。

本轮又补齐了拓扑和恢复边界：面之外增加了由 BitBybit 网格端点派生的 edge/vertex 签名，并通过 `geometry.topology()` 返回面/边/点引用，签名使用量化坐标、长度/端点而不使用面索引；这仍不是 OCCT `Generated/Modified/Deleted` 历史。FCStd inspection 现在同时生成只读 `proxyDocument`，对象属性带有 `recognized/proxy/blocked` 状态；SQLite/OPFS Project API 增加 `recovery(documentId)`，报告完整性、schema、最后保存版本和降级警告。持久化写入现在在支持的浏览器使用 Web Locks 跨标签页互斥，并通过 BroadcastChannel 广播保存版本；无 Web Locks 环境明确报告 `local-queue`，不能解释为跨标签页安全。代理文档和恢复报告都不能被解释为 FCStd 参数化写回或崩溃恢复已经完成。

## 17. 本轮后续实现记录与下一批任务

本轮继续执行了重算、文件安全和命令能力三个关键边界。实现与验收必须按下面的定义理解，不能把“接口存在”解释成“FreeCAD 业务已完成”：

| 任务 | 实施措施 | 验证结果 | 剩余边界 |
|---|---|---|---|
| P1-03 / DAG-06 重算执行器 | `RecomputeCoordinator` 为每次运行分配 generation；后发运行取消前发；节点完成后校验 AbortSignal、文档 ID/版本和当前 generation；结果状态为 `completed/failed/cancelled/stale`；按 DAG `levels` 使用 `Promise.all` 并行执行同层节点，并按稳定计划顺序合并结果和进度；可选的 `createFacadeGeometryRecomputeExecutor` 在 OCCT Worker ready 时执行真实 Pad/Pocket/Revolution/Fillet/Chamfer | 取消、过期版本、依赖失败传播、独立节点并行、闭合 Sketch 特征链、Revolution 角度/反向和 Facade 提交测试通过 | 默认数据模型仍不持久化 ShapeHandle；Up to face、拓扑历史映射、每节点独立 Worker 和完整 PartDesign 特征仍待实现；失败时缓存保留最近有效 Shape |
| DAG-08 失败/抑制传播 | 上游 `error` 将下游置为 `upstream-failed`；Feature 的可持久化 `Suppressed` 属性将自身置为 `suppressed`、下游置为 `upstream-suppressed`，不误报重算失败；抑制时释放缓存 Shape，解除后只重算依赖闭包；重算错误映射为带版本、generation、根因、依赖路径和修复动作的诊断树 | 上游失败、抑制跳过、Shape 释放、保存恢复、根因树、对象定位和解除错误后的最小闭包修复测试通过 | 多配置抑制、Body Tip 重定向、最近有效 Shape 显式回滚和完整 FreeCAD 状态机仍待实现 |
| P4-06 任务提交与重算闭包 | Task 草稿在 Facade 事务内写入 Boolean Base/Tool 等链接；新对象和依赖闭包进入 `touched/dirty`，React OK 通过 `recomputeAsync()` 提交并反馈结果；Facade `diagnostics` 提供根因树和定位/闭包重算/合法抑制修复，Diagnostics 页面只做事件投影 | Boolean Task 链接/依赖测试、Task dirty 快照、根因路径和修复后诊断清理通过 | Apply 预览仍未持久化临时 Shape；多选选择集、Shape 回滚和完整 FreeCAD Task 校验仍待实现 |
| DAG-07 Body/Tip 与来源链接 | Part Design 特征提交时按来源类型绑定 Profile/Base，更新只读 Body.Tip，并将 Body 与新特征一并纳入 dirty/recompute 闭包；Undo/Redo 恢复 Tip | Pad Task、Body.Tip、Undo/Redo 回归测试通过 | 单实体规则、Tip 抑制/重定向、复杂容器和跨 Body 支持仍待实现 |
| SK-04 求解器边界 | Sketch 节点通过可替换 executor 求解；冲突/无效约束阻止下游，求解结果作为对象更新返回 | 基础 Sketch solve 与异步对象更新测试通过 | 当前是基础 TypeScript solver，不是 `planegcs` WASM；高级约束、拖拽、外部几何和 B-spline 未完成 |
| FC-03 ZIP 安全读取 | 先读中央目录再解压；限制 archive/entry/total 字节、压缩比、条目数；拒绝路径穿越、重复路径、加密项、ZIP64 和 XML entity | 缺 Document.xml、路径穿越、压缩炸弹测试通过 | 尚未恢复 BRep/Shape、视图、表达式和参数化对象 |
| FC-04/FC-07 只读报告 | `project.fcstd.inspect()` 解析 Document.xml 对象声明、Label、属性数量和类型；未知类型为 proxy，Python 类型为 blocked；脚本资源只告警且不执行 | recognized/proxy/blocked 分类和 Facade-only 测试通过 | `metadata-compatible` 仅表示 XML 元数据可读，不表示 FCStd 可编辑或 round-trip |
| P2-04 Project list/load | `project.list()` 暴露 SQLite/内存快照摘要，`app.document.load()` 将选定快照作为活动 Document 事务恢复，清理旧重算/Shape/Task 状态、保留 Undo 边界并按完整对象图异步重算；Projects 页面按 documentId 调用 Facade API | 列表摘要、保存→修改→加载后属性恢复、选择清空、任务清空和加载重算调用通过测试 | FCStd 导入仍是只读 metadata/proxy；跨文档 ShapeHandle 和 Shape 持久化仍待完成 |
| P2-03 Resource/recovery fallback | SQLite Worker 在无 OPFS 的浏览器中使用内存资源表，保留 SHA-256 身份和引用计数；恢复报告区分数据库完整但目标文档缺失的 `unavailable`；销毁 Worker 时清空临时资源 | Worker 类型检查、生产构建通过 | 内存资源会随刷新丢失；配额回收、持久资源校验和大文件压力仍待实现 |
| PART-07 Shape check | `check-shape` 使用 Facade `geometry.topology()` 生成面/边/顶点数量和 `SHAPE_CHECK_PASSED` 信息诊断；空缓存、空拓扑和 Worker 错误分别返回结构化失败诊断 | 无 Shape、错误选择前置和拓扑调用边界通过测试/构建 | 当前是网格派生拓扑检查，不等价于 OCCT `BRepCheck_Analyzer`，完整修复建议和自交诊断仍待实现 |
| P1-02 命令准确性 | manifest 仍可完整展示；Part `primitive/union/cut/intersection` 与 Part Design 核心命令已有 Facade executor；命令状态同时检查工作台和对象类型选择谓词；其余未接入 executor 的命令返回 disabled 与 `COMMAND_UNIMPLEMENTED`，不再静默完成 | Part 基本体/布尔 Shape 缓存、选择不兼容时的禁用原因、`mirrored` 未实现状态与诊断测试通过 | 其余工作台要逐项增加真实 executor、Task 参数和黄金回放后才能启用 |
| P3-05 Pattern 实验切片 | `linear-pattern` 和 `polar-pattern` 通过 Part Design 选择谓词、Task 和类型化属性创建对应对象；Linear 按总 Length 等距平移，Polar 在小于 360° 时覆盖首末角、360° 时不复制重合端点；两者均由 OCCT union 合并并释放临时副本 | 线性间距/方向、圆周完整/部分角度分布、联合输入、句柄释放、非法参数诊断、Base 链接、Body.Tip、属性校验和任务提交回归测试通过 | 当前为 FreeCAD 1.0+ 的 Transform body 近似，只复制整个 Base Shape；未实现 Transform tool shapes、连接单实体过滤、稳定 TopoRef、历史映射、反向轴和引用轴，因此保持 `experimental` |
| P3-05 Hole 基础切片 | `hole` 创建 `PartDesign::Hole`，用 32 边圆形 Profile 调用现有 OCCT Pocket；支持 Diameter、Depth 以及 Dimension/Through all，校验正尺寸并纳入 Base 链接和 Body.Tip | 圆孔 Profile、有限深度调用、非法直径诊断、Task 属性提交和 Tip 更新测试通过 | 仅为基体原点 XY 面、+Z 法向的直孔；草图圆/面定位、沉孔、锪孔、钻尖、螺纹、尺寸标准和稳定支撑面引用仍待实现，保持 `experimental` |
| TSN-02/05/06/08 TopoRef 基础迁移 | `topologyReferences` 提供 schema v1 创建、序列化、安全解析、解析和跨版本迁移；重复几何候选 ID 唯一，一旧多新不会错误继承；匹配按 kind 隔离并用形状尺度归一化几何评分支持纯平移 | round-trip、瞬时索引拒绝、resolved/ambiguous/deleted、重复拆分和纯平移回归测试通过 | 仍是网格签名启发式；没有 OCCT Generated/Modified/Deleted、邻接/曲率签名、布尔历史和黄金模型规模验证，不得提升为 compatible |
| TSN-08/09 LinkSub 文档接线 | `PropertyValue` 支持 schema v1 TopoRef，`App::PropertyLinkSub` 经 Facade 解析/校验和深克隆；依赖图产生带 persistentId 的 `topo-ref` 边；SQLite/内存 Project 以结构化 JSON 保存；Pocket 暴露 `UpToFace` 槽，Property 面板显示状态并可清除 | 非法瞬时索引/缺失对象拒绝、DAG 边、保存加载 round-trip、LinkSub 专项测试、桌面属性面板无横向溢出 | 尚未从 3D 选择创建引用，也未在重算后自动写回迁移结果；Pocket Up to face executor 仍保持结构化 unsupported，等待 OCCT 面历史/解析接线 |
| TSN-03/07 历史适配器回退 | Bitbybit 1.1.1 绑定仅有 `HasGenerated()`，没有逐 Shape 的 Generated/Modified/IsDeleted；新增显式 `signature-fallback` provider，把多输入到输出保守分类为 preserved/modified/generated/deleted/ambiguous，跨对象相同签名不抢占继承 | 平移修改、新增面、删除面和两个输入竞争同一输出的歧义测试通过；全套 50 项测试通过 | 此 provider 不是 OCCT history；只有自构建绑定暴露逐子形状历史并通过布尔黄金模型后，才能将 TSN-03/07 标为完成 |

后续按以下顺序连续开发：

1. `P4-06/DAG-08`：同步/异步重算已共享抑制传播和根因诊断语义，并支持定位、解除错误后的最小闭包重算与合法特征抑制；继续补齐多配置抑制、Body Tip 重定向、最近有效 Shape 显式回滚和性能计数器。Shape 缓存已进入 Facade，但尚未持久化。
2. `P3-04/P3-05`：Pad/Pocket/Revolution/Fillet/Chamfer 已有 OCCT Worker 输入适配和 Shape 缓存回写，Pocket Through all 已接入；Linear/Polar Pattern 与原点法向直孔已完成实验切片；继续补齐 Up to face、局部特征/拓扑历史及 Hole 高级形态，未完成能力保持 disabled 或 experimental。
3. `TSN-03/07/08`：TopoRef schema、面/边/点签名、基础迁移和歧义处理已落地；继续补齐 OCCT Generated/Modified/Deleted、邻接/曲率签名、跨布尔历史和数据库属性接线；任何 transient index 不得写入持久引用。
4. `SK-03/SK-06/SK-07`：编译和验证 planegcs WASM，按基础/高级约束建立 FreeCAD 黄金回放；基础 solver 维持 experimental。
5. `P2-04/P2-05/P2-06`：完成保存点恢复报告、迁移回滚、配额回收和 BroadcastChannel 单写者冲突。
6. `FC-04/05/06/10`：增加 XML/Shape/Expression/Link 映射，未知字段原样保留，完成 WebCAD↔FCStd↔FreeCAD 差异报告。
7. `P6-03/P8-02`：把 disabled 原因、重算进度/取消、FCStd 报告和能力矩阵接入 React，并通过目标浏览器回放和视觉基线。

启用规则：`RecomputeExecutionResult.status=completed` 只表示已注册节点成功；FCStd `metadata-compatible` 只表示安全元数据可读；只有 FreeCAD 对照黄金测试、取消/失败/只读、保存/加载和跨浏览器门禁都通过，才能把对象或命令从 `experimental` 提升到 `compatible`，`exact` 还要求锁定版本后的逐项差异为零。