feat: establish reproducible FreeCAD web compatibility baseline
This commit is contained in:
122
docs/freecad-exact-promotion-runbook.zh-CN.md
Normal file
122
docs/freecad-exact-promotion-runbook.zh-CN.md
Normal file
@@ -0,0 +1,122 @@
|
||||
# FreeCAD Web Exact Promotion Runbook
|
||||
|
||||
本手册描述如何从当前兼容子集推进到系统级 FreeCAD exact。基线固定为 FreeCAD 1.1.1，提交 `0108fd4b4850cc46e625b60e53cea7a7bbe69f8d`，浏览器基准为 Chrome 150。手册不允许通过改写能力矩阵、截图或最终几何猜测来缩短证据链。
|
||||
|
||||
## 当前状态
|
||||
|
||||
- exact claim：`false`
|
||||
- exact 任务：`1/52 completed`、`37 in_progress`、`14 pending`、`0 blocked`
|
||||
- exact 模块：`0/34`
|
||||
- promotion task：`EX-REL-01=pending`
|
||||
- 三项硬边界：无原生 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 个模块和 1113 个 GUI 命令是否与真实桌面报告逐项一致；该 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](../config/freecad-web-exact-promotion-report.schema.json)。
|
||||
5. 运行 `npm run check:freecad-web-exact-promotion`；通过后才可同步 claim、模块等级和签名发布物。
|
||||
|
||||
## Promotion 报告最低结构
|
||||
|
||||
```json
|
||||
{
|
||||
"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
Block a user