wangdequan/Web_FreeCAD_Bitbybit
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
378a6e7c0ab90901b17a56bb6afd24e7724b4c0d
Web_FreeCAD_Bitbybit/docs/freecad-exact-promotion-runbook.zh-CN.md
wangdequan 5bbd7b9d4f
Some checks failed
real-verification / chrome (push) Has been cancelled
Details
real-verification / freecad-oracle (push) Has been cancelled
Details
real-verification / wasm (push) Has been cancelled
Details
feat: advance FreeCAD exact parity evidence
2026-08-14 22:39:16 -04:00

7.9 KiB
Raw Blame History

FreeCAD Web Exact Promotion Runbook

本手册描述如何从当前兼容子集推进到系统级 FreeCAD exact。基线固定为 FreeCAD 1.1.1，提交 0108fd4b4850cc46e625b60e53cea7a7bbe69f8d，浏览器基准为 Chrome 150。手册不允许通过改写能力矩阵、截图或最终几何猜测来缩短证据链。

当前状态

  • exact claim：false
  • exact 任务：5/52 completed、36 in_progress、11 pending、0 blocked
  • exact 模块：0/34
  • promotion task：EX-REL-01=pending
  • 三项硬边界：私有 token 只来自原生 MappedNameRef/StringHasher、逐阶段 builder 关系必须有原生证据、无唯一同构来源时 fail-closed

实施顺序

1. 冻结基线与证据环境

任务：EX-ORA-01/02/03

  1. 锁定 FreeCAD 源码、FreeCADCmd、GUI 构建、OCCT/Bitbybit/WASM、浏览器版本和许可证清单。
  2. 生成 TypeId、Property、GUI command、format、entrypoint inventory；每个候选必须有源码位置和 runtime 状态。
  3. 建立成功、失败、禁用、取消、重算、保存重开六类 oracle fixture。
  4. 运行 npm run check:freecad-inventory、check:freecad-type-properties、check:freecad-gui-commands、check:freecad-entrypoints。
  5. 运行 npm run check:freecad-oracle-coverage，核对 34 个模块、1111 个工作台启动 GUI 命令、19 个 source-only 命令和 2 个 context-only 命令是否与隔离的真实桌面报告逐项一致；该 gate 同时报告未构建模块和仍待逐对象 probe 的静态候选。
  6. 运行 npm run check:freecad-golden-coverage，按 feature family 核对成功、失败、history、复合阶段、ElementMap2、FCStd 往返和浏览器回放七个维度；用 -- --details 输出逐 family 缺口。新增原生 feature-family fixture 时必须同时通过 test:golden:freecad:families 和 test:golden:freecad:family-failures，任何 missing 项继续保留为 EX-ORA-02 blocker。
  7. 运行 npm run check:freecad-partdesign-failures、npm run check:freecad-partdesign-revolution-groove、npm run check:freecad-partdesign-transform 和 npm run check:freecad-part-builders。原生缺输入后仍为 Up-to-date + Valid + null Shape 的 feature 必须分类为 accepted-empty，不能计入失败覆盖；只有真实 rejected 诊断才能关闭 failure-fixture 维度。局部重算失败保留旧 Shape 时，必须同时保存 Invalid 状态、原生诊断和 stale Shape，不得把旧 Shape 当作成功结果。

退出条件：没有未分类模块、命令、属性、格式或入口；所有后续任务均可引用固定 oracle。

2. 闭合内核、逐阶段历史与命名

任务：EX-KER-01、EX-TSN-01/02/03/04

  1. 为每个 Part/PartDesign/Boolean/Pattern/Dress-up builder 采集输入、每个中间 Shape、结果 Shape 和原生 history。
  2. 将 Generated/Modified/Deleted 按生产 stage 和 result index 写入 Facade；禁止把最终 Shape 的索引套到中间阶段。
  3. 让 native provider 输出 MappedNameRef、StringHasher、ElementMap2 token 的实际证据；没有证据时写 final-shape-only。
  4. 以对称 Boolean、拆分/合并、重复面/边/点和跨对象竞争模型验证唯一来源与 ambiguous 候选持久化。
  5. 运行 30-case ElementMap2/StringHasher gate、native history Chrome gate 和 topology replay。

退出条件：错误绑定、未解释关系、名称漂移、命名证据缺失及边界违规均为零；否则保持 compatible/fallback。

3. 完成 App 文档和特征内核

任务：EX-DOC-01..05、EX-SK-01/02、EX-PART-01、EX-PD-01/02

  1. 按 Property 类型、状态标志、表达式、LinkSub、Extension、Group、Body/Tip、Attachment、Datum、Binder 建立逐字段 oracle。
  2. 完成事务、observer 顺序、DAG 重算、局部失败、抑制、Undo/Redo、多文档和恢复语义。
  3. 按 Sketcher、Part、PartDesign 的特征族逐项推进；每个特征必须同时有成功、非法输入、取消、编辑、保存重开和 native history 证据。
  4. 每提升一个 feature level，更新 compatibility-matrix.json，不得批量提升整个 workbench。

退出条件：对象图、参数、Shape、history、拓扑引用和诊断在 FreeCAD↔Web↔FreeCAD 中稳定。

4. 完成 FCStd 与格式入口

任务：EX-FC-01、EX-FMT-01..04

  1. FCStd 按 Document.xml、GuiDocument、BRep、ElementMap2、StringHasher、脚本、未知资源逐项闭合。
  2. BREP/STEP/IGES 完成单位、颜色、名称、装配层级、容差和失败诊断。
  3. STL/OBJ/PLY/DXF/SVG/PDF/IFC/CSV/GCODE 按对象和元数据建立双向或显式只读契约。
  4. JT/IDF/OpenSCAD/Cloud/Help 逐项决定浏览器实现、受控 sidecar 或正式排除；不得保留 scope-only。

退出条件：支持格式无未知差异；不能实现的格式有明确排除报告，不计入 exact claim。

5. 完成 GUI 和工作台流程

任务：EX-UI-01..05、EX-DRAFT-01、EX-TD-01、EX-SS-01、EX-PLOT-01、EX-DOCWB-01、EX-ASM-01、EX-BIM-01、EX-SURF-01、EX-MESH-01、EX-MAT-01

  1. 建立 FreeCAD GUI oracle：菜单、工具栏、工作台、Combo/Task、属性、对话框、快捷键、上下文、焦点和状态栏。
  2. 每个工作台回放新建、选择、Task、属性修改、错误、取消、Undo/Redo、保存重开和导出。
  3. 对桌面、390px、键盘、读屏树、locale、长文本和 GPU fallback 做同一流程对照。
  4. 只有动态 enable/visible/focus/validation 与原生 oracle 对齐后，UI 任务才能完成。

退出条件：零未登记 UI 差异、零遮挡、零无名控件、零核心流程阻断。

6. 完成 FEM/CAM/Robot/数据/脚本/插件

任务：EX-FEM-01、EX-CAM-01、EX-ROBOT-01、EX-DATA-01、EX-INSPECT-01、EX-SCRIPT-01、EX-ADDON-01、EX-PROXY-01、EX-PLATFORM-01

  1. FEM：对象、网格、材料、求解器、结果场和后处理与原生 benchmark 对照。
  2. CAM：全部 Path operation/dress-up、原生 operation-object、Task、后处理、仿真、刀具/夹具和机床配置对照；生产授权继续 fail-closed。
  3. Robot、Points、ReverseEngineering、Inspection 完成算法、数据和报告闭环。
  4. Python/macro 只允许 capability-secure、可审计、可复现的受限 API；Addon 必须签名、隔离、可回滚。
  5. 五个 proxy 模块要么获得原生差分证据，要么出具正式排除边界。

退出条件：所有模块达到 exact，或被明确记录为不属于最终 exact scope；不能留 unexplained。

7. QA、报告和 promotion

任务：EX-QA-01/02/03、EX-REL-01

  1. 运行 Chrome/Firefox/Safari、GPU fallback、桌面/平板/移动矩阵。
  2. 完成无障碍、locale、性能、安全、fuzz、压力、迁移、崩溃恢复和资源释放。
  3. 汇总八项指标：wrongBindings、unexplainedRelations、roundtripNameDrift、unknownSemanticDifferences、namingEvidenceMissing、namingEvidenceBoundaryViolations、unexplainedModules、releaseBlockers。
  4. 仅由 EX-REL-01 生成 config/freecad-web-exact-promotion-report.json，其结构必须符合 report schema。
  5. 运行 npm run check:freecad-web-exact-promotion；通过后才可同步 claim、模块等级和签名发布物。

Promotion 报告最低结构

{
  "schemaVersion": 1,
  "taskId": "EX-REL-01",
  "completedTasks": 52,
  "exactModules": 34,
  "metrics": {
    "wrongBindings": 0,
    "unexplainedRelations": 0,
    "roundtripNameDrift": 0,
    "unknownSemanticDifferences": 0,
    "namingEvidenceMissing": 0,
    "namingEvidenceBoundaryViolations": 0,
    "unexplainedModules": 0,
    "releaseBlockers": 0
  },
  "evidenceClasses": [
    "native-oracle", "browser-runtime", "save-reopen-roundtrip",
    "failure-cancel-recovery", "resource-release", "security",
    "accessibility", "signed-release"
  ]
}

当前不应创建该报告；在 EX-REL-01 完成前，缺少报告是预期状态，promotion gate 必须保持 freecad-web-exact-promotion-fail-closed。

Reference in New Issue View Git Blame Copy Permalink