# 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. 当前架构主链

```text
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. 关键依赖链

```text
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 条记录中，22 种/4304 条已有通用原生 codec，5 种/683 条已有专用 codec，仍有 58 种/523 条只能 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` 从原生报告生成，并由 `check:freecad-active-work-queue` fail-closed 校验。当前共 487 个微任务：134 `completed`、1 `in_progress`、352 `pending`；`maxInProgress=1`，唯一下一任务是 `TSN-PAIR-fuse-pad`。

| 微里程碑 | 任务粒度 | 数量 | 状态 | 下一退出条件 |
| --- | --- | ---: | --- | --- |
| `ORA-GUI-BASELINE` | 1 个配置边界或 1 个 GUI 命令分片 | 106 | 106 completed | 已关闭：100/100 分片、1111/1111 命令状态、2 个上下文延迟命令均有证据 |
| `ORA-GUI-WORKFLOWS` | 1 个命令族的 1 种工作流状态 | 7 | 7 completed | `PartDesign_Pad` 五态原生工作流、聚焦断言和 exact blocker 更新已关闭 |
| `TSN-RECOVERY-DRIFT` | 1 个原生 case 或 1 个生产 mutation | 13 | 13 completed | 11 个 PartDesign case 与生产 `cut`/`rotate` 漂移均已分类为允许演进 |
| `TSN-ORDERED-PAIRS` | 1 个有序操作对 | 361 | 8 completed / 1 in_progress / 352 pending | `fuse->rotate` 已关闭；当前只分类 `fuse->pad` |

`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/命名批次：

```bash
./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/文档批次：

```bash
./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
```

合并前统一门禁：

```bash
./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 版”。