feat: advance FreeCAD parity and native OCCT history

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

@@ -1,6 +1,8 @@
 # 完整 FreeCAD 对标实施方案
 
 > 本文是“功能完全对标 FreeCAD”的工程基线和任务分解，不把当前已有的页面、MockFacade 或少量 OCCT 特征误报为完成。所有“支持”都必须经过锁定版本 FreeCAD 的行为黄金测试和文件互操作测试。
+>
+> 全模块、逐领域任务 ID、执行波次和统一退出条件以 [FreeCAD 1.1.1 全功能对标主任务账本](freecad-complete-parity-backlog.zh-CN.md) 为准；本文保留架构决策、专项设计和阶段门。两者不一致时，能力状态以 `config/compatibility-matrix.json` 为机器可读真值，范围和待办以主任务账本为准。
 
 ## 1. 目标与边界
 
@@ -12,6 +14,8 @@
 
 对 React 和页面公开的唯一业务入口是 `BitBybitWebCadFacade`。页面不得直接导入 Three.js、OCCT、OCCT Worker、SQLite 或 OPFS；这些实现只能由 Facade 适配器和 Worker 使用。新增工作台、命令、属性、文件格式和诊断，必须先扩展版本化 Facade 合同，再接入页面。
 
+Bitbybit 必须被充分用作几何、Worker、IO、三角化和缓存的首选实现层。对 Bitbybit 1.1.1 npm 包未暴露但 FreeCAD 对标必需的能力，允许锁定 Bitbybit 与 OCCT 源码提交后扩展绑定并用 Emscripten 自构建 WASM；不得以现成包 API 不足作为降低功能范围的理由。自构建 provider 与现有 provider 必须共享 Facade/Worker 合同、能力探测、句柄生命周期、取消/诊断和黄金测试。
+
 ### 1.3 “完整对标”的可验收定义
 
 | 等级 | 含义 | 允许的产品表述 |
@@ -24,6 +28,16 @@
 
 没有黄金测试、差异报告和迁移策略的功能，不得标记为 `exact` 或 `compatible`。浏览器限制必须体现为能力矩阵和用户可见诊断，不能静默删除 FreeCAD 行为。
 
+### 1.4 全量范围和清册门禁
+
+锁定源码 `src/Mod` 的 34 个目录全部纳入范围：`AddonManager`、`Assembly`、`BIM`、`CAM`、`Cloud`、`Draft`、`Fem`、`Help`、`Idf`、`Import`、`Inspection`、`JtReader`、`Material`、`Measure`、`Mesh`、`MeshPart`、`OpenSCAD`、`Part`、`PartDesign`、`Plot`、`Points`、`ReverseEngineering`、`Robot`、`Sandbox`、`Show`、`Sketcher`、`Spreadsheet`、`Start`、`Surface`、`TechDraw`、`TemplatePyMod`、`Test`、`Tux`、`Web`。同时覆盖 `App`、`Base`、`Gui`、`Main` 暴露的文档、Property、事务、选择、视图、参数、命令、Python 控制台、宏、偏好、快捷键、多文档、剪贴板和打印行为。
+
+`P0-02/INV-01..06` 未完成以前，“全部功能”范围仍视为未冻结。源码模块中的测试、模板或开发设施可以被分为开发等价能力或明确 `unsupported`，但不得遗漏；Python、宏、插件、外部求解器和后处理器必须有沙箱与权限决策。
+
+项目 Node/npm 命令统一经 `./npmw` 执行；系统 `npm` 的结果不得用作阶段门证据。
+
+本机 `FreeCADCmd` 可作为第一层行为 oracle：`./npmw run probe:freecad-reference` 采集版本、提交、已加载模块和核心 Property 元数据；当前构建是无界面 `Part/Material/Measure` 子集。完整桌面/工作台回放必须另行启用 FreeCAD 原生模块，不能将 headless probe 的可用性扩展到未构建的工作台。
+
 ## 2. 当前差距与解决策略
 
 | 领域 | 当前切片 | 达到对标还缺少的核心能力 | 主任务包 |
@@ -56,6 +70,7 @@
 - 依赖循环、求解冲突、拓扑歧义和未知文件对象必须显式失败并保留诊断。
 - Undo/Redo、自动保存和资源引用计数必须以同一事务边界提交。
 - Worker 结果不可直接改变 React 状态，必须经 Facade 校验和事件投影。
+- 几何能力按 `reuse-bitbybit`、`extend-bitbybit-binding`、`custom-occt-binding` 三档登记；后两档必须锁定源码、补丁、ABI、Emscripten 工具链、许可证和 WASM hash，并完成 Bitbybit/FreeCAD 三方差分。
 
 ## 4. 专项一：稳定子形状命名（TSN）
 
@@ -196,11 +211,15 @@
 | 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 |
+| 数据/交换模块 | Import、Points、ReverseEngineering、OpenSCAD、IDF、JT、Material、MeshPart | IMP/PTS/RE/OSC/IDF/JT/MAT：格式、单位、颜色、代理、几何转换和往返 | FC、QA |
+| 应用/扩展模块 | Start、Help、AddonManager、Cloud、Show、Web | APPMOD/ADDON：最近项目、离线帮助、扩展治理、分享/云和安全边界 | P0 manifest、安全门 |
+| Robot/Plot | 机器人、轨迹、运动学、数据绘图和结果输出 | ROBOT-01..12、PLOT-01..06 | DAG、EXU、QA |
+| 脚本/宏/桌面通用 | Python 控制台、宏、插件、偏好、自定义、剪贴板、打印、多文档 | SCRIPT/GUI-REST：沙箱、权限、等价 Web 工作流或逐项不支持诊断 | P0 manifest、安全门 |
+| 开发/测试模块 | Sandbox、TemplatePyMod、Test、Tux | DEV-01..06：保留开发/自动化等价入口或明确非产品能力 | P0 manifest |
 
 ### 8.3 工作台交付顺序
 
-先完成 `PartDesign + Part + Sketcher + TechDraw + Spreadsheet` 的参数化闭环，再做 Draft/Assembly/BIM/Mesh/Surface，最后处理 FEM/CAM/Raytracing 等需要额外数值库或后处理器的模块。每个工作台在进入下一层前必须通过对象创建、编辑、重算、撤销、保存、加载和导出七项门禁。
+先完成 `PartDesign + Part + Sketcher` 的参数化闭环与 FCStd 双向往返，再做 TechDraw/Spreadsheet/Draft/Plot，随后做 Assembly/BIM/Mesh/Surface，最后处理 FEM/CAM/Robot/Inspection、数据交换模块、应用/扩展模块和脚本/桌面通用能力。每个工作台在进入下一层前必须通过对象创建、编辑、重算、撤销、保存、加载和导出七项门禁。
 
 ## 9. 专项六：文件兼容与迁移（FC）
 
@@ -297,13 +316,17 @@
 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`，不提前宣称完整。
+6. 以 PartDesign 核心闭环为第一条完整垂直链，随后完成 FCStd 对象/属性/Shape/视图双向读写和 round-trip。
+7. 按 `TD→SS→DRAFT/PLOT→ASM/BIM/MESH/SURF→FEM/CAM/ROBOT/INSP` 顺序完成工作台七项门禁。
+8. 完成 Import/Points/ReverseEngineering/OpenSCAD/IDF/JT/Material、Start/Help/AddonManager/Cloud/Show/Web、Python/宏/插件和桌面通用能力的逐项兼容决策与实现。
+9. 完成跨浏览器、OPFS 故障、性能/内存、安全 fuzzing、a11y/i18n、PWA、升级回滚、SBOM 和发布差异报告。
 
 ## 15. 完成定义
 
 “完整 FreeCAD 对标”只有在 F0-F9 全部阶段门通过、核心与扩展工作台均有兼容等级、稳定子形状命名/Sketcher/Expression/单位/DAG/重算/FCStd 均有黄金报告、跨浏览器和安全门禁通过，并且发布文档列出所有差异后才能使用。当前仓库仍处于核心 Facade、OCCT 几何和属性编辑的进行中阶段，下一工作目标按第 14 节执行。
 
+完整对标还要求 34 个源码模块和 App/Base/Gui 通用能力全部进入机器可读清册；任何尚未登记的命令、对象、属性、格式、Python/宏/插件入口都会阻断 G9。详细关闭条件见主任务账本第 3、11、13 节。
+
 ## 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，因此当前是可验证的业务调度层，不是完整几何重算。
@@ -348,6 +371,8 @@ PartDesign Mirrored 已形成 experimental whole-shape 垂直切片：Facade 验
 | TSN-08/09 LinkSub 文档接线 | `PropertyValue` 支持 schema v1 TopoRef；重算 generation 自动迁移 LinkSub/草图外部几何，歧义/删除不强绑；schema v6 保存对象拓扑快照；Facade 候选替换事务验证当前同 kind persistentId，重建 DAG 并支持 Undo/Redo；属性/诊断 UI 可替换；Pocket 暴露 `UpToFace` 槽 | 非法瞬时索引/候选拒绝、DAG 边、稳定/歧义/删除迁移、跨 generation 回退解析、候选替换、Undo/Redo、保存加载和 67 项全套测试通过 | 尚未从 3D 拾取、预选或高亮候选；Pocket Up to face executor 仍保持结构化 unsupported，等待原生面历史/解析接线 |
 | TSN-03/07 历史适配器回退 | Bitbybit 1.1.1 绑定仅有 `HasGenerated()`，没有逐 Shape 的 Generated/Modified/IsDeleted；`signature-fallback` 已进入真实重算 generation，对每个成功 Shape 保存快照/matches/history，采集失败释放临时 Shape并保留最近有效缓存 | 平移修改、新增/删除/重复面、跨对象竞争、generation 写回、采集失败隔离和持久化测试通过；全套 63 项测试通过 | 此 provider 不是 OCCT history；多输入 Boolean 当前仍缺逐输入原生映射，只有自构建绑定暴露逐子形状历史并通过黄金模型后，才能将 TSN-03/07 标为完成 |
 
+原生历史 provider 适配器现已进入重算执行器：当 Geometry Worker 暴露 `topologyHistory()` 且 Base/Tool/Profile 有拓扑快照时，Facade 将真实输入/输出 Shape 和记录交给 `captureNativeTopologyHistory()`；否则保守回退。该适配层有独立单测，但当前 Bitbybit 1.1.1 provider 仍未提供真实记录，因此 TSN-03/07 仍不能标记完成。
+
 后续按以下顺序连续开发：
 
 1. `P4-06/DAG-08`：同步/异步重算已共享抑制传播和根因诊断语义，并支持定位、解除错误后的最小闭包重算与合法特征抑制；继续补齐多配置抑制、Body Tip 重定向、最近有效 Shape 显式回滚和性能计数器。Shape 缓存已进入 Facade，但尚未持久化。