Web_FreeCAD_Bitbybit/docs/current-work.zh-CN.md

Web FreeCAD 当前工作主线

更新时间：2026-08-15

1. 唯一目标

本项目的目标是把锁定的 FreeCAD 1.1.1 能力准确迁移到浏览器，而不是另做一套外观相似的通用 Web CAD。

浏览器端必须继续遵守现有边界：React 只负责交互，所有 CAD 业务通过 BitBybitWebCadFacade；几何、求解、命名和持久化分别在受控 Worker/WASM 边界内执行；最终几何相似不能替代 FreeCAD 文档语义、原生历史、拓扑命名和 FCStd 往返证据。

2. 当前真实状态

截至 2026-08-15：

• 系统级 FreeCAD exact claim 为 false。
• 34 个模块中 0 exact、26 compatible、5 proxy、3 development。
• 兼容实现账本 P01-P10 已全部标记为 completed，表示已有实现和对应门禁，不表示与 FreeCAD 完全等价。
• exact 计划共 52 项：5 completed、36 in_progress、11 pending。
• 已完成的 exact 项只有 EX-TSN-00..03 和 EX-PD-02：原生命名证据边界、逐阶段历史、生产私有命名、同构来源处理，以及 Attachment/XLink 生命周期。
• exact 发布任务 EX-REL-01 仍为 pending，34 个模块都不得提升为 exact。
• 当前工作树包含 TSN 逐阶段相关性、Property 状态/codec、CAM/LinuxCNC 验证资产、oracle 清册分类和首个 Pad GUI 五态工作流；聚焦门禁、完整 verify、发布产物验签和最终差异校验均已通过。

状态冲突时按以下顺序取真值：

1. config/freecad-web-exact-parity-plan.json：是否达到 FreeCAD exact 及具体阻断项。
2. config/release-capability-matrix.json：对用户可声明的模块能力等级。
3. config/freecad-execution-plan.json：兼容实现工作包是否已有执行闭环。
4. config/*-verification.json 和原生 oracle：某次具体环境运行的证据。
5. docs/continuation-status.zh-CN.md：按时间追加的历史日志，不作为当前总状态入口。

状态字段需要结合依赖读取：in_progress 只表示已有证据或实现，不表示当前可直接关闭；少数 completed 项是按自身验收范围关闭的独立切片，即使它引用的更大上游任务仍开放，也不能反推整条依赖链已经完成。

3. 当前架构主链

React / FreeCAD Web UI
        |
BitBybitWebCadFacade
        |
Document + Property + Transaction + DAG/Recompute
        |
Geometry / Sketch / Naming / Project Facades
        |
Dedicated Workers
        |
Bitbybit OCCT + FreeCAD naming + planegcs + SQLite OPFS
        |
FCStd / STEP / IGES / mesh / engineering resources

任何新功能都必须接入这条主链，不能从 React 绕过 Facade 直接调用 Three.js、OCCT、文件系统或持久化实现。

4. 关键依赖链

EX-ORA-01 -> EX-ORA-02 -> EX-KER-01
     |                         |
     +-> EX-DOC-01             +-> EX-PART-01 -> EX-PD-01
              |                       ^
EX-TSN-00..03 -> EX-TSN-04 -----------+
              |       |
              |       +-> EX-DOC-02
              |              |
              +--------------+-> EX-DOC-04 -> EX-FC-01
EX-DOC-01 -> EX-DOC-03 ---------^

核心链闭合后 -> GUI/工作台 -> 跨浏览器 QA -> EX-REL-01

当前形式上没有未完成前置的 P0 根任务只有 EX-ORA-01 和 EX-TSN-04。EX-DOC-01 已有可继续收敛的局部实现，但整体关闭仍依赖 EX-ORA-01；Sketcher、Part、PartDesign、FCStd 和 CAM 不作为当前新增范围，除非它们是关闭上述根任务所需的验证夹具。

5. 执行优先级

P0-A：锁定完整原生 oracle

对应 EX-ORA-01/02。当前隔离配置下有 1111 个工作台启动命令、19 个 source-only 命令和 2 个上下文延迟命令；1111 个启动命令已拆为 100 个独立原生分片，全部完成 no-document/document/selection 三状态采样。首个 PartDesign_Pad 命令族的 success、disabled、failure、cancel、recovery 五态工作流和 blocker 更新已全部完成；其他命令族及运行时对象/Property 的未知项仍保持开放。没有原生基线的功能不进入 exact 实现判断。

P0-B：关闭跨特征拓扑命名

对应 EX-KER-01、EX-TSN-04。锁定 30-case corpus 已按 9 Boolean + 11 PartDesign + 6 复合 Boolean + 4 dress-up 逐案例执行原生属性编辑，30/30 都传播到最终 Shape，219/219 阶段几何恢复，657 条 before/edited/restored 阶段记录完成 fail-closed 对账；恢复状态再保存、重开、二次保存后的错误绑定、未解释关系和名称漂移均为零。11 个 PartDesign 案例/28 个恢复命名阶段与生产链 2 个恢复拓扑案例/5 个下游阶段均已通过独立原生复跑分类为允许演进，恢复几何与初值一致且演进命名在 save/reopen/resave 后稳定。生产 Worker 五阶段顺序链仍只有 2/5 原生 builder，3/5 为通用 Shape 代理，rotate 仍缺注册 mutation family；19 类生产操作的 361 个有序组合现覆盖回放 8 个，其中 fuse->rotate 使用单输入 BRepBuilderAPI_Transform 和 15→22.5→15 独立角度变异，因此门禁继续 fail-closed。

P0-C：关闭 App 文档语义

对应 EX-DOC-01/02/03。85 种运行时 Property、5510 条记录中，30 种/4361 条已有通用原生 codec，5 种/683 条已有专用 codec，仍有 50 种/466 条只能 opaque 保存。15 类已观察到的 Property status 均已进入类型化 Facade 行为；LockDynamic 的动态属性增删改事务和 PartialTrigger 的 partial-document observer 行为已有原生 oracle 与 Facade 测试。后续依次补齐剩余 Property codec/editor、完整 observer 顺序、局部重算失败、Extension 和 FeaturePython 边界。

P0-D：关闭核心建模语义

对应 EX-SK-01/02、EX-PART-01、EX-PD-01。按原生 oracle 逐特征补齐参数组合、失败诊断、编辑恢复、原生 history 和 FCStd 往返；不能按整个工作台批量提升等级。

P0-E：关闭 FCStd 和核心格式

对应 EX-FC-01、EX-FMT-01。先完成所有原生 Property/Shape/ElementMap/StringHasher 的保存、重开、再保存，再处理 STEP/IGES 的高级元数据和装配语义。

P1/P2 的 GUI 全量对标、其他工作台、代理模块和跨浏览器发布，必须在上述 P0 主链有明确前置证据后推进。当前不再以增加工作台数量作为主要进度指标。

6. 里程碑队列

按下表自上而下推进。并行上限为“一个实现里程碑 + 一个只读 oracle 准备项”；未达到退出条件时，不切换到新的工作台或长尾模块。

顺序	任务	当前状态	交付范围	退出条件
M0	收口当前工作树	completed	将 TSN、Property、CAM/LinuxCNC 三组已有增量分别核对证据和边界，不再混入新功能	聚焦门禁、完整 verify、git diff --check、全部 JSON 解析通过；计划与报告无陈旧哈希
M1	EX-ORA-01 运行时清册闭合	in_progress	对 352 个注册对象、1111 个启动 GUI command、19 个 source-only command、2 个 context-only command 和 GUI 工作流状态生成差异账本	每个候选均为 runtime-backed 或有机器可读排除原因；成功/禁用/失败/取消/恢复工作流未知项为零
M2	EX-TSN-04A 漂移判定	completed	逐项解释 11 个 PartDesign case 的 28 个恢复命名摘要演进，以及五阶段链的 5 个恢复拓扑变化	每个差异都有 FreeCAD 复跑证据并被判定为稳定语义、允许演进或实现缺陷；未知项为零，缺陷有回归测试
M3	EX-TSN-04B 转换矩阵闭合	in_progress	将 19×19 的 361 个有序操作对按原生输入/输出类型分类；原生允许的组合使用真实 builder 回放，原生拒绝的组合保存失败 oracle	361/361 已分类；可执行组合的 history/naming/mutation/resave 通过；不可执行组合的原生错误可复现；不再用通用 Shape 代理冒充 feature builder
M4	EX-DOC-01 Property 批次	after-M1	先做高复用 App 类型与链接/列表类型，再处理 Material、File、PythonObject 等带安全或工作台边界的类型	每批均具备原生值/状态/editor oracle、Facade codec、FCStd reopen/resave、Undo/Redo 和 Chrome 证据；opaque 数量只按机器报告下降
M5	EX-DOC-02/03 文档闭环	after-M3+M4	observer 顺序、事务 abort、局部重算失败、Extension、FeaturePython、copy/clone/delete/relink	原生与浏览器事件序列一致；失败不污染最后有效状态；资源归零；随后再推进 EX-DOC-04
M6	EX-ORA-02/KER/PART/PD/SK 纵向切片	after-M2+M5	由 oracle 差异报告选择一个特征族，一次完成参数、失败、恢复、history、命名、FCStd 和 UI Task 生命周期	单特征全部证据通过后才选择下一族；不按整个工作台批量提升 exact
M7	EX-FC-01/FMT-01	after-M3+DOC-04	所有已支持对象、Property、Shape、ElementMap2、StringHasher 的 FreeCAD-Web-FreeCAD 双向 mutation；随后补 STEP/IGES 高级元数据	两次保存重开后无未知语义漂移，未知资源按合同保留，格式差异全部登记
M8	EX06..EX10	deferred	GUI 全量、生产/工程工作台、代理策略、跨浏览器、性能、安全和发布	52/52 exact 任务、34/34 exact 模块及最终 promotion report 全部满足后才执行 EX-REL-01

M3 不要求把 FreeCAD 本身拒绝的组合强行实现为顺序特征链。正确证据是：先由原生 FreeCAD 判断组合是否合法，再分别保存成功 builder 证据或稳定失败证据。M4 也不按记录数盲目排序；PropertyPythonObject、文件路径和 Material 类型必须先确定执行、安全和资源边界。

6.1 微任务队列

机器真值为 config/freecad-active-work-queue.json，由 generate:freecad-active-work-queue 从原生报告、Property 语义报告、exact 计划和后续进度账本生成，并由 check:freecad-active-work-queue fail-closed 校验。实时任务数、里程碑状态和唯一下一任务只发布在 docs/freecad-active-work-status.generated.zh-CN.md，本手写文档不再复制动态数字。

队列现在覆盖 GUI oracle、TSN 漂移、全部有序操作对、逐 Property codec、Document 语义、核心建模、FCStd/格式、GUI 全量、文档/工程工作台、平台/脚本/代理和 QA/发布。每个后续能力拆为 A-I 九个串行任务；完成证据记录在 config/freecad-follow-up-task-progress.json，跳号、未知任务、空证据和第二个活动任务都会使生成器失败。

ORA-GUI-WORKFLOWS 已按七步关闭：选定命令族、成功、禁用、失败、取消、恢复、更新 blocker/门禁。一步只新增一种原生状态证据，前一步未通过时不启动后一步。

TSN-RECOVERY-DRIFT 的 13 个独立任务已全部关闭；11 个 PartDesign case 记录在 config/freecad-recovered-naming-classification.json，生产 cut/rotate 记录在 config/freecad-production-drift-classification.json。两类 checker 都锁定原生 harness 哈希、两次运行一致性和持久化稳定性，且每项只有稳定语义、允许演进或实现缺陷一种结论。

100 个 GUI 分片分别对应 ORA-GUI-SHARD-000..099，每片覆盖排序命令全集中的 11 或 12 个命令。每片有独立报告、SHA-256、起止索引和退出条件；合并器要求 100 个区间连续、1111 个 ID 唯一且全集哈希一致。

7. 每项工作的完成定义

一个 FreeCAD 能力只有同时具备以下证据，才可关闭对应 exact 任务：

1. 锁定 FreeCAD 1.1.1 的原生成功、失败、取消和编辑 oracle。
2. Facade 内的结构化实现，无 UI 直连内核旁路。
3. 真实浏览器 Worker/WASM 回放，不以 Node mock 代替。
4. FCStd 保存、关闭、重开、再次保存后语义稳定。
5. Undo/Redo、局部失败、崩溃或 stale generation 不破坏最后有效状态。
6. ShapeHandle、Worker、OPFS 等资源在结束后正确释放。
7. 聚焦测试、相关 Chrome gate、计划/能力矩阵和差异说明同步更新。
8. exact promotion gate 不依靠改写报告或放宽断言通过。

8. 验证矩阵

每次修改先运行所属聚焦门禁；只有聚焦门禁通过后才运行全量门禁。

TSN/命名批次：

./npmw run check:freecad-composite-history-elementmap
./npmw run check:freecad-tsn-stage-correlation
./npmw run check:freecad-exact-history-elementmap-gate
./npmw run check:freecad-naming-production
./npmw run check:chrome-freecad-naming-production

Property/文档批次：

./npmw run check:freecad-native-property-semantics
./npmw run check:freecad-property-status
./npmw run test:facade
./npmw run check:freecad-fcstd-roundtrip
./npmw run check:chrome-fcstd-semantic

合并前统一门禁：

./npmw run check:execution-plan
./npmw run verify
git diff --check
find config -maxdepth 1 -type f -name '*.json' -print0 | xargs -0 -n1 jq empty

若修改了 oracle/harness 或验证报告生成逻辑，必须先实际执行对应 probe:*/test:chrome-*，再运行只读 check:*；静态旧报告不能作为完成证据。

9. 维护规则

• 本文只维护当前状态、关键路径和下一批队列；长期范围仍由 exact JSON 账本管理，历史事实只追加到 continuation 日志。
• 每个里程碑只更新自己直接影响的实现、测试、verification、exact blocker 和能力矩阵，不顺手刷新无关报告。
• completed 必须对应机器账本中的验收范围；局部进展写入 blocker 数字，不提前改状态。
• 任何 failed 浏览器 gate、陈旧 artifact hash、资源泄漏或未知语义差异优先于新增能力。

10. 明确不做

• 不把项目改成远程桌面、服务端截图流或仅 UI 仿制品。
• 不新增绕过 Facade 的几何、渲染、脚本或存储入口。
• 不以 mock、静态截图、最终 Shape 相似或单次成功回放声明 exact。
• 不为追求模块数量继续铺开低优先级工作台，优先关闭 P0 核心语义。
• 不在 EX-REL-01 全部条件满足前宣传“完整 FreeCAD Web 版”。