Files
Web_FreeCAD_Bitbybit/docs/continuation-status.zh-CN.md

206 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Web FreeCAD 接续执行状态
更新时间2026-08-03FreeCAD 1.1.1 原生黄金 oracle 里程碑)
## 1. 当前目标
按 FreeCAD `1.1.1` 全功能对标方案持续推进 F0-F9 阶段门,完成实现、测试、兼容矩阵、发布门禁并同步云仓库。当前仍是 experimental 核心 Facade/OCCT 阶段,不能宣称已达到 FreeCAD 全功能兼容。
## 2. 仓库状态
- 分支:`main`
- 云仓库:`http://154.8.160.151:3000/wangdequan/Web_FreeCAD_Bitbybit.git`
- 最近已推送里程碑:`81fcc69 docs: record multi-transform milestone`
- 最近已推送里程碑的完整门禁:`./npmw run verify` 通过
- 当前原生 oracle 里程碑验证FreeCAD 1.1.1 源码构建成功5/5 Part 黄金回放、`./npmw run verify`、diff/JSON 校验全部通过
- 生产构建:通过
- 本地开发地址:`http://127.0.0.1:5173/`
- 兼容真值表:`config/compatibility-matrix.json`
- 总体方案:`docs/freecad-full-parity-plan.zh-CN.md`
## 3. 本轮已完成并推送
1. 重计算根因诊断、修复分支重算与诊断树。
2. Linear Pattern、Polar Pattern 和基础 Hole 的 experimental OCCT 执行链路。
3. 稳定拓扑签名、版本化 TopoRef、迁移、PropertyLinkSub 与保守拓扑历史回退。
4. Sketcher 版本化 solver provider 协议、能力探测、取消/过期 generation 隔离和回放合同。
5. 椭圆/B-spline 领域模型;基础 TypeScript solver 对未支持曲线返回明确诊断。
6. 外部草图几何、稳定 TopoRef、持久化与 `topo-ref` DAG 依赖边。
7. Vector、Placement、LinkList/StringList 结构化属性合同Placement 深拷贝、校验、撤销、持久化和 UI 编辑器。
8. 对象级 Placement 重算:基本体/特征 Shape 生成后执行平移与轴角旋转;恒等变换跳过额外 Shape变换失败释放临时 Shape 并保留上一次有效缓存;保存后恢复的 Placement 可再次驱动重算。
9. TSN generation 写回:重算成功后采集面/边/点签名快照与保守历史;迁移 LinkSub/草图外部几何歧义或删除引用标脏所有者并生成可定位诊断schema v6 保存对象拓扑快照。
10. TopoRef 候选替换事务:属性面板/诊断页从源对象当前同 kind 拓扑候选中原子替换 LinkSub 或外部几何引用,重建 DAG、标脏重算并支持 Undo/Redo。
11. Mirrored whole-shapeFacade 暴露 OCCT 平面法向镜像PartDesign Task 支持 XY/XZ/YZ 原点平面与可选 Fuse重算释放 union 临时副本并写回 Shape/拓扑 generation。
12. MultiTransform whole-shape新增结构化有序 Linear/Polar/Mirrored 步骤属性、Task/属性编辑器、最多 6 步和 100 实例校验;重算按顺序组合全部实例,失败与成功均释放中间 Shape并保留最近有效缓存。
相关提交按新到旧:
- `293cff6` structured placement properties
- `a8f902c` stable sketch external geometry
- `6786261` advanced sketch curves
- `e0b4817` versioned sketch solver protocol
- `4d94109` conservative topology history fallback
- `d3d88b2` LinkSub topology references
- `9def470` topology reference migration
- `1ed3527` basic hole
- `ce3b81c` polar pattern
- `8995b90` linear pattern
- `aeafc6c` recompute diagnostic repair tree
## 4. 已确认限制
- 锁定的 FreeCAD 1.1.1 C++ 源码可由脚本获取到忽略目录并完成无界面 Part 原生构建;尚无 FreeCAD/planegcs Emscripten 工程或 planegcs WASM 产物,`SK-03` 不能标记完成。现有 `typescript-basic` solver 仅用于协议与基础模型验证。
- Pattern 与 MultiTransform 当前复制整个 Shape不是 FreeCAD 局部特征历史。
- Hole 固定原点/法向,尚无面定位、沉孔、锪孔、螺纹和完整孔标准。
- 拓扑历史来自签名保守回退,不是 OCCT/FreeCAD 原生 Generated/Modified/Deleted 历史。
- Placement 已进入文档属性,并接入 Facade 的对象级 Shape 重算;尚未完整映射到 Body/Tip、Support、AttachmentOffset 或所有特征执行器的 FreeCAD 局部坐标链语义。
- FCStd 仍以安全预检、metadata/proxy 和只读报告为主本轮新增对象属性名、FreeCAD 类型、XML 元素和值的字段级 `Document.xml` 投影,但尚未双向原生往返。
## 5. 下一步执行顺序
1. 补齐 P2 浏览器实证门禁:真实 SQLite v4→v5 升级、OPFS 孤儿清扫、QuotaExceeded、大文件和崩溃注入合同层与 fallback 测试已由 `6bfbdf5` 完成。
2. 补齐 P3-03 浏览器 OCCT 包围盒/体积黄金测试,并验证 Placement 撤销、保存和恢复的真实 Worker 路径Node/fallback 合同已通过。
3. 为 ambiguous/deleted TopoRef 补 3D 候选高亮,并增加真实 OCCT/SQLite 浏览器回放;候选替换 Facade 事务和属性/诊断 UI 已进入当前里程碑。
4. 基于已锁定的 FreeCAD `1.1.1` 源码提取 planegcs 最小依赖图,完成 `SK-03` Emscripten/WASM POC同时扩充回放夹具、约束分类和 Sketch 编辑事务。
5. 扩展 PartDesign推进 Loft/Pipe/Groove、Thickness/Draft以及 Mirrored/MultiTransform/Pattern/Hole 的局部特征历史与完整语义。
6. 完成 FCStd 原生对象/属性/Shape 双向映射和 STEP/IGES/STL/Web CAD 包导入导出。
7. 按核心优先级完成 TechDraw、Spreadsheet、Draft、Assembly、BIM、Mesh、Surface、FEM、CAM 等工作台。
8. 最后通过跨浏览器、性能、内存、安全、可访问性、离线/PWA、升级回滚和发布差异报告门禁。
## 6. 接续操作
```bash
cd /home/mes123456/working_Web_FreeCAD_Bitbybit
git status --short
git log -5 --oneline
./npmw run verify
```
每个独立里程碑必须:
1. 更新实现与聚焦测试。
2. 更新 `config/compatibility-matrix.json` 和两份实施方案中的真实状态。
3. 运行 `./npmw run verify``git diff --check` 和 JSON 校验。
4. 单独提交并推送 `main`,不得把凭据写入仓库。
## 7. 2026-08-03 P2 接续进展
本轮已完成 schema v5 迁移运行器、最近 5 版文档检查点、`loadCheckpoint()`、配额预检、资源清扫计划/API 和 1000 次写队列压力实现。完整门禁已通过,并由提交 `6bfbdf5` 推送到云仓库。后续 TSN 里程碑把 schema 提升到 v6`objects.topology_json` 保存 generation 拓扑快照;真实浏览器 v5→v6 升级仍需补证。
证据边界Node/fallback 证明迁移合同、队列、检查点与纯资源策略;真实浏览器 SQLite v4→v5 升级、OPFS 孤儿清扫、QuotaExceeded、大文件与崩溃注入仍是 P2/P8 后续任务,不能因本轮测试而标记完整 G4/G5。
## 8. 2026-08-03 Placement 里程碑快照
Placement 里程碑涉及实现、测试、兼容矩阵和三份状态/方案文档:
- `src/facade/recomputeEngine.ts`Shape 生成成功后读取对象 `Placement`,通过 `geometry.applyPlacement()` 执行平移/轴角旋转;恒等 Placement 不创建额外 Shape成功后释放局部 Shape缓存只提交变换后的句柄。
- `tests/facade.test.ts`:新增非恒等 Placement 与恒等 Placement 的执行器测试。
- `docs/continuation-status.zh-CN.md``config/compatibility-matrix.json` 及两份实施方案:记录本里程碑的能力边界和验证证据。
已完成的当前工作区验证:
```text
./npmw run test:facade -> 61/61 通过
./npmw run build -> 通过
```
完整 `./npmw run verify``git diff --check``jq empty config/compatibility-matrix.json` 均已通过Placement 已作为独立里程碑提交并推送到远端 `main`
1. 浏览器 OCCT 包围盒黄金证据若无法自动化,保持 P3-03 为 `IN PROGRESS`
2. TSN generation 历史写回已进入当前工作区;提交后推进候选替换事务与下一批 PartDesign 特征,不把签名回退误标为 OCCT 原生历史。
## 9. 2026-08-03 TSN generation 写回快照
- `geometry.topology()` 同时返回可序列化的面/边/点签名条目;几何执行器只在 generation 被接受且拓扑采集成功后提交 Shape 和 `ObjectTopologySnapshot`
- 每个对象快照记录 generation、文档版本、迁移 matches 和 `signature-fallback` 历史;拓扑采集失败释放本轮 Shape最近有效缓存不被覆盖。
- 重算提交遍历 `App::PropertyLinkSub` 与 Sketch 外部几何:稳定引用写回新 generation歧义/删除引用不强绑,所有者保持 dirty/warning 并产生 `TOPOLOGY_REFERENCE_AMBIGUOUS/DELETED` 诊断。
- schema v6 新增 `objects.topology_json`fallback 保存/加载已验证快照深克隆;真实 SQLite/OPFS v5→v6 升级尚未进行浏览器实证。
- 完整 `./npmw run verify`、diff/JSON 校验均通过;里程碑已由 `ffbe2c6` 推送。
这仍不是 OCCT/FreeCAD 原生历史:签名来自三角网格,缺少曲面/曲线参数、邻接图和 Boolean 的逐输入原生历史。候选替换事务/UI 已在下一里程碑补齐,但 3D 候选预选与高亮尚未实现,因此 F3/TSN-03/07/09 不能标记完成。
## 10. 2026-08-03 TopoRef 候选替换快照
- 新增 Facade `resolveTopologyReference()` 事务按所有者、PropertyLinkSub/ExternalGeometry 名称和候选 persistentId 定位引用;候选必须存在于源对象最新拓扑快照且 kind 一致。
- 用户明确选择后写入 stable TopoRef 和最新 generation重建 `topo-ref` DAG 边,标脏依赖闭包,更新文档版本并进入 Undo/Redo 与自动保存。
- 属性面板对 ambiguous/deleted LinkSub 显示候选菜单;诊断页对 LinkSub 和草图外部几何显示候选替换控件。非法候选拒绝,不修改文档。
- 完整 `./npmw run verify`、diff/JSON 校验通过Chrome 桌面/移动布局无重叠SwiftShader 延时截图确认 OCCT canvas 非空;提交和推送仍待执行。
尚未完成 3D 面/边/点候选预选与高亮,也没有真实 OCCT 浏览器黄金回放,因此 TSN-09/F3 仍保持进行中。候选替换里程碑已由 `56903db` 推送。
## 11. 2026-08-03 Mirrored whole-shape 快照
- `geometry.mirror()` 对文档/Shape 句柄、原点和非零法向做 Facade 校验,再调用 Bitbybit `mirrorAlongNormal()`
- `PartDesign::Mirrored` 文档对象保存 Base、Plane 与 FuseTask 更新 Body.Tip 和 DAG。重算按 XY/XZ/YZ 映射法向Fuse 时 union Base 与镜像副本,并始终释放临时副本。
- 当前是整 Shape 镜像,不是 FreeCAD 对选中特征历史的镜像;平面固定经过文档原点,未接 DatumPlane/Sketch axis/TopoRef 支持,也未证明单实体规则。
- 完整 `./npmw run verify`、diff/JSON 校验通过;里程碑已由 `4aa6ca4` 推送。
## 12. 2026-08-03 MultiTransform whole-shape 快照
- `App::PropertyMultiTransform` 保存最多 6 个有序步骤;每个步骤使用稳定 ID 和 Linear/Polar/Mirrored 判别联合不解析自由字符串。Facade 写入边界校验枚举、数值、唯一 ID 和笛卡尔组合后的 100 实例上限。
- Task 面板与 Data 属性面板共用步骤编辑器,可添加、删除、切换类型并编辑 Count/Length/Direction、Count/Angle/Axis 或 Plane提交绑定 Base、更新 Body.Tip并进入 Undo/Redo、自动保存和深拷贝持久化。
- 重算从 Base whole Shape 开始,每一步作用于前一步的全部实例,最终 union成功或中途失败都释放镜像/平移/旋转副本,失败不覆盖上一次成功缓存。接受的 generation 继续走统一拓扑采集和写回。
- 合同测试覆盖 Mirrored→Linear 的 6 实例组合、参数映射、完整临时句柄回收、故障注入、最近有效缓存保留、100 实例拒绝、任务提交、深拷贝、Undo/Redo 和 fallback 持久化。
当前实现不是 FreeCAD Transform feature history 的完全等价实现:它组合并融合整个 Base Shape未实现局部特征列表、Datum/TopoRef 轴面、单实体过滤或 OCCT 原生历史。下一执行点是 Additive/Subtractive Loft 的结构化截面合同与 whole-shape experimental 执行边界。
本里程碑不得声称 P3-03、F3 或完整 FreeCAD 兼容已经通过。当前对象 Placement 是 Shape 生成后的对象级变换,尚未证明 FreeCAD 对 Body/Tip、Support、AttachmentOffset 和局部坐标链的完整等价语义。
## 13. 2026-08-03 FreeCAD 原生黄金 oracle 快照
- 官方 `1.1.1` 标签已在线核验到提交 `0108fd4b4850cc46e625b60e53cea7a7bbe69f8d``fetch:freecad-source` 只接受该提交并使用 detached checkout。
- `configure:freecad-native``build:freecad-native` 已在 Debian trixie 上完成 Release、无 GUI、Part/Material/Measure 最小构建;产物报告 `FreeCAD 1.1.1 Revision: 14556 (Git)`,哈希和工具版本记录在 `config/freecad-native-build.json`
- 新增声明式黄金契约、FreeCAD Python driver、CLI 回放器和比较器。Box、Cylinder、Sphere、Cone、穿孔 Cut 共 5/5 场景通过有效性、拓扑、体积/面积和包围盒对比。
- 全部 Node/npm 操作均使用 `./npmw`;依赖、构建、回放和 CI 边界已写入 `docs/freecad-baseline-and-golden.zh-CN.md`
本轮只完成 P0-01/P0-03 的首批可复现基线。依赖容器 digest、完整 FreeCAD 工作台构建、100 个黄金文件、50 个错误文件、GUI 行为和 Web OCCT 双端差分尚未完成F0/G0 保持进行中。下一执行点是读取 FreeCAD/OCCT 原生 Generated/Modified/Deleted 历史接口并形成可供 Web `TopoRef` 消费的类型化历史合同。
## 14. 2026-08-03 全功能范围账本与 Bitbybit 构建轨道
新增 [FreeCAD 1.1.1 全功能对标主任务账本](freecad-complete-parity-backlog.zh-CN.md),以锁定源码 `src/Mod` 的 34 个模块和 `App/Base/Gui/Main` 通用能力为完整范围。账本把任务拆成 `INV``BASE``BYB``CORE``TSN``SK``PART``PD``FC`、各工作台任务和 `QA/REL` 门禁;源码中的 Sandbox/模板/测试设施以及 Python、宏、插件、偏好、打印和剪贴板均必须有明确能力等级不得隐藏在“其他”中。
几何实现改为 Bitbybit 优先:先复用 Bitbybit 的 OCCT Worker、建模、IO、三角化、缓存和资源生命周期公开 API 不足时,从锁定的 Bitbybit/OCCT 源码扩展绑定并用 Emscripten 构建自有 WASM provider。对应 `BYB-01..08` 要求来源提交、补丁、ABI/消息协议、SBOM/许可证、产物 hash、句柄回收和 Bitbybit↔自构建 provider↔FreeCAD 三方黄金差分。React 仍只能通过 `BitBybitWebCadFacade` 访问几何。
兼容矩阵新增 `sourceScope`34 个模块)和 `geometryBuildStrategy`,并把 AddonManager、Cloud、Fem、Help、Idf、Import、JtReader、Material、Measure、MeshPart、OpenSCAD、Plot、Points、ReverseEngineering、Robot、Show、Start、Web 及开发/测试目录登记为 `scope-only/unsupported`,直到各自任务与证据完成。现有 Part/PartDesign/Sketcher/持久化/FCStd 等状态不提升,仍按实验或只读边界执行。
本机 `FreeCADCmd` reference probe 已接入 `./npmw run probe:freecad-reference`:实测报告为 FreeCAD 1.1.1、commit `0108fd4b4850cc46e625b60e53cea7a7bbe69f8d``guiUp=false`;当前构建可加载 `Part``Material``Measure`Sketcher/PartDesign/TechDraw/Spreadsheet/Draft/Mesh/Fem/CAM/Assembly 明确 unavailable。探针会采集核心 TypeId 和 Property 元数据,作为 `INV-02` 和后续黄金夹具的输入;完整桌面工作台行为仍需启用对应 FreeCAD 原生模块后再回放。
本轮已把 `geometry.topologyHistory()` provider 接入 `createFacadeGeometryRecomputeExecutor`:对有 Base/Tool/Profile 拓扑输入的特征,若 Worker 提供原生记录,则使用 `captureNativeTopologyHistory()` 按 kind 和 source/result index 生成 `occt-native` 历史provider 缺失、无输入或不支持时继续使用 `signature-fallback`。新增原生关系映射、删除、重复记录和索引越界测试,完整门禁 68/68 通过。该接线不等于 OCCT 原生历史已可用,真实 Bitbybit/OCCT 自构建绑定仍由 `BYB-04..07` 完成。
新增 `check:bitbybit-history` 绑定面审计并纳入 `./npmw run verify`。审计结果明确记录当前 npm 绑定的原生历史缺口,防止 `occt-native` 合同在没有 Generated/Modified/IsDeleted 实现时被误报为完成。
BYB-01/02 证据已锁定:本地 Bitbybit 源码快照为 `d3f52bd1fcf78148b60800d69ed6b42e53f4ad06`(版本 `1.1.1`),记录于 `config/compatibility-matrix.json`;门禁会同时校验源码提交与安装包版本。
本轮已完成 BYB-04 的第一版实际编译:`native/occt-history` 从缓存 OCCT `bb75017e915f6509a4bfa8b551f853352754c2da`8.0.0)构建 `TKBO``TKDESTEP``TKXSBase``TKDE` 和 Embind WASM`./npmw run test:occt-history` 通过,`shapeToStep -> booleanHistoryFromStep(cut)` smoke case 返回 42 条原生关系记录。`mapNativeOcctHistoryRecords``createNativeOcctStepHistoryBridge` 已把 provider 协议接入 Facade 类型边界。该 provider 当前仍是独立 WASM 实例;跨 Bitbybit 主 WASM 只能通过 STEP 文本序列化交换,不能直接传递指针。
## 15. 2026-08-03 原生 OCCT 历史 + STEP 跨 WASM 桥接
- `native/occt-history` 现从 OCCT `bb75017e...` 编译 `TKBO``TKDESTEP``TKXSBase``TKDE`Embind 暴露 `Generated``Modified``IsDeleted``STEPControl_Reader/Writer``shapeToStep``booleanHistoryFromStep`
- 原生 smoke 已验证 `shapeToStep(makeBox()) -> STEP text -> booleanHistoryFromStep()``cut` 返回 42 条历史记录;最终 wasm 在 Node 22.23.2 可实例化。
- 由于当前 Emscripten/OCCT 大型静态链接的 wasm 异常控制流限制,依赖库固定 `-O0 -fexceptions`Embind wrapper 固定 `-O2 -fexceptions`;产物 hash 记录在兼容矩阵并由 `check:bitbybit-history` 校验。
- `createNativeOcctStepHistoryBridge()` 已加入 Facade它只把 Bitbybit `exportStep()` 的文本交给原生 provider禁止传递跨 WASM ShapeHandle重算器仅对 `Part::Fuse/Cut/Common` 注入明确 operation其余特征继续签名回退。
该里程碑仍不是默认 GeometryRuntime也没有把所有 PartDesign 特征切换到原生 provider本轮已补齐 `BitbybitGeometryRuntime.configureNativeHistory()`,显式配置后 Boolean 重算会通过 STEP 和协调器消费原生记录。浏览器真实 WASM 实例化、STEP 精度/单位策略和 Bitbybit↔原生↔FreeCAD 三方黄金差分仍是 `BYB-05..08``TSN-03..10` 后续门禁。
## 16. 2026-08-03 原生历史协议与故障隔离
- 新增 `NATIVE_OCCT_HISTORY_PROTOCOL_VERSION = 1`,请求携带 `documentId/documentVersion/operationId` 和两份 ISO-10303-21 STEP 文本,响应携带 provider 能力、原生历史和上下文回显。
- `DirectNativeOcctHistoryProvider` 绑定已编译 Embind 模块;`NativeOcctHistoryCoordinator` 统一处理 AbortSignal、超时、取消、stale 文档版本和并发 generation未把任何 ShapeHandle 放进消息协议。
- Facade 测试新增协议上下文、STEP 格式拒绝、timeout/cancel/stale 覆盖;完整测试数更新为 72/72。
该协议已完成 BYB-05 的类型/合同层,并新增 `NativeOcctHistoryWorkerProvider`/Worker 入口;构建脚本会把产物发布到 `/native/occt-history/``BitbybitGeometryRuntime` 可显式配置该 provider 并把 STEP 历史接入 Facade 重算。跨浏览器真实 WASM 实例化、Worker 崩溃恢复和三方黄金差分仍需单独验证,不能把 Node 原生 smoke 当作浏览器证据。
本轮文档变更验证必须使用项目包装器:
```bash
./npmw run verify
git diff --check
jq empty config/compatibility-matrix.json
```
## 17. 2026-08-03 本机 FreeCAD 参考与后续安排
再次执行 `./npmw run probe:freecad-reference` 已确认锁定 oracle 为 FreeCAD `1.1.1`、提交 `0108fd4b4850cc46e625b60e53cea7a7bbe69f8d`。当前缓存构建 `guiUp=false`,可加载 `Part/Material/Measure`;其余工作台是构建缺失证据,不是对应 Web 功能的行为 oracle。
新增 [FreeCAD 1.1.1 全功能对标执行路线图](freecad-reference-execution-roadmap.zh-CN.md),按 R0 参考环境、R1 几何/拓扑、R2 Sketcher、R3 参数化核心、R4 FCStd、R5-R8 工作台与平台长尾、R9 发布门禁连续执行。近期先完成完整桌面 O2 oracle、机器清册差分、真实浏览器原生历史三方黄金再进入 planegcs 与 PartDesign 完整闭环。