1751 lines
143 KiB
Markdown
1751 lines
143 KiB
Markdown
# BitBybit + FreeCAD 业务语义 + WASM + Three.js Web CAD
|
||
|
||
## 1. 文档目的
|
||
|
||
本文是项目的需求基线、技术路线、实施步骤和任务分解。当前仓库已经完成“全量前端页面设计冻结”的静态实现；本文中的真实 BitBybit Facade、FreeCAD/OCCT WASM、Three.js 几何视口、SQLite WASM 和 OPFS 持久化仍按后续里程碑实施。
|
||
|
||
本文的目标是把“基于 BitBybit、充分利用 FreeCAD 业务逻辑、WASM 几何计算、Three.js 三维可视化、React 应用框架、OPFS + SQLite WASM 本地存储”的设想，收敛为可以评审、估算、分阶段验收的工程计划。
|
||
|
||
### 1.1 方案结论
|
||
|
||
采用以下总体路线：
|
||
|
||
1. 以 BitBybit Web CAD Facade 作为浏览器侧唯一入口；Facade 内部使用 BitBybit 的 OCCT WASM 能力，必要时使用 Manifold/JSCAD 作为轻量网格或 CSG 辅助内核。
|
||
2. FreeCAD 是界面信息架构和前端业务逻辑的规范来源：工作台、菜单/工具栏、Model/Tasks、Data/View 属性、Document/Object/Feature、Body/Tip、Selection、TaskPanel、依赖图、重计算、事务和 PartDesign 工作流都以 FreeCAD 行为为基线。
|
||
3. BitBybit 是唯一运行时入口。React、Three.js Viewport、项目存储、文件导入导出和 Worker 都只能调用 BitBybit Web CAD Facade；FreeCAD 语义、OCCT/其他 WASM 内核和 SQLite/OPFS 实现均隐藏在 Facade 之后。
|
||
4. 以 SQLite WASM 作为结构化数据源，以 OPFS 保存数据库文件和大体积几何/附件。SQLite 运行在 Worker 中，主线程只通过异步服务协议访问。
|
||
5. 首个可交付版本聚焦 Part/PartDesign 的可制造零件建模和本地离线工作流；装配、TechDraw、FEM、CAM、BIM、Python 宏兼容性列为后续产品线，而不是 MVP 的隐含承诺。
|
||
6. 前端信息架构和前端业务逻辑以锁定版本 FreeCAD 为唯一规范来源：完整映射工作台、模型树、任务面板、属性编辑器、文档标签、选择驱动命令、Data/View 属性及其状态和结果；浏览器适配只允许改变呈现方式，不允许无记录地改变业务含义。
|
||
|
||
### 1.2 依据和边界
|
||
|
||
BitBybit 官方文档列出了 OCCT、JSCAD、Manifold 等 CAD 能力，并支持 Three.js 集成；其代码仓库采用 MIT 许可。FreeCAD 官方仓库描述的底层技术包括 OpenCASCADE、Python、Coin3D 和 Qt，FreeCAD 的 PartDesign 是以 Body 和累积特征为核心的参数化建模体系。因此本方案把 FreeCAD 的“界面合同、业务模型和工作流”作为规范，把 BitBybit 作为唯一公开 API 和运行时编排层，把 FreeCAD 桌面 UI、Python 解释器和 Coin3D 视图层排除在浏览器前端之外。
|
||
|
||
SQLite 官方 WASM 文档支持 OPFS VFS，但 OPFS 主要在 Worker 上使用，不同 VFS 对并发、性能及跨浏览器兼容性的取舍不同。本方案会把数据库 Worker、单写者策略、浏览器降级路径和数据导出作为一等设计目标。Three.js 同时存在 WebGL2 和 WebGPU 后端，本方案以 WebGL2 作为稳定基线，以 WebGPU 作为能力增强，不把 WebGPU 当作首发必需条件。
|
||
|
||
### 1.3 不可违反的入口约束
|
||
|
||
#### 唯一入口
|
||
|
||
定义一个版本化的 BitBybit Web CAD Facade，作为浏览器端唯一的 CAD 能力入口。Facade 不是简单的转发函数集合，而是 FreeCAD-compatible 的应用服务边界，负责命令、文档、工作台、选择、视图、存储、导入导出和任务生命周期。
|
||
|
||
所有前端模块只允许依赖 Facade 的公开类型和事件：
|
||
|
||
```text
|
||
React / UI components
|
||
│
|
||
▼
|
||
BitBybit Web CAD Facade（唯一入口）
|
||
├─ FreeCAD-compatible App/Gui/Workbench/Command services
|
||
├─ Geometry Worker（OCCT/Manifold/JSCAD WASM，内部实现）
|
||
├─ Viewport Adapter（Three.js，内部实现）
|
||
├─ Persistence Adapter（SQLite WASM + OPFS，内部实现）
|
||
└─ Import/Export Adapter（STEP/IGES/FCStd/mesh，内部实现）
|
||
```
|
||
|
||
禁止项：
|
||
|
||
- React 直接导入或调用 OCCT、FreeCAD、Manifold、JSCAD、SQLite WASM、OPFS 文件句柄或 Three.js 场景对象来实现业务规则。
|
||
- UI 直接构造 Shape、修改 Feature 属性、执行重计算或写数据库。
|
||
- 业务逻辑绕过 BitBybit Command/Task/Document API 自行维护第二套模型树或撤销栈。
|
||
- 将 FreeCAD Python API 原样暴露给浏览器或执行项目文件中的不可信脚本。
|
||
|
||
允许项：
|
||
|
||
- React 通过 Facade 获取与锁定版本 FreeCAD 对齐的文档投影、属性元数据、命令状态和任务状态。
|
||
- BitBybit Facade 内部参考、移植、编译或适配 FreeCAD/OCCT 算法，并以稳定版本化协议向前端返回结果。
|
||
- Three.js 只作为 Facade 的 Viewport 实现，应用层不依赖其对象图作为领域真值。
|
||
|
||
入口验收要求：在构建产物和依赖图中，前端业务包只能出现 BitBybit Facade 依赖；架构测试必须阻止新增绕过入口的 import 或 Worker 消息。
|
||
|
||
## 2. 产品定位
|
||
|
||
### 2.1 目标用户
|
||
|
||
- 机械设计师和工程师：创建、修改和审阅中小型参数化零件。
|
||
- 教学与培训用户：在不安装桌面软件的情况下学习 Part/PartDesign 基本流程。
|
||
- 开源项目和工具开发者：通过 TypeScript API 嵌入 CAD 能力。
|
||
- 需要离线编辑和浏览器内数据驻留的个人或小团队。
|
||
|
||
### 2.2 产品形态
|
||
|
||
- 响应式 Web 单页应用，可安装为 PWA。
|
||
- 默认 local-first：无账号也能新建、保存、导入和导出工程。
|
||
- 可选云同步服务，但云端不是几何计算的唯一依赖。
|
||
- 支持 URL 打开只读模型、下载项目包和导出标准 CAD 格式。
|
||
|
||
### 2.3 明确不做的事项（MVP）
|
||
|
||
- 不承诺兼容所有 FreeCAD Workbench、所有 Python 宏和所有 FCStd 文件。
|
||
- 不在浏览器中运行完整 Qt/Python/Coin3D 桌面应用。
|
||
- 不在首版实现多用户实时几何协作、完整版本控制和云端渲染农场。
|
||
- 不把三角网格编辑器、雕刻建模和动画系统作为核心 CAD 范围。
|
||
|
||
这里的“不做”仅表示首个可发布切片的排期边界，不表示 FreeCAD 完整准确兼容目标被取消。完整官方核心工作台覆盖按第 3.4、3.5 节和阶段 9-11 分批交付。
|
||
|
||
## 3. 需求范围
|
||
|
||
### 3.1 MVP 必须提供
|
||
|
||
#### 文档和项目
|
||
|
||
- 新建、打开、关闭、复制、重命名和删除项目。
|
||
- 一个项目可包含多个文档；文档包含对象树、参数、视图状态、单位和元数据。
|
||
- 自动保存、手动保存、保存点、崩溃恢复和最近项目列表。
|
||
- 离线运行；无网络时仍可完成建模和导出。
|
||
|
||
#### 参数化建模
|
||
|
||
- 基准面、基准轴、原点和坐标系。
|
||
- Sketch：二维几何、尺寸约束、几何约束、约束状态、草图编辑和求解错误提示。
|
||
- PartDesign Body：创建 Body、单一实体约束、特征顺序和 Tip。
|
||
- 首批特征：Additive/Subtractive Box、Pad、Pocket、Revolution、Fillet、Chamfer、Boolean、Pattern（线性和圆周）以及基本 Hole。
|
||
- Part 基本体：Box、Cylinder、Sphere、Cone、Torus、Prism 等。
|
||
- 依赖关系、特征抑制/恢复、参数修改后的增量重计算。
|
||
- 无效特征、拓扑失败、自相交和不闭合实体的可解释错误。
|
||
|
||
#### 视图和交互
|
||
|
||
- 三维视图、透视/正交相机、标准视图、适应全部、旋转/平移/缩放。
|
||
- 选择面/边/顶点/对象，悬停预选，选择过滤和选择集。
|
||
- 实体、线框、半透明和剖切/截面预览显示模式。
|
||
- 模型树、属性编辑器、任务面板、命令搜索、状态栏和消息中心。
|
||
- 基准、网格、测量、坐标读数、隐藏/显示、透明度和颜色设置。
|
||
- 键盘快捷键、右键上下文菜单、撤销/重做和操作取消。
|
||
|
||
#### 数据交换
|
||
|
||
- 导入 STEP、IGES、STL、OBJ、PLY（按内核和许可可用性逐项确认）。
|
||
- 导出 STEP、IGES、STL、OBJ、GLB/GLTF 和项目原生包。
|
||
- 原生 Web CAD 项目包包含参数树和必要的 BREP/网格缓存。
|
||
- 对 FCStd 提供“兼容性导入”能力：先支持无复杂 Python 对象的 Part/PartDesign 文档，并显示不支持对象报告。
|
||
|
||
#### 存储
|
||
|
||
- SQLite WASM 保存项目元数据、对象树、特征参数、依赖边、历史和索引。
|
||
- OPFS 保存 SQLite 数据库文件和大体积二进制资源；数据库和资源均带版本、校验和及迁移信息。
|
||
- 单 Worker 写入、事务提交、跨标签页通知和数据库锁冲突提示。
|
||
- 一键导出完整备份；一键导入备份并校验完整性。
|
||
|
||
### 3.2 第二阶段需求
|
||
|
||
- Assembly：零件实例、装配树、约束、碰撞检查和简化爆炸图。
|
||
- TechDraw：二维投影、视图布局、标注、尺寸、标题栏和 PDF/SVG 导出。
|
||
- 更完整的 Sketcher 求解器和拓扑命名稳定性策略。
|
||
- 更完整的 FCStd 双向兼容和版本迁移。
|
||
- 基础协作：工程分享、只读链接、冲突检测、对象级锁和操作日志同步。
|
||
- 插件 SDK、命令扩展、参数化组件库和脚本化建模。
|
||
|
||
### 3.3 远期可选需求
|
||
|
||
- FEM/CalculiX、CAM/Path、BIM/Arch、机器人和渲染工作台。
|
||
- 服务器端重计算、队列任务和大模型异步预览。
|
||
- 多用户实时协作、评论、审阅和变更审批。
|
||
- 与桌面 FreeCAD 的更高保真双向互操作。
|
||
|
||
### 3.4 “完整、准确使用 FreeCAD”的定义
|
||
|
||
建议以当前正式版 FreeCAD 1.1.1 的官方发布标签为初始基线，并在 POC 启动时记录精确源码提交；后续升级作为独立兼容迁移。项目不把“有 FreeCAD 风格外观”或“能调用几个 OCCT 操作”视为完成。完整性必须按固定 FreeCAD 基线版本建立可追踪矩阵，至少覆盖以下四层：
|
||
|
||
最终产品目标是对标锁定版本 FreeCAD 的完整功能语义，而不是只完成当前的 PartDesign 静态页面。任何暂未实现的工作台、命令、对象、属性、任务生命周期、撤销/重计算、文件互操作或脚本能力，都必须在兼容矩阵中保持可见状态，不能用“后续支持”替代完成定义。
|
||
|
||
1. **界面层**：菜单、工具栏、工作台、Combo View、Model/Tasks、Property Editor、Data/View 属性、报告视图、选择视图、任务确认/取消、快捷键、导航预设、首选项和文档标签。
|
||
2. **应用业务层**：Document、DocumentObject、Property、PropertyLink、Expression、事务、撤销/重做、依赖 DAG、状态机、重计算、错误恢复、对象生命周期和视图状态分离。
|
||
3. **工作台层**：官方核心工作台的命令、参数、选择前置条件、结果类型、失败行为和对象映射。第一批覆盖 Part、PartDesign、Sketcher、Draft、TechDraw、Spreadsheet、Mesh、Assembly；随后覆盖 Path、FEM、Arch/BIM、Robot、Raytracing/Rendering 和其他官方核心模块。
|
||
4. **文件和脚本层**：FCStd 对象/属性/链接/视图状态的读取和写出；对官方 FreeCAD Python API 提供明确的兼容等级。第三方 Addon 和任意 Python 执行不能默认为“完整兼容”。
|
||
|
||
每一项都必须有：FreeCAD 版本、源码/文档依据、Web 行为定义、BitBybit Facade API 映射、Web 实现状态、差异说明、黄金样例和自动化测试。兼容状态使用 `exact`、`compatible`、`read-only`、`proxy`、`unsupported` 五级，不允许用“支持”一个词掩盖差异。
|
||
|
||
### 3.5 FreeCAD 核心覆盖矩阵
|
||
|
||
| FreeCAD 区域 | 完整性要求 | 浏览器实施方式 | 首个可用版本 |
|
||
|---|---|---|---|
|
||
| App/Base | Document、Object、Property、Link、Expression、事务、依赖、重计算和状态 | FreeCAD App 核心优先编译为内部 WASM；BitBybit Facade 负责对象和命令协议 | Core 1 |
|
||
| Gui | Command、Workbench、Selection、ViewProvider、Preferences、Dock/Task 状态 | React/Three.js 重建 UI，但行为由 FreeCAD-compatible Gui 服务定义 | Core 1 |
|
||
| Part | 精确 BREP、基本体、布尔、导入导出、检查和测量 | BitBybit Facade 内的 OCCT WASM adapter | Core 1 |
|
||
| PartDesign | Body、Origin、Tip、特征历史、基于草图的加/减特征和 dress-up | FreeCAD 语义服务 + BitBybit 几何执行器 | Core 1 |
|
||
| Sketcher | 草图几何、完整约束集、求解器状态、支持面和外部几何 | Sketcher 核心/求解器 WASM 优先，React 编辑器消费 Facade 协议 | Core 1/2 |
|
||
| Draft | 2D/辅助建模、工作平面、捕捉、标注和对象属性 | FreeCAD 业务语义移植，几何操作进入 Facade | Core 2 |
|
||
| TechDraw | 页面、模板、投影视图、尺寸、标注和导出 | 领域模型由 Facade 提供，Three.js/Canvas/SVG 只负责显示 | Core 2 |
|
||
| Spreadsheet | 单元格、表达式、引用、格式和与模型属性联动 | 兼容的表格模型和表达式服务由 Facade 提供 | Core 2 |
|
||
| Mesh | 网格导入、修复、分析、显示和导出 | BitBybit mesh 能力或内部 WASM adapter | Core 2 |
|
||
| Assembly | 零件实例、装配约束、层级、求解和碰撞 | FreeCAD Assembly 语义服务 + 几何/约束 Worker | Core 2 |
|
||
| Path/CAM | 工具、刀路、作业、后处理和 G-code | 独立受控模块；浏览器侧先做参数/预览，重计算可选服务端 | Core 3 |
|
||
| FEM | 分析对象、材料、边界、网格、求解器和结果 | FreeCAD FEM 业务模型；CalculiX/网格求解器单独 WASM 或服务端 | Core 3 |
|
||
| Arch/BIM | IFC/BIM 对象、属性、墙/结构/空间及导入导出 | 分阶段引入，不能把 PartDesign 对象冒充 BIM 兼容 | Core 3 |
|
||
|
||
“Core 1/2/3”是覆盖批次，不是替代需求。只有矩阵中的每个条目达到约定兼容级别并通过黄金样例，才能宣称对应层级完成。
|
||
|
||
## 4. 核心业务模型
|
||
|
||
### 4.1 文档对象模型
|
||
|
||
文档采用与锁定版本 FreeCAD 对齐的对象图，而不是单纯的“最终网格”：
|
||
|
||
- `Document`：项目内的建模文档、单位制、标签、版本和根对象。
|
||
- `Object`：所有可持久化对象的统一标识、类型、名称、标签、可见性和属性集合。
|
||
- `Container`：Part、Body、Assembly 等层级容器。
|
||
- `Feature`：输入引用、参数、输出 Shape、计算状态和错误信息。
|
||
- `Sketch`：几何、约束、支持面/基准、求解结果和映射关系。
|
||
- `Shape`：BREP 引用、三角化缓存、包围盒、拓扑子形状索引和显示材质。
|
||
- `Link`：对象引用、子形状引用、外部文档引用和版本化引用。
|
||
|
||
每个对象必须有稳定的 UUID；显示名称不能作为引用主键。对象类型采用版本化字符串，例如 `PartDesign::Pad@1`，以便未来迁移。
|
||
|
||
### 4.2 特征图和重计算
|
||
|
||
1. 属性变化产生领域命令。
|
||
2. 命令在事务中写入文档状态并记录反向操作。
|
||
3. 依赖图分析受影响的特征闭包。
|
||
4. 计算调度器在 Geometry Worker 中按拓扑顺序执行。
|
||
5. 每个节点产出 Shape、诊断、包围盒和可视化缓存。
|
||
6. 计算完成后以不可变结果提交到主线程；失败节点保留上一次有效结果并标记错误。
|
||
|
||
首版使用单文档串行重计算保证确定性；后续再把无依赖节点并行化。几何运算必须可取消，长任务不可阻塞 UI。
|
||
|
||
### 4.3 单位和精度
|
||
|
||
- 内部长度统一使用毫米或 SI 基准单位，UI 根据文档单位制显示。
|
||
- 所有角度、长度、质量和容差参数都保存数值、单位和显示精度。
|
||
- 明确建模容差、显示容差和导入容差，禁止将渲染精度误当成几何精度。
|
||
- 对浮点结果使用容差比较和格式化策略，避免参数往返产生无意义变更。
|
||
|
||
### 4.4 FreeCAD 业务语义对照
|
||
|
||
Web CAD 必须先定义“兼容哪些语义”，再选择实现语言。以下对象不是 UI 临时状态，而是领域模型的一部分：
|
||
|
||
| FreeCAD 参考概念 | Web CAD 对应概念 | 必须保持的语义 |
|
||
|---|---|---|
|
||
| `App::Document` | `Document` 聚合根 | 对象注册、事务、重计算、保存、恢复和唯一名称 |
|
||
| `App::DocumentObject` | `DocumentObject` | 类型、内部名称、显示标签、属性、状态、输入和输出 |
|
||
| `Property` / `PropertyLink` | 类型化属性和引用属性 | 校验、持久化、只读/隐藏、依赖、循环检测和链接失效 |
|
||
| `Part::Feature` | `ShapeFeature` | 参数输入、BREP 输出、可见性和错误状态 |
|
||
| `PartDesign::Body` | `Body` 容器 | 有序特征历史、Tip、单一实体和局部坐标系 |
|
||
| `Sketcher::SketchObject` | `SketchFeature` | 二维几何、约束、支持面、自由度和求解状态 |
|
||
| `ViewProvider` / View 属性 | `ViewObject` 投影 | 颜色、透明度、线宽、显示模式和选择表现，不改变几何定义 |
|
||
| Workbench | `WorkbenchDefinition` | 命令集合、工具栏布局、菜单、选择规则和上下文任务 |
|
||
| Task panel | `TaskSession` | 一次命令的草稿参数、实时预览、应用、取消和校验 |
|
||
| Selection | `SelectionService` | 对象、子形状、预选、选择过滤和命令可用性 |
|
||
|
||
内部名称创建后不可修改，用于持久化和引用；用户可见标签允许重复和重命名。任何逻辑都不得使用显示标签代替 UUID/内部名称。
|
||
|
||
### 4.5 App 与 View 分离
|
||
|
||
参考 FreeCAD 的 App/Gui 分离，系统维护两类状态：
|
||
|
||
- `App state`：建模事实，包括文档、对象、属性、依赖、单位、表达式、Shape 和计算状态；由 BitBybit 内部 FreeCAD-compatible 领域层和 Geometry Worker 维护，可持久化、可重算。
|
||
- `View state`：颜色、透明度、显示模式、可见性、相机、剖切、选择和面板布局；由 ViewObject/视口服务维护，部分可持久化，但不得作为几何计算输入。
|
||
|
||
约束如下：
|
||
|
||
- React 组件不得直接修改内核句柄或 Shape。
|
||
- Three.js 对象不是文档真值；场景可以销毁并从 App + View 投影完整重建。
|
||
- 重计算完成后更新 App 输出，再由 ViewObject 生成新的三角化显示；不允许从 Three.js BufferGeometry 反推精确 BREP。
|
||
- 对象删除、撤销、文档关闭和内核重启时，App、View、WASM 句柄和缓存必须按统一生命周期清理。
|
||
|
||
### 4.6 属性系统
|
||
|
||
首版属性类型至少包括：Boolean、Integer、Float、String、Enumeration、Length、Angle、Vector、Placement、Color、File、ObjectLink、SubshapeLink、ObjectLinkList、Expression 和只读 Shape 摘要。
|
||
|
||
当前 Facade 已补齐 Vector、Placement、ObjectLinkList/StringList 的结构化值合同，并为几何对象提供可编辑 Placement 数据属性；复合值经过有限数、非零旋转轴、对象存在性校验，深拷贝贯穿 Undo/Redo、自动保存和 SQLite JSON 往返。Placement 编辑器采用可展开的 Position/Axis/Angle 网格。File、只读 Shape 摘要、多选 mixed 和 Placement 对真实特征执行器的完整 FreeCAD 局部坐标语义仍待后续门禁。
|
||
|
||
每个属性定义包含：
|
||
|
||
- 稳定名称、显示标签、分组、说明、数据类型和默认值。
|
||
- 数值范围、步长、单位、精度、枚举选项和自定义编辑器类型。
|
||
- `ReadOnly`、`Hidden`、`Transient`、`Output`、`NoRecompute`、`NoPersist` 等编辑和生命周期标志。
|
||
- 是否允许表达式、是否参与依赖图、是否允许跨文档引用。
|
||
- 序列化版本和旧版本迁移函数标识。
|
||
|
||
属性修改流程：
|
||
|
||
1. 属性编辑器提交原始输入。
|
||
2. 单位服务解析并标准化数值。
|
||
3. 属性定义执行类型和业务校验。
|
||
4. Command Bus 开启事务并写入新值。
|
||
5. 对象执行 `onPropertyChanged`，只做轻量派生状态和脏标记，禁止在此同步执行昂贵几何运算。
|
||
6. 依赖图传播 touched 状态，调度器决定 `mustExecute` 节点。
|
||
7. 重计算成功后提交输出属性和 Shape；输出属性默认不再次触发父对象重计算。
|
||
8. 失败时保留事务和错误上下文，由命令策略决定回滚参数或保留无效编辑。
|
||
|
||
### 4.7 文档和对象状态机
|
||
|
||
#### Document 状态
|
||
|
||
`new → loading → ready → recomputing → ready/error → saving → ready → closing → closed`
|
||
|
||
- `loading/restoring` 时允许构造对象图，但不逐对象触发重计算。
|
||
- `ready` 时才接受建模命令；只读文档只接受 View 命令。
|
||
- `recomputing` 时允许导航和查看，冲突的建模命令排队或取消当前任务。
|
||
- `saving` 保存一致性快照；保存不得读取一半更新的 Shape。
|
||
- `error` 是文档级恢复状态，不等于所有对象失效。
|
||
|
||
#### DocumentObject 状态
|
||
|
||
`clean | touched | recomputing | valid | warning | error | suppressed | missing-reference | proxy | deleted-pending`
|
||
|
||
状态必须能同时表达计算状态和可见性，不以单个布尔字段混合。对象处于 `error` 时保留最近一次有效 Shape，并在视图中使用错误标识区分“旧结果”和“当前参数结果”。
|
||
|
||
### 4.8 依赖、链接和重计算
|
||
|
||
- 对象输入引用形成有向无环图；新增或替换链接前执行循环检测。
|
||
- Link 包含目标文档、对象 UUID、可选子形状引用、引用版本和解析状态。
|
||
- 删除被引用对象时，不静默清空全部引用；将依赖对象标记为 `missing-reference`，提供“替换引用、删除依赖、撤销删除”动作。
|
||
- `recompute(document)` 按拓扑顺序执行 touched 闭包；支持全量重算、选中对象重算和跳过抑制对象。
|
||
- 每次执行接收不可变输入快照、上游 ShapeHandle 和取消信号，返回输出、诊断、耗时和内存摘要。
|
||
- 文档版本发生变化后，过期 Worker 结果不得提交。
|
||
- 调度器记录导致重算的属性链，UI 能回答“为什么这个对象被重新计算”。
|
||
|
||
### 4.9 Body 和 PartDesign 规则
|
||
|
||
- Body 内特征是有序历史，不是任意树层级；模型树应以线性顺序表达并显示 Tip。
|
||
- 新增特征默认使用当前 Tip 作为基体，成功后成为新 Tip；失败特征不能自动替换有效 Tip。
|
||
- 进入某个历史特征编辑时，后续特征临时隐藏或进入预览状态；完成后按顺序重算。
|
||
- Body 默认要求每一步产出单一连续实体；产生多实体时给出明确错误和可选改用 Part Boolean 的建议。
|
||
- 删除中间特征前先展示直接/间接依赖；用户可选择级联删除、保留为失效对象或取消。
|
||
- 特征重排必须在执行前校验依赖方向和支持面引用，不能只移动树节点。
|
||
|
||
### 4.10 Command、事务和任务会话
|
||
|
||
所有写操作分为三层：
|
||
|
||
- `CommandDefinition`：稳定命令 ID、所属工作台、图标、快捷键、选择前提、权限、是否可撤销。
|
||
- `TaskSession`：命令执行过程中的草稿参数、临时选择、预览 Shape、校验和 Apply/OK/Cancel 生命周期。
|
||
- `DomainTransaction`：一次原子文档变更及其 inverse/补偿信息。
|
||
|
||
命令状态为 `hidden | disabled | enabled | active`。状态由当前工作台、活动文档、文档读写状态、选择类型、对象状态和内核能力共同计算。禁用命令必须能返回原因，供 tooltip 和命令搜索展示。
|
||
|
||
`Cancel` 必须销毁预览和草稿，不写正式事务；`Apply` 提交当前结果并保持任务面板；`OK` 提交并关闭；`Esc` 优先取消当前拾取步骤，再取消任务会话。任务会话未结束时切换文档必须提示保存草稿、放弃或返回。
|
||
|
||
### 4.11 选择和子形状引用
|
||
|
||
- Selection 项包含文档、对象 UUID、元素类型、稳定子形状引用、拾取点和选择来源。
|
||
- 预选与正式选择分开；鼠标移出只清除预选，不清除正式选择。
|
||
- 命令通过 Selection Predicate 声明输入，例如“一个平面或平面面”“一个 Body 内的草图”“一组同一实体的边”。
|
||
- 模型树选择和三维选择双向同步，但支持临时锁定，避免任务拾取期间意外改变输入。
|
||
- 子形状引用优先使用特征来源、几何签名和邻接上下文，不使用单一 `Face3/Edge7` 序号作为长期引用。
|
||
- 拓扑匹配不确定时不得静默选取；进入待确认状态并显示候选。
|
||
|
||
### 4.12 表达式和参数驱动
|
||
|
||
- 属性可绑定常量、同文档属性引用和受限表达式。
|
||
- 表达式解析生成独立依赖边并参与循环检测。
|
||
- 修改被引用参数时显示受影响对象数量，按同一重计算流程执行。
|
||
- 首版表达式语言只提供数学、单位和属性引用，不执行任意 JavaScript/Python。
|
||
- 表达式错误保留原文本、位置、期望类型和最后有效值。
|
||
|
||
## 5. 技术架构
|
||
|
||
### 5.1 分层结构
|
||
|
||
```text
|
||
React Application Shell
|
||
├─ Command / Shortcut / Dialog / Property UI
|
||
└─ FreeCAD-compatible UI projection
|
||
|
||
BitBybit Web CAD Facade（前端唯一入口）
|
||
├─ App API: Document / Object / Property / Link / Expression
|
||
├─ Gui API: Workbench / Command / Selection / View / Task
|
||
├─ Model API: Feature graph / Body / Sketch / Recompute / Transaction
|
||
├─ Project API: Open / Save / Import / Export / Recovery
|
||
└─ Versioned events, diagnostics, jobs and capabilities
|
||
|
||
BitBybit Internal Runtime（前端不可直接依赖）
|
||
├─ FreeCAD semantic/core WASM modules where source-level reuse is viable
|
||
├─ Geometry Worker: BitBybit OCCT/Manifold/JSCAD WASM and tessellation
|
||
├─ Viewport Adapter: Three.js scene, picking and render cache
|
||
├─ Persistence Worker: SQLite WASM + OPFS VFS
|
||
└─ Optional File/Compression/Script compatibility Workers
|
||
```
|
||
|
||
### 5.2 BitBybit 和 FreeCAD 的职责边界
|
||
|
||
| 能力 | 首选实现 | 说明 |
|
||
|---|---|---|
|
||
| FreeCAD App/Gui 业务合同 | BitBybit Web CAD Facade | 对外公开的唯一 API；方法、事件、状态、错误和版本必须稳定 |
|
||
| Document/Object/Property/Link/Expression | FreeCAD 核心语义模块优先；必要时 TypeScript 等价实现 | 以 FreeCAD 源码/文档和黄金模型验收；前端不得创建第二套语义 |
|
||
| Body/Tip/PartDesign/Sketcher | FreeCAD 对应模块的 WASM 编译或逐项兼容实现 | 先锁定官方版本；无法直接编译的模块必须提供差异报告 |
|
||
| BREP、布尔、拉伸、旋转、圆角、倒角 | BitBybit OCCT WASM 内部适配 | 只能由 Facade 的 Feature/Geometry API 间接调用 |
|
||
| 轻量 CSG 和网格布尔 | BitBybit Manifold/JSCAD 内部适配 | 可用于预览或网格流程，但不能替代精确 BREP 结果 |
|
||
| 拓扑命名、子形状引用 | FreeCAD 语义 + OCCT 拓扑信息 + 稳定引用服务 | 只通过 Facade 返回 SubshapeRef，禁止暴露临时索引 |
|
||
| Workbench/Command/Task/Selection | FreeCAD Gui 行为的 Web 实现 | React 负责显示，命令可用性和生命周期由 Facade 决定 |
|
||
| Three.js 视图 | BitBybit Viewport Adapter 内部实现 | React 只能使用 Facade 的视口挂载、选择和显示命令 |
|
||
| SQLite/OPFS 项目存储 | BitBybit Project API 内部实现 | UI 不直接打开数据库、不持有 OPFS 句柄 |
|
||
| FreeCAD Python API/宏 | 兼容等级单独定义 | 不能以不可信脚本执行作为首版能力；可提供受限兼容层或只读报告 |
|
||
| Qt/Coin3D 桌面实现 | 不直接移植到 UI | React/Three.js 复现外观和交互，业务合同仍由 Facade 定义 |
|
||
|
||
原则是“FreeCAD 语义为规范、BitBybit Facade 为唯一入口、内部实现可替换”。FreeCAD 源码中的 App/Base、非 Qt Feature、Sketcher 求解器和可分离的 Part/PartDesign 核心应优先作为内部 WASM 编译对象；依赖 Qt/Coin3D 的 Gui 层不直接编译到 React，而是从命令、选择、ViewProvider 和任务行为中提取准确合同后在 Web UI 实现。只有在编译体积、Python/Qt 依赖、浏览器线程或许可证不允许时，才采用逐项兼容实现。替代实现必须通过同一 Facade 和 FreeCAD 黄金模型验收，不能由前端自行定义差异。
|
||
|
||
### 5.2.1 BitBybit Facade 的公开能力分组
|
||
|
||
Facade 只公开 FreeCAD 业务所需的稳定能力，不公开底层库类型：
|
||
|
||
| API 分组 | 公开内容 | 禁止泄漏 |
|
||
|---|---|---|
|
||
| `app` | 文档生命周期、对象查询、属性元数据、单位和能力 | FreeCAD C++ 指针、Python 对象、OCCT handle |
|
||
| `gui` | 工作台、命令、菜单/工具栏描述、首选项、面板和视图状态 | Qt Widget、Coin3D 节点、Three.js Object3D |
|
||
| `model` | 创建/编辑特征、Body/Sketch、重计算、事务、错误和诊断 | 内核拓扑临时编号、WASM 堆内存地址 |
|
||
| `selection` | 对象/子形状选择、过滤、预选和拾取确认 | Three.js Raycast 结果作为业务真值 |
|
||
| `task` | TaskSession、草稿、预览、Apply/OK/Cancel、进度和取消 | UI 表单私有状态直接写模型 |
|
||
| `project` | 打开、保存、导入、导出、备份、迁移和恢复 | SQLite Connection、OPFS FileHandle |
|
||
| `viewport` | 视口挂载、相机、显示模式、视图缓存和渲染能力 | Scene Graph 作为持久化模型 |
|
||
|
||
Facade 的所有调用和事件都必须包含 API 版本、Document ID、Document Version、请求 ID、取消信号和结构化诊断。任何新增 FreeCAD 工作台先扩展 Facade 合同，再实现 UI 和内部模块。
|
||
|
||
### 5.3 Worker 和数据交换
|
||
|
||
- 主线程只处理输入、React UI 投影和 BitBybit Facade 事件；不直接向内部 Worker 发消息。
|
||
- Geometry Worker 持有 FreeCAD/OCCT 等内部 WASM 模块、内核对象句柄和重计算上下文，由 Facade 调度。
|
||
- Persistence Worker 独占 SQLite 连接和 OPFS 文件句柄，只接受 BitBybit Project API 的内部请求。
|
||
- Facade 到 Worker 使用版本化内部消息协议，包含 `requestId`、文档版本、取消标记、进度、诊断和错误分类；该协议不成为 UI 公共 API。
|
||
- 小数据使用结构化克隆；大网格使用 Transferable ArrayBuffer；避免跨线程复制完整 BREP。
|
||
- 句柄生命周期必须显式释放，页面关闭、文档关闭和异常恢复都要清理 WASM 内存。
|
||
- SharedArrayBuffer/多线程 WASM 仅作为可选加速项，启用时要求 COOP/COEP 和跨源资源审计。
|
||
|
||
### 5.4 Three.js 渲染策略
|
||
|
||
- Three.js 由 BitBybit Viewport Adapter 创建和管理；React 只通过 Facade 挂载 viewport host 和提交 FreeCAD View 命令。
|
||
- 首发基线为 WebGL2；探测到 WebGPU 时允许切换并保留一致的材质、选择和拾取协议。
|
||
- BREP 结果先在 Geometry Worker 中三角化，再以 BufferGeometry 更新场景。
|
||
- 每个对象维护显示实体、选择实体、边线实体和可选的透明/剖切实体。
|
||
- 使用层级包围盒、视锥裁剪、实例化和 LOD 控制大型装配的绘制量。
|
||
- 拾取结果由 Viewport Adapter 转换为对象 UUID + 稳定子形状引用，再经 Facade Selection API 确认后返回 UI。
|
||
- 相机、灯光、背景和显示模式属于文档视图状态，不混入几何参数。
|
||
|
||
### 5.5 SQLite WASM + OPFS 存储策略
|
||
|
||
以下是 BitBybit Project API 的内部实现设计。前端只能看到项目、文档、保存状态、进度和结构化错误，不得直接执行 SQL 或访问 OPFS。
|
||
|
||
#### 数据分层
|
||
|
||
- SQLite：项目、文档、对象、属性、特征输入、依赖图、事务日志、版本、单位、视图状态和索引。
|
||
- OPFS 资源目录：BREP 快照、三角网格缓存、缩略图、导入原文件、附件和导出包临时文件。
|
||
- SQLite 只保存资源元数据、相对逻辑路径、大小、哈希、格式和引用计数；大文件不默认以内联 Blob 保存。
|
||
|
||
#### 逻辑表
|
||
|
||
| 表/集合 | 关键字段 | 用途 |
|
||
|---|---|---|
|
||
| projects | id, name, schema_version, created_at, updated_at | 项目级元数据 |
|
||
| documents | id, project_id, label, unit_system, active_object_id | 文档 |
|
||
| objects | id, document_id, type, label, parent_id, state | 对象树 |
|
||
| properties | object_id, name, value_json, unit, editor_type | 参数属性 |
|
||
| feature_inputs | feature_id, slot, target_id, subshape_ref | 特征输入引用 |
|
||
| dependencies | source_id, target_id, relation | 依赖图和拓扑排序 |
|
||
| shape_assets | object_id, asset_kind, opfs_path, sha256, bbox_json | BREP/网格缓存 |
|
||
| transactions | id, document_id, command_json, inverse_json, timestamp | 撤销、恢复和审计 |
|
||
| migrations | version, applied_at, checksum | 模式迁移 |
|
||
|
||
#### 并发与恢复
|
||
|
||
- 一个标签页的 Persistence Worker 作为写者；其他标签页通过 BroadcastChannel 接收变更通知。
|
||
- 写入采用短事务和幂等命令；几何计算完成后才提交对应 Shape 资产引用。
|
||
- 启动时执行数据库完整性检查、孤立资源扫描和未完成事务恢复。
|
||
- 关闭标签页、浏览器配额不足或 OPFS 不可用时提示并允许导出备份。
|
||
- 数据库版本、项目格式版本和几何内核版本分开管理。
|
||
|
||
#### 兼容性降级
|
||
|
||
- 首选 SQLite OPFS VFS；无法使用时评估 `opfs-sahpool` 或 WASMFS 方案。
|
||
- 若浏览器不支持目标 OPFS 能力，降级为显式下载/上传项目包，不伪装成可靠自动保存。
|
||
- 应用启动页展示存储能力检测结果和数据风险提示。
|
||
|
||
## 6. 用户体验与界面需求
|
||
|
||
### 6.1 设计基线：FreeCAD 的 Web 化适配
|
||
|
||
界面以锁定版本的 FreeCAD 官方桌面界面为功能基线，而不是一般的“3D 展示器”，也不是只借用视觉风格：
|
||
|
||
- 完整保留 Menu → Workbench → Command → Task Panel 的命令组织关系；Core 1 先启用 Start、Part、Part Design、Sketcher 和 Inspection，后续批次按第 3.5 节补齐官方工作台。
|
||
- 保留 Model/Tasks 两种上下文：Model 查看文档对象；Tasks 完成当前命令。
|
||
- 保留 Data/View 两类属性：Data 改变业务对象和几何；View 只改变显示。
|
||
- 保留文档标签和活动文档概念；多个文档可打开但只有一个活动文档接收命令。
|
||
- 保留选择驱动命令和命令驱动拾取两种方式。
|
||
- 保留状态栏、进度、报告/消息视图和参数重算反馈。
|
||
|
||
Web 化改进包括命令搜索、非阻塞重计算、自动保存、清晰错误恢复、面板布局持久化和浏览器能力提示。改进不得改变 FreeCAD 对象、属性、命令或任务结果的业务含义。FreeCAD 熟悉用户应该能按原有步骤完成相同任务；Qt 特有的窗口细节可以适配，但所有差异必须进入兼容矩阵。
|
||
|
||
### 6.1.1 界面准确性基线
|
||
|
||
每个目标 FreeCAD 版本建立机器可读的 UI 清单：
|
||
|
||
- 全局菜单：File、Edit、View、Tools、Macro/Script、Windows、Help，以及每个工作台注入的菜单。
|
||
- 全局和工作台工具栏：命令 ID、顺序、分组、图标、tooltip、快捷键和选择前置条件。
|
||
- Dock/Panel：Combo View、Tree View、Property Editor、Selection View、Report View、任务面板和状态栏。
|
||
- 对话框/任务：字段、单位、默认值、可见条件、Apply/OK/Cancel、预览、校验和错误。
|
||
- 对象属性：对象类型、Data/View 分组、显示名称、编辑器、只读/隐藏标志和默认值。
|
||
- 视图交互：导航模式、选择、预选、框选、标准视图、显示模式、剖切和测量。
|
||
|
||
UI 兼容验收分三类：
|
||
|
||
| 类型 | 要求 |
|
||
|---|---|
|
||
| 结构准确 | 相同命令位于相同工作台/菜单语义和任务阶段，允许针对 Web 调整像素和 Dock 方式 |
|
||
| 行为准确 | 相同选择、参数和操作顺序产生相同对象类型、属性、依赖、Shape 或同类错误 |
|
||
| 状态准确 | 命令启用、任务锁定、touched/recompute、Tip、可见性、撤销和保存标志一致 |
|
||
|
||
每个界面差异必须标记为浏览器限制、产品改进、尚未实现或 FreeCAD 版本差异，不能以“Web 优化”为理由无记录地删除行为。
|
||
|
||
### 6.1.2 页面设计先行原则
|
||
|
||
本项目采用“两阶段交付”：
|
||
|
||
1. **页面设计阶段**：只完成页面信息架构、静态视觉、交互原型、状态样式、模拟数据、FreeCAD 对照和设计验收；不接入 BitBybit 几何运算、真实 SQLite、OPFS、WASM 或远程服务。
|
||
2. **功能衔接阶段**：页面结构和交互冻结后，按同一页面清单逐项接入 BitBybit Facade、FreeCAD-compatible 业务模型、Three.js Viewport、Worker 和 Project API。
|
||
|
||
页面设计阶段可以使用静态假数据模拟对象树、属性、命令状态、进度、错误和任务预览，但模拟数据必须遵循 FreeCAD 对象/属性/状态结构，不能先设计一套与真实业务不兼容的表单。
|
||
|
||
页面验收顺序固定为：
|
||
|
||
`FreeCAD 页面/工作台清单 → 信息架构 → 页面线框 → 视觉稿 → 静态交互原型 → FreeCAD 行为审查 → 页面冻结 → BitBybit 功能接入`
|
||
|
||
页面设计冻结后，新增页面、删除页面、改变主要工作流或改变任务面板字段必须形成变更记录，并同步更新 FreeCAD UI manifest、Facade 合同和任务分解。
|
||
|
||
### 6.1.3 全部前端页面与视图清单
|
||
|
||
页面分为应用级页面、CAD 工作区页面、工作台视图、任务/对话框和系统辅助页面。CAD 工作区内的工作台不是独立浏览器路由，而是同一 FreeCAD 工作区中的上下文视图；这样保留 FreeCAD 的文档标签和工作台切换心智。
|
||
|
||
#### 应用级页面
|
||
|
||
| 页面 ID | 页面 | FreeCAD 对应 | 页面职责 | 首版设计交付 |
|
||
|---|---|---|---|---|
|
||
| PAGE-APP-01 | 启动/欢迎页 | Start page | 新建、打开、最近项目、示例、导入、能力检测 | 桌面/窄屏、空数据、最近项目、存储不可用 |
|
||
| PAGE-APP-02 | 项目管理页 | Open/Save/New document | 项目搜索、排序、复制、重命名、删除、备份和恢复 | 列表、网格、选择批量、删除确认、配额警告 |
|
||
| PAGE-APP-03 | 文件导入向导 | Import dialog | 文件选择、格式识别、单位、对象映射和警告 | 选择、解析中、映射预览、部分失败、取消 |
|
||
| PAGE-APP-04 | 文件导出向导 | Export dialog | 格式、单位、精度、范围、材质和导出位置 | 参数、进度、完成、失败、再次导出 |
|
||
| PAGE-APP-05 | 备份/恢复页 | Recovery/Save As | 自动保存记录、损坏项目、快照比较和恢复 | 快照列表、差异、恢复前确认、恢复失败 |
|
||
| PAGE-APP-06 | 分享/只读查看页 | Read-only document | 无编辑权限的模型浏览、测量、下载和兼容性说明 | 加载、只读工具栏、权限提示、下载 |
|
||
| PAGE-APP-07 | 账号/同步中心（可选） | User/Cloud services | 登录、设备、同步状态、冲突、团队权限和退出 | 未登录、同步中、冲突、离线、权限不足 |
|
||
|
||
#### CAD 工作区页面
|
||
|
||
| 页面 ID | 页面 | FreeCAD 对应 | 页面职责 | 首版设计交付 |
|
||
|---|---|---|---|---|
|
||
| PAGE-CAD-01 | 默认建模工作区 | Main window + Combo View | 菜单、工作台、文档标签、模型树、视口、属性和底部报告 | 默认空文档、已有模型、多个文档、只读、错误 |
|
||
| PAGE-CAD-02 | 模型树视图 | Model/Tree view | Document、Part、Body、Origin、Feature、代理对象和状态 | 万级节点、搜索过滤、依赖徽标、拖放预演 |
|
||
| PAGE-CAD-03 | 任务面板视图 | Tasks tab/Task panel | 当前命令步骤、参数、选择槽、预览、Apply/OK/Cancel | 无任务、输入中、预览中、警告、失败、取消 |
|
||
| PAGE-CAD-04 | Data 属性视图 | Property editor/Data tab | 对象业务属性、单位、表达式、链接和只读输出 | 单选、多选、mixed、搜索、表达式、无效值 |
|
||
| PAGE-CAD-05 | View 属性视图 | Property editor/View tab | 颜色、透明度、线宽、显示模式、可见性和视图参数 | 单选、多选、默认值、继承、重置 |
|
||
| PAGE-CAD-06 | 报告/作业/诊断抽屉 | Report view/Jobs | 重计算、导入导出、保存、内核错误、性能和恢复建议 | 折叠、过滤、聚合、定位对象、导出诊断 |
|
||
| PAGE-CAD-07 | 选择与测量覆盖层 | Selection view/Measure | 选中对象、子形状、测量结果、坐标和选择过滤 | 预选、正式选择、多选、锁定、测量失败 |
|
||
|
||
#### 工作台页面/视图
|
||
|
||
| 页面 ID | 工作台 | FreeCAD 业务功能 | 页面必须设计的区域 |
|
||
|---|---|---|---|
|
||
| PAGE-WB-01 | Start | 新建、打开、示例、入门 | 欢迎内容、最近项目、模板、能力和版本状态 |
|
||
| PAGE-WB-02 | Part | 基本体、布尔、变换、检查、测量、导入导出 | Part 工具栏、任务面板、选择提示、对象属性 |
|
||
| PAGE-WB-03 | Part Design | Body、Sketch、Pad、Pocket、dress-up、Pattern、Hole | Body 上下文、特征命令、Tip 状态、任务参数 |
|
||
| PAGE-WB-04 | Sketcher | 草图、约束、尺寸、外部几何、求解 | 二维画布、几何工具栏、约束工具栏、求解器状态 |
|
||
| PAGE-WB-05 | Draft | 工作平面、捕捉、二维对象、标注、阵列 | Draft 工具栏、捕捉设置、任务面板、对象属性 |
|
||
| PAGE-WB-06 | TechDraw | 页面、模板、投影、剖视、尺寸和标注 | 页面画布、视图树、模板/页面属性、标注面板 |
|
||
| PAGE-WB-07 | Spreadsheet | 单元格、别名、表达式、模型属性引用 | 表格网格、公式栏、别名面板、引用高亮 |
|
||
| PAGE-WB-08 | Mesh | 导入、网格检查、修复、简化、转换和导出 | 网格统计、修复任务、显示模式、质量报告 |
|
||
| PAGE-WB-09 | Assembly | 实例、装配树、约束、求解、碰撞和爆炸图 | 装配树、约束面板、实例属性、碰撞结果 |
|
||
| PAGE-WB-10 | Path/CAM | Job、工具、操作、刀路、模拟和后处理 | Job 树、刀具/材料、刀路预览、G-code 状态 |
|
||
| PAGE-WB-11 | FEM | Analysis、材料、边界、网格、求解和结果 | Analysis 树、材料/约束面板、求解作业、结果图例 |
|
||
| PAGE-WB-12 | Arch/BIM | IFC/BIM 对象、墙、结构、空间、材料和层级 | BIM 树、对象属性、空间关系、IFC 映射状态 |
|
||
| PAGE-WB-13 | Robot | 机器人、轨迹、关节和仿真 | 机器人树、轨迹面板、关节状态、动画时间轴 |
|
||
| PAGE-WB-14 | Raytracing/Rendering | 材质、灯光、相机和渲染任务 | 渲染设置、材质/灯光属性、渲染队列、结果预览 |
|
||
|
||
#### 系统页面、对话框和覆盖层
|
||
|
||
| 页面 ID | 页面/覆盖层 | FreeCAD 对应 | 页面职责 |
|
||
|---|---|---|---|
|
||
| PAGE-SYS-01 | 首选项页 | Preferences | 常规、单位、导航、显示、颜色、缓存、存储、快捷键和工作台设置 |
|
||
| PAGE-SYS-02 | 工作台/插件管理页 | Addon Manager/Workbench selector | 官方工作台状态、版本、依赖、权限和安装/禁用说明 |
|
||
| PAGE-SYS-03 | 命令搜索面板 | Menu/Command search | 按命令 ID、名称、工作台和快捷键搜索，显示启用原因 |
|
||
| PAGE-SYS-04 | 依赖影响对话框 | Delete/Link handling | 删除、替换、重排和跨文档链接的影响确认 |
|
||
| PAGE-SYS-05 | 重计算错误面板 | Report/Task error | 对象、输入、原因、建议动作、上一次有效结果和诊断 |
|
||
| PAGE-SYS-06 | 存储/配额错误页 | Save/Recovery error | OPFS/SQLite 不可用、配额不足、迁移失败和备份动作 |
|
||
| PAGE-SYS-07 | 帮助与快捷键页 | Help/Keyboard shortcuts | 工作台帮助、命令说明、导航、版本和兼容差异 |
|
||
| PAGE-SYS-08 | 关于/许可证页 | About FreeCAD | BitBybit、FreeCAD、OCCT、WASM、第三方许可证和版本信息 |
|
||
| PAGE-SYS-09 | 版本迁移/兼容检查页 | Document migration | 项目格式、FreeCAD 基线、内核版本、对象差异和迁移结果 |
|
||
| PAGE-SYS-10 | 隐私/安全设置页 | Preferences/Security | 本地数据、网络、诊断、脚本权限、插件权限和清除数据 |
|
||
|
||
#### 应用路由与工作区内部视图
|
||
|
||
| 路径/入口 | 页面或视图 | 说明 |
|
||
|---|---|---|
|
||
| `/start` | PAGE-APP-01 | 默认启动入口，不依赖网络或账号 |
|
||
| `/projects` | PAGE-APP-02 | 项目管理和最近项目 |
|
||
| `/import` | PAGE-APP-03 | 文件导入向导，可从启动页或工作区调用 |
|
||
| `/export` | PAGE-APP-04 | 文件导出向导，保持当前文档上下文 |
|
||
| `/recovery` | PAGE-APP-05 | 自动保存、迁移和损坏项目恢复 |
|
||
| `/share/:shareId` | PAGE-APP-06 | 只读分享入口，不暴露内部文档 ID |
|
||
| `/sync` | PAGE-APP-07 | 可选账号、云同步和团队功能 |
|
||
| `/workspace/:projectId` | PAGE-CAD-01 | FreeCAD 风格主工作区；文档以标签页打开 |
|
||
| `workbench` context | PAGE-WB-01 至 PAGE-WB-14 | 工作台是 BitBybit Gui Facade 的上下文，不创建独立业务真值 |
|
||
| `task` overlay | PAGE-CAD-03、PAGE-SYS-04 至 PAGE-SYS-06 | 任务和错误覆盖层绑定当前 Document/TaskSession |
|
||
| `/settings/*` | PAGE-SYS-01、PAGE-SYS-10 | 首选项、导航、单位、隐私和安全 |
|
||
| `/plugins` | PAGE-SYS-02 | 工作台/插件管理 |
|
||
| `/help`、`/shortcuts` | PAGE-SYS-07 | 帮助和快捷键 |
|
||
| `/diagnostics`、`/about` | PAGE-CAD-06、PAGE-SYS-08 | 诊断、版本、许可证和构建信息 |
|
||
|
||
上述页面是设计范围，不代表所有页面首版都具备真实业务功能。页面设计阶段必须先交付全部页面的静态状态，功能衔接阶段再按工作台和风险排序接入。
|
||
|
||
### 6.1.4 页面状态矩阵
|
||
|
||
每一个 PAGE 项目至少设计以下状态，不能只设计“正常有数据”页面：
|
||
|
||
| 状态组 | 具体状态 | 必须体现的内容 |
|
||
|---|---|---|
|
||
| 生命周期 | 首次进入、加载、恢复、关闭中 | 骨架、进度、取消、不可用区域和数据安全提示 |
|
||
| 数据 | 空项目、单对象、多对象、大模型、只读 | 空状态引导、层级密度、权限、性能模式 |
|
||
| 操作 | 可用、禁用、进行中、预览、Apply、OK、Cancel | 命令前置、任务步骤、取消结果和保存标志 |
|
||
| 计算 | 排队、重计算、成功、警告、失败、已取消、过期 | 进度、对象定位、旧结果、诊断和恢复动作 |
|
||
| 存储 | 已保存、未保存、自动保存、保存失败、配额不足、迁移中 | 明确状态、备份入口、不可丢数据提示 |
|
||
| 兼容 | exact、compatible、read-only、proxy、unsupported | 来源版本、差异、可编辑范围和导出影响 |
|
||
| 设备 | 桌面宽屏、桌面窄屏、触摸板、键盘操作 | 面板折叠、控件尺寸、焦点和导航方式 |
|
||
|
||
### 6.1.5 页面与业务衔接规则
|
||
|
||
页面设计阶段的假数据字段必须直接对应 BitBybit Facade 的未来投影：
|
||
|
||
- 模型树页面使用 `Document/Object/Container/Feature` 的层级和状态字段。
|
||
- Data/View 属性页面使用 FreeCAD-compatible Property metadata，不在页面里硬编码业务校验。
|
||
- 工作台页面使用 `WorkbenchDefinition` 和 `CommandDefinition` 的命令列表、图标、快捷键、选择谓词和启用原因。
|
||
- Task 页面使用 `TaskSession` 草稿、预览、诊断、进度和确认动作。
|
||
- 报告/作业/诊断页面使用 Facade 事件中的 Job、Diagnostic、Document Version 和 request ID。
|
||
- 视口页面只展示 Facade 返回的 View/Selection 投影，不把 Three.js 对象结构写入页面状态。
|
||
|
||
每个页面设计卡片必须标注“未来衔接的 Facade API 分组”和“暂不接入的功能”，确保设计与后续实现一一对应。
|
||
|
||
### 6.2 工作区布局
|
||
|
||
```text
|
||
┌──────────────────────────────────────────────────────────────────────────┐
|
||
│ App/Menu │ Document │ Undo/Redo │ Workbench │ Command Search │ Save State │
|
||
├───────────────┬─────────────────────────────────────┬────────────────────┤
|
||
│ Model | Tasks │ Document Tabs │ Data | View │
|
||
│ ├─────────────────────────────────────┤ Property Editor │
|
||
│ Model Tree / │ │ │
|
||
│ Active Task │ Three.js Viewport │ │
|
||
│ │ │ │
|
||
│ │ │ │
|
||
├───────────────┴─────────────────────────────────────┴────────────────────┤
|
||
│ Report / Jobs / Diagnostics Status / Units / Progress │
|
||
└──────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
- 顶部应用栏：项目菜单、文档命令、保存状态、全局撤销/重做、工作台切换器、命令搜索、设置和帮助。
|
||
- 工作台工具栏：只显示当前工作台的高频命令；低频命令保留在菜单和命令搜索中。
|
||
- 左侧组合面板：Model 与 Tasks 标签互斥；进入任务会话时自动切到 Tasks，结束后恢复 Model。
|
||
- 中央文档区：多文档标签、Three.js 视口、视图立方体、导航、选择、测量和错误覆盖层。
|
||
- 右侧属性面板：Data 与 View 标签、属性搜索、分组折叠、表达式入口、恢复默认值和多选公共属性。
|
||
- 底部抽屉：Report、Jobs、Diagnostics 可按需展开；常态只保留状态、单位、坐标、选择摘要和进度。
|
||
|
||
固定格式工具控件必须有稳定尺寸，面板可调整宽度但需要最小/最大值；布局按用户保存。首发以宽度 1280px 以上桌面工作区为主要验收目标，较窄窗口折叠右侧属性面板，不承诺手机完成复杂草图编辑。
|
||
|
||
### 6.3 工作台与命令组织
|
||
|
||
| 工作台 | 首发命令组 | 进入条件 |
|
||
|---|---|---|
|
||
| Start | 新建、打开、最近项目、导入、示例 | 始终可用 |
|
||
| Part | 基本体、变换、布尔、测量、导入导出 | 有可写活动文档 |
|
||
| Part Design | Body、Sketch、Pad、Pocket、Revolution、Fillet、Chamfer、Pattern、Hole | 活动文档可写；部分命令要求活动 Body/有效选择 |
|
||
| Sketcher | 几何、约束、尺寸、修剪、外部几何、求解信息 | 活动 TaskSession 为草图编辑 |
|
||
| Inspection | 测量、剖切、几何检查、质量属性 | 有可见 Shape 或选中子形状 |
|
||
|
||
工作台切换只改变可用命令和布局建议，不修改文档对象。正在执行任务时切换工作台需要先结束或挂起 TaskSession。
|
||
|
||
### 6.4 模型树
|
||
|
||
模型树至少支持：
|
||
|
||
- 多文档根、Document、Part、Body、Origin、基准、Sketch、Feature 和代理对象图标。
|
||
- 展开/折叠、键盘导航、搜索、类型/错误/可见性过滤和定位选中对象。
|
||
- 可见性切换、重命名、删除、抑制、重算、设为 Tip、导出和属性定位。
|
||
- 错误、警告、touched、recomputing、suppressed、missing-reference、proxy 和 active task 状态徽标。
|
||
- Body 历史顺序、当前 Tip、活动 Body 和编辑中对象的明确表现。
|
||
- 选择同步：单击选择对象，Ctrl/Cmd 多选，Space 切换可见性，双击进入默认编辑任务。
|
||
- 拖放只用于业务允许的重排/归组；悬停期间预演合法位置，非法放置显示原因。
|
||
- 删除前依赖分析：列出直接依赖、间接依赖和可选处理方式。
|
||
|
||
模型树必须使用虚拟化，保证上万节点仍可滚动；不可因三维重算重建整棵树或丢失展开状态。
|
||
|
||
### 6.5 任务面板
|
||
|
||
任务面板是建模命令的主交互面，结构统一为：
|
||
|
||
- 标题、命令图标、对象/步骤说明和帮助入口。
|
||
- 参数分组、单位输入、选择槽、反向/对称等二元选项和模式选择。
|
||
- 输入校验、几何警告、预览状态、重计算耗时和内核错误摘要。
|
||
- 固定底部动作：Cancel、Apply（命令支持时）、OK；危险操作另行确认。
|
||
|
||
任务面板规则：
|
||
|
||
- 打开时创建草稿对象或临时参数，不立即污染正式历史。
|
||
- 参数变化采用短防抖触发可取消预览；连续滑动时可用粗糙三角化，停止后精细预览。
|
||
- 新预览开始后取消旧请求；只有匹配当前文档版本和 TaskSession 的结果可显示。
|
||
- 无效参数保留用户输入但禁用 OK，展示字段级错误。
|
||
- 选择槽进入拾取模式后，只接受声明类型；拾取完成自动推进到下一个必需输入。
|
||
- 重计算失败时展示可操作建议，不关闭任务面板，也不删除草稿。
|
||
|
||
### 6.6 属性编辑器
|
||
|
||
- Data 标签按属性分组展示领域属性；View 标签展示显示属性。
|
||
- 编辑器由属性元数据生成：数值输入带单位，枚举用下拉菜单，布尔值用复选框/开关，颜色用色板，Placement 用可展开复合编辑器，引用用对象选择器。
|
||
- 支持属性搜索、显示全部/仅修改项、恢复默认值、复制值、粘贴值和表达式切换。
|
||
- 单击选择属性，双击或 Enter 编辑；Esc 取消，Enter 提交。
|
||
- 修改昂贵参数时提供“即时预览/应用后重算”策略；用户偏好可配置，但结果一致。
|
||
- 多选对象时只展示共同可编辑属性；不同值显示 mixed，不得用任一对象值覆盖其他对象。
|
||
- 输出属性、只读属性、代理对象属性显示来源和不可编辑原因。
|
||
- 属性提交后，模型树、视口和状态栏通过领域事件更新，组件间不直接互相调用。
|
||
|
||
### 6.7 三维视口
|
||
|
||
- 鼠标默认准确实现锁定版本的 FreeCAD CAD 导航预设，并可额外提供 Blender/CAD/触控板预设；额外预设不得改变默认行为。
|
||
- 空白单击清除选择，Ctrl/Cmd 增减选择，框选支持从左到右包含和从右到左相交模式。
|
||
- 悬停显示预选；状态栏显示对象、子形状和坐标；右键菜单随选择类型变化。
|
||
- 视图立方体提供前后左右上下、轴测和正交/透视切换；Fit All、Fit Selection 和旋转中心是独立命令。
|
||
- 显示模式包含 Flat Lines、Shaded、Wireframe、Points、透明和隐藏线增强；默认模式以清晰机械 CAD 轮廓为目标。
|
||
- 编辑 Sketch 时切换到草图相机和二维交互层，离开任务后恢复进入前视图状态。
|
||
- 重计算期间保留上一次有效几何并降低不透明度，受影响对象显示忙碌状态；成功后原位更新，不重置相机。
|
||
- WebGL 上下文丢失时重建场景；因为场景不是真值，恢复不得要求用户重新打开项目。
|
||
|
||
### 6.8 文档标签和保存状态
|
||
|
||
- 每个打开文档有标签、修改标记、只读/错误标识和关闭按钮。
|
||
- 切换标签更新活动 Document、Model tree 根、Selection 和命令状态；各文档相机可独立保存。
|
||
- 保存状态区分 `saved`、`unsaved`、`autosaving`、`save-error`、`storage-risk` 和 `read-only`。
|
||
- 关闭未保存文档提供保存、导出副本、放弃、取消；浏览器关闭前尽最大努力提交短事务，但不依赖 `beforeunload` 完成大文件写入。
|
||
- 自动保存失败必须持续可见，并提供立即导出项目包的恢复动作。
|
||
|
||
### 6.9 报告、作业和诊断
|
||
|
||
- Report：面向用户的命令结果、导入警告、保存错误和恢复建议。
|
||
- Jobs：正在运行/排队/已取消的重计算、导入、导出、三角化和清理任务。
|
||
- Diagnostics：面向开发和高级用户的对象 ID、依赖链、内核错误、耗时、内存和版本；默认折叠。
|
||
- 相同错误聚合并计数，避免预览期间刷屏；点击消息可定位对象、属性或任务字段。
|
||
- 诊断包导出前展示包含内容并默认移除项目名称、文件路径和几何数据。
|
||
|
||
### 6.10 关键用户流程
|
||
|
||
#### 新建 Body 并 Pad
|
||
|
||
1. 新建文档，系统创建 Document 和 Origin，保存空快照。
|
||
2. 切换 Part Design，点击 Create Body；模型树标记活动 Body。
|
||
3. 点击 Create Sketch，任务面板要求选择基准面或平面面。
|
||
4. 进入 Sketcher，创建几何和约束；求解状态实时显示自由度。
|
||
5. 关闭草图任务，Sketch 成为 Body Tip；点击 Pad。
|
||
6. Pad 任务面板修改长度并异步预览；OK 后提交一个事务并成为新 Tip。
|
||
7. 自动保存参数树，几何缓存异步写入 OPFS；保存失败不影响当前内存模型，但必须提示。
|
||
|
||
#### 编辑历史特征
|
||
|
||
1. 双击模型树中的 Pad，后续特征进入临时隐藏/预览状态。
|
||
2. 任务面板加载原参数；修改生成可取消预览。
|
||
3. OK 后从 Pad 开始向下增量重算；失败节点显示错误并保留最近有效 Shape。
|
||
4. 用户可继续编辑失败节点、撤销本次修改或检查依赖链。
|
||
|
||
#### 面选择创建 Pocket
|
||
|
||
1. 用户在视口选择实体面，SelectionService 解析稳定 SubshapeRef。
|
||
2. Create Sketch 命令因选择满足“平面面”谓词而启用。
|
||
3. 新 Sketch 保存支持对象和子形状引用；草图坐标系映射到该面。
|
||
4. 上游拓扑变化后引用通过来源和几何签名重新匹配；不确定时要求用户确认，不静默改变支持面。
|
||
|
||
#### 删除被引用对象
|
||
|
||
1. Delete 命令先计算依赖影响，不直接删除。
|
||
2. 对话框列出将失效和将级联删除的对象。
|
||
3. 用户选择级联删除、保留失效对象或取消。
|
||
4. 提交单一事务；撤销恢复对象、链接、Tip 和可见性。
|
||
|
||
### 6.11 关键交互原则
|
||
|
||
- 所有会改变模型的动作走 Command Bus，确保撤销、持久化和审计一致。
|
||
- 属性编辑支持暂存、应用、取消和批量编辑；输入错误不破坏上一次有效值。
|
||
- 重计算期间显示阶段、进度、取消按钮和受影响对象；禁止无反馈地冻结界面。
|
||
- 选择对象和选择子形状使用统一高亮颜色和状态说明。
|
||
- 错误信息包含“对象、特征、输入、可能原因、可尝试动作”，避免只显示 WASM 堆栈。
|
||
- 触摸设备提供最小可用导航，但精确草图编辑首发以鼠标/触控板为主。
|
||
|
||
### 6.12 前端状态边界
|
||
|
||
前端不能使用一个全局 store 混装所有状态，按生命周期拆分：
|
||
|
||
| 状态域 | 真值位置 | React 中保存的内容 |
|
||
|---|---|---|
|
||
| 文档和对象 | BitBybit Facade App/Model | FreeCAD-compatible 只读投影、当前版本和查询结果 |
|
||
| 精确 Shape | BitBybit 内部 Geometry Worker | Facade 返回的摘要、诊断和不透明资源引用 |
|
||
| 渲染场景 | BitBybit Viewport Adapter | React 只持有 viewport host 和公开状态 |
|
||
| 选择 | BitBybit Facade Selection | 当前选择摘要和命令可用性 |
|
||
| 任务会话 | BitBybit Facade Task | FreeCAD-compatible 表单投影、校验和进度 |
|
||
| 面板/主题/偏好 | UI store | 布局、折叠、主题、导航预设 |
|
||
| 保存和后台任务 | BitBybit Facade Project/Jobs | 状态摘要、进度和错误 |
|
||
|
||
所有 Facade 事件必须带 Document ID、Document Version 和来源；React 订阅投影，禁止通过组件副作用触发隐式业务重计算，也禁止绕过 Facade 连接内部 Worker。
|
||
|
||
## 7. 非功能需求
|
||
|
||
### 7.1 性能预算（首发目标）
|
||
|
||
- 首屏 UI 可交互时间：中档桌面设备、缓存命中时不超过 2 秒；冷启动 WASM 加载不超过 8 秒。
|
||
- 简单零件（不超过 20 个特征）重计算：P50 不超过 500 ms，P95 不超过 2 秒。
|
||
- 视口交互在 100 万三角形以内保持 60 FPS 目标；超出后自动启用 LOD/降级显示。
|
||
- UI 主线程长任务不超过 50 ms；几何和持久化不得在主线程同步执行。
|
||
- 首次加载和按需加载分别统计 WASM、JavaScript、纹理和项目数据体积。
|
||
|
||
### 7.2 可靠性和一致性
|
||
|
||
- 同一输入文档、内核版本和参数必须产生可复现的几何结果或同类错误。
|
||
- 自动保存不丢失已提交事务；异常退出后能恢复到最近提交点。
|
||
- 资源引用无泄漏；删除对象后对应缓存可回收但不影响撤销窗口。
|
||
- 导入失败是可诊断的局部错误，不得导致整个项目数据库损坏。
|
||
|
||
### 7.3 安全、隐私和许可证
|
||
|
||
- 默认所有设计数据留在本地；网络请求仅用于可选更新、云同步和用户明确触发的上传。
|
||
- 不执行来自项目文件的任意 Python/JavaScript；插件采用显式权限和沙箱策略。
|
||
- 评估 BitBybit、OCCT、FreeCAD 各模块及其第三方依赖的许可证，形成 NOTICE、源代码提供和动态链接边界清单。
|
||
- 对导入文件进行大小、压缩比、实体数和资源路径校验，防止资源耗尽和路径逃逸。
|
||
- 发布版本提供 WASM 二进制来源、构建参数、版本和 SBOM。
|
||
|
||
### 7.4 浏览器支持
|
||
|
||
首发仅验证 Chrome 的最新两个稳定大版本；明确 WebAssembly、WebGL2、Worker、OPFS 和 File System Access API 的支持差异。其他浏览器测试延期至全部任务完成并收到明确通知。
|
||
|
||
## 8. 文件格式与互操作
|
||
|
||
### 8.1 原生项目格式
|
||
|
||
定义版本化的 `*.webcad` 项目包，建议为 ZIP 容器，包含：
|
||
|
||
- `manifest.json`：格式版本、应用版本、单位、内核版本和校验和。
|
||
- `document.json`：对象、属性、依赖图和事务快照的可移植表示。
|
||
- `assets/`：BREP、网格、缩略图和附件。
|
||
- `preview/`：可直接展示的 GLB/PNG 预览。
|
||
- `compatibility.json`：导入/导出警告和不支持对象报告。
|
||
|
||
SQLite 是运行时的主存储，不要求项目包直接暴露数据库内部结构。导入导出服务负责在数据库和项目包之间转换。
|
||
|
||
### 8.2 FCStd 兼容策略
|
||
|
||
分三档验收：
|
||
|
||
1. A 档：原生创建的简单 Part/PartDesign 文档可导出到 FCStd，并在桌面 FreeCAD 打开后几何和主要参数一致。
|
||
2. B 档：桌面 FreeCAD 创建的基础 Part/PartDesign/Sketcher 文档可导入，无法识别的对象被保留为只读代理或列入报告。
|
||
3. C 档：复杂链接、Python 对象、第三方 Workbench、特殊视图和 GUI 状态只做只读预览或明确不支持。
|
||
|
||
每个互操作版本维护样例文件集、差异报告和已知限制。不能把“能读取 ZIP”当作 FCStd 业务兼容完成。
|
||
|
||
## 9. 分阶段实施步骤
|
||
|
||
### 阶段 UI-0：FreeCAD 全量页面盘点与设计基线（2-3 周）
|
||
|
||
这一阶段只做页面和交互设计，不接入真实业务功能。目标是把锁定版本 FreeCAD 的界面和业务入口完整盘点为可评审的页面资产。
|
||
|
||
- 固定 FreeCAD 版本，采集官方菜单、工作台、工具栏、命令、快捷键、Model/Tasks、属性、任务面板和首选项清单。
|
||
- 以第 6.1.3 节页面目录为基线，为每个页面建立页面 ID、目标用户、入口、退出、数据字段、错误、权限和后续 Facade API 映射。
|
||
- 输出桌面宽屏、桌面窄屏、只读、空状态、加载、错误、禁用和恢复状态的低保真线框。
|
||
- 明确页面之间的导航关系：应用级路由、文档标签、工作台切换、任务覆盖层、设置/帮助/恢复流程。
|
||
- 组织 FreeCAD 用户评审，记录“结构差异、行为差异、浏览器适配、暂不支持”四类问题。
|
||
|
||
交付物：全量页面地图、FreeCAD UI manifest、页面卡片、导航图、状态矩阵、术语表、首轮差异记录。
|
||
|
||
### 阶段 UI-1：Web CAD 视觉系统和组件规范（3-5 周）
|
||
|
||
- 设计 FreeCAD 对标的菜单、工具栏、工作台切换、Combo View、Property Editor、Task Panel、状态栏、报告抽屉和文档标签组件。
|
||
- 定义颜色、间距、字体、图标、边框、密度、选中/预选/错误/警告/计算状态、禁用状态和焦点规范。
|
||
- 定义 Data/View 属性编辑器、单位输入、枚举、链接选择器、Placement、颜色、表达式和多选 mixed 状态。
|
||
- 定义 Three.js 视口外围控件：标准视图、导航、视图立方体、显示模式、剖切、测量、选择过滤和状态覆盖层。
|
||
- 定义桌面宽屏、窄窗口、触摸板、键盘和高对比度的布局规则。
|
||
|
||
交付物：设计 Token、组件状态表、图标/命令清单、无障碍规范、响应式断点、组件用例和视觉回归基线。
|
||
|
||
### 阶段 UI-2：全量静态页面和工作台原型（6-10 周）
|
||
|
||
- 按第 6.1.3 节完成 PAGE-APP、PAGE-CAD、PAGE-WB 和 PAGE-SYS 的所有静态页面。
|
||
- 使用遵循 FreeCAD 对象/属性结构的模拟数据展示空项目、基础零件、Body 历史、Sketch 约束、TechDraw 页面、Spreadsheet、Assembly、FEM 等工作台。
|
||
- 为每个命令制作打开、填写、预览、警告、失败、Apply、OK、Cancel 和恢复的静态任务面板流程。
|
||
- 制作模型树万级节点、错误节点、代理对象、缺失引用、多选属性和存储故障的高密度页面。
|
||
- 完成命令搜索、首选项、插件/工作台管理、帮助、快捷键、诊断和关于/许可证页面。
|
||
|
||
交付物：可点击静态原型、全部页面截图、交互录屏、页面状态覆盖表、FreeCAD 对照审查报告。
|
||
|
||
### 阶段 UI-3：页面冻结和功能衔接合同（2-4 周）
|
||
|
||
- 对页面、组件、模拟字段、事件、错误和状态逐项映射 BitBybit Facade App/Gui/Model/Selection/Task/Project/Viewport 分组。
|
||
- 为每个页面建立“设计字段 → Facade 字段 → 后续任务 ID → 验收场景”的追踪关系。
|
||
- 冻结页面结构、主要工作流和状态名称；将真实功能接入列入阶段 0-11，不在静态设计中提前实现。
|
||
- 建立页面依赖守卫和模拟数据契约，确保后续接入真实 Facade 不改变页面结构和 FreeCAD 业务含义。
|
||
|
||
交付物：页面到 Facade 映射表、功能衔接 backlog、页面冻结记录、差异关闭清单和接入验收模板。
|
||
|
||
### 阶段 0：需求冻结与可行性 POC（2-4 周）
|
||
|
||
目标是固定 FreeCAD 基线版本、生成完整兼容清单，并回答四个高风险问题：FreeCAD App/Sketcher/选定模块的 WASM 可编译边界、BitBybit 唯一入口协议是否覆盖全部前端需求、OCCT WASM 的真实体积和性能、SQLite+OPFS 在目标浏览器中的可靠性。
|
||
|
||
交付物：
|
||
|
||
- 需求基线、术语表、兼容性矩阵和许可证清单。
|
||
- FreeCAD UI/业务清单：命令、工作台、对象、属性、任务、选择前置和黄金模型。
|
||
- FreeCAD App/Sketcher 源码依赖图和 Emscripten/WASM 编译 POC；记录 Qt、Python 和系统库阻塞点。
|
||
- BitBybit Facade POC：React 只经 Facade 完成 Box、Pad、Boolean、Fillet、STEP 导入导出、三角化、保存和恢复。
|
||
- Facade 内部 Worker POC：几何/存储、取消、Transferable、错误回传和内存释放；前端不得直接发 Worker 消息。
|
||
- BitBybit Project API POC：内部 SQLite WASM + OPFS 创建数据库、事务、重启恢复、配额和跨标签页通知。
|
||
- BitBybit Viewport API POC：内部 Three.js 显示、对象/子形状拾取和 100 万三角形基准。
|
||
- 决策记录：Sketch 求解器、WebGPU、SharedArrayBuffer、FCStd 兼容方式。
|
||
|
||
退出条件：所有 POC 在目标浏览器运行；性能和内存数据可复现；FreeCAD 源码复用与等价适配边界已逐模块记录；依赖图证明 React 前端只有 BitBybit Facade 一个 CAD 入口。
|
||
|
||
### 阶段 1：工程骨架与协议（2-3 周）
|
||
|
||
- 建立 monorepo、TypeScript 配置、构建产物分层和版本策略。
|
||
- 定义 BitBybit Facade 的 App/Gui/Model/Selection/Task/Project/Viewport 公开合同、版本和弃用策略。
|
||
- 定义领域 ID、单位、错误、诊断、Facade 事件、内部 Worker 消息和项目格式版本。
|
||
- 建立 React 应用壳、Facade Provider、视口 host、内部 Worker 生命周期和日志/遥测接口。
|
||
- 建立架构检查，禁止前端业务包直接依赖 FreeCAD/OCCT/Three.js/SQLite/OPFS 和内部 Worker 协议。
|
||
- 建立 CI：类型检查、单元测试、WASM 资源校验、许可证扫描和浏览器烟测。
|
||
|
||
### 阶段 2：BitBybit 内部 FreeCAD/几何运行时（4-8 周）
|
||
|
||
- 将可复用的 FreeCAD App/Base/Sketcher/Part 业务核心按 POC 结论编译为内部 WASM 模块；阻塞模块建立兼容实现和差异测试。
|
||
- 将 BitBybit OCCT/Manifold/JSCAD 封装为 Facade 内部 Kernel Adapter。
|
||
- 实现 primitives、变换、布尔、拉伸/旋转、圆角/倒角、拓扑查询和三角化。
|
||
- 定义 ShapeHandle、MeshAsset、SubshapeRef 和诊断模型。
|
||
- 建立内核基准、容差策略、取消/超时和资源释放。
|
||
- 形成 FreeCAD/BitBybit 能力矩阵，所有未支持或非 exact 操作返回结构化兼容等级和错误。
|
||
|
||
### 阶段 3：FreeCAD-compatible 文档和特征系统（6-10 周）
|
||
|
||
- 实现 Document/Object/Container/Feature/Shape 基础模型。
|
||
- 实现属性类型、编辑器元数据、依赖图、拓扑排序和增量重计算。
|
||
- 实现 Command Bus、事务、撤销/重做、保存点和错误节点。
|
||
- 实现 Body、Tip、特征可见性和单一实体规则。
|
||
- 通过 BitBybit App/Gui/Model API 暴露全部行为；React 不引用内部领域实现。
|
||
- 用同一组桌面 FreeCAD 黄金文档验证对象、属性、结果、错误和撤销行为。
|
||
|
||
### 阶段 4：Sketch 和 PartDesign MVP（8-12 周）
|
||
|
||
- 草图编辑器：网格、吸附、几何创建、约束列表、尺寸编辑和求解状态。
|
||
- 先完成固定数量的核心约束，再扩展到切线、平行、对称、等距、参考约束。
|
||
- 实现 Pad、Pocket、Revolution、Fillet、Chamfer、Boolean、Pattern 和 Hole。
|
||
- 加入特征重排、抑制、重命名、替换输入和错误恢复。
|
||
- 通过黄金模型和桌面 FreeCAD 对比测试校验几何与参数语义。
|
||
|
||
### 阶段 5：BitBybit Viewport/Three.js 和 FreeCAD Gui 交互（并行 4-6 周）
|
||
|
||
- 场景图、材质、边线、剖切、选择、预选、相机和导航。
|
||
- 几何结果到 BufferGeometry 的增量更新和缓存淘汰。
|
||
- 面/边/点拾取到 SubshapeRef 的反查。
|
||
- 大模型性能模式、LOD、实例化和视图状态持久化。
|
||
- WebGL2 基线完成后再接入 WebGPU 实验通道。
|
||
- React 只消费 BitBybit Gui/Selection/Viewport API；建立依赖测试防止 Three.js 类型泄漏。
|
||
|
||
### 阶段 6：BitBybit Project API 与 SQLite/OPFS（4-6 周）
|
||
|
||
- BitBybit Project API、内部 Persistence Worker 和 repository adapter。
|
||
- 数据库模式、迁移、事务日志、索引、完整性检查和恢复。
|
||
- OPFS 资源管理器、哈希、引用计数、垃圾回收和配额处理。
|
||
- 自动保存、项目包导入导出、崩溃恢复和跨标签页通知。
|
||
- 浏览器能力降级和备份/恢复演练。
|
||
- 架构测试确认 UI 不能访问 SQL、数据库连接或 OPFS 句柄。
|
||
|
||
### 阶段 7：文件互操作（4-8 周）
|
||
|
||
- STEP/IGES/STL/OBJ/GLB 的导入导出流水线。
|
||
- FCStd A 档兼容：解析、映射、警告和样例回归。
|
||
- FCStd B/C 档可行性研究；对不支持对象生成代理和报告。
|
||
- 大文件导入的进度、取消、限额和错误恢复。
|
||
|
||
### 阶段 8：质量、可观测性和发布（4-6 周）
|
||
|
||
- 单元、属性基于模型、内核黄金样例、跨浏览器、视觉回归和端到端测试。
|
||
- 性能基准自动化、WASM 崩溃报告、用户可选诊断包和匿名指标。
|
||
- PWA、静态资源缓存、版本回滚、数据迁移和发布检查单。
|
||
- 文档、帮助中心、示例项目、兼容性说明和安全响应流程。
|
||
|
||
### 阶段 9：FreeCAD Core 2 工作台覆盖（6-12 个月）
|
||
|
||
- Draft：工作平面、捕捉、2D 对象、标注、转换和 FreeCAD 属性一致性。
|
||
- TechDraw：页面、模板、投影、剖视、尺寸、标注和 PDF/SVG 输出。
|
||
- Spreadsheet：表格、别名、表达式、模型属性引用和重计算联动。
|
||
- Mesh：导入、分析、修复、转换、显示和导出。
|
||
- Assembly：零件实例、装配树、约束、求解、碰撞和对象链接。
|
||
- 对每个工作台生成菜单/命令/任务/属性清单，经 BitBybit Facade 暴露并执行桌面 FreeCAD 对照测试。
|
||
|
||
### 阶段 10：FreeCAD Core 3 工程工作台覆盖（12-24 个月）
|
||
|
||
- Path/CAM：Job、Tool、Operation、Path、Post Processor 和 G-code 兼容等级。
|
||
- FEM：Analysis、Material、Constraint、Mesh、Solver、Result 对象和外部求解器策略。
|
||
- Arch/BIM：对象类型、IFC 属性、层级、材料、空间、结构和导入导出。
|
||
- Robot、Raytracing/Rendering 及基线版本中的其他官方模块。
|
||
- 对无法在浏览器本地运行的求解器，通过 BitBybit Facade 使用可选服务端执行；前端入口保持不变。
|
||
|
||
### 阶段 11：FreeCAD 脚本和 Addon 兼容（独立项目）
|
||
|
||
- 固定需要兼容的 FreeCAD Python API 子集和安全模型。
|
||
- 评估 Python WASM、受限解释器、RPC 到受控 FreeCAD Worker/服务端三种路线。
|
||
- 项目文件中的脚本默认不自动执行；显示来源、权限和将访问的数据。
|
||
- 官方/第三方 Addon 逐个建立 manifest、依赖、API 等级、UI 扩展点和沙箱策略。
|
||
- “完整官方核心”与“兼容任意第三方 Addon”分别验收，后者不能作为默认承诺。
|
||
|
||
阶段时长是日历周估算，不是简单相加的人周。UI-0 至 UI-3 必须先于真实功能接入；阶段 2、5、6 可并行，阶段 4 和 7 的深度受 POC 结论影响；阶段 9-11 是实现“完整 FreeCAD 官方核心覆盖”不可省略的后续计划。以需求、交互和技术决策已能及时确认作为前提，建议采用以下排期口径：
|
||
|
||
当前 P0 实证：FreeCAD `1.1.1` 精确提交已由脚本获取并完成无界面 Part 原生构建，Box/Cylinder/Sphere/Cone/Cut 五个声明式黄金场景通过 `FreeCADCmd` 回放。完整命令见 `docs/freecad-baseline-and-golden.zh-CN.md`，Node/npm 操作统一使用 `./npmw`。该证据尚未覆盖 digest 锁定容器、GUI、完整工作台、100 个成功样例和 50 个错误样例，因此只计为 P0-01/P0-03 进行中。
|
||
|
||
| 交付层级 | 建议团队 | 预计周期 | 范围 |
|
||
|---|---:|---:|---|
|
||
| 全量前端页面设计 | 4-6 人 | 13-22 个日历周 | FreeCAD 页面盘点、设计系统、全部工作台静态页面、状态、原型和 Facade 映射 |
|
||
| 可行性 + 垂直切片 | 4-6 人 | 10-16 个日历周 | Box/Sketch/Pad/Pocket/Fillet、显示、选择、保存、STEP/项目包 |
|
||
| PartDesign MVP | 6-8 人 | 9-13 个月 | 第 3.1 节范围、基础 FCStd 兼容、跨浏览器和离线可靠性 |
|
||
| 可生产使用的 V1 | 8-12 人 | 12-18 个月 | 性能、安全、迁移、更多互操作、文档和发布运营 |
|
||
| 接近 FreeCAD 广度的平台 | 多团队 | 24-36 个月以上 | Assembly、TechDraw、插件、协作及选定的工程工作台 |
|
||
|
||
以上为量级估算，不是承诺日期。Sketch 求解器、稳定拓扑命名、FCStd 高兼容、Assembly 和多人协作都应独立估算；任何一个都可能形成数月级工作流。
|
||
|
||
### 9.1 关键路径与并行关系
|
||
|
||
关键路径为：A1/A2/A6 需求、FreeCAD 版本和语义冻结 → UI-0/UI-1/UI-2/UI-3 全量页面设计与 Facade 映射 → B1/B2/B3 内核与 Facade 验证 → B4-B6 几何能力 → C1/C2/C7 文档属性 → C3/C4 重计算与 Body → D1/D2 Sketch → D4-D7 PartDesign → H3/H4 项目/FCStd 兼容 → I2-I5 发布门禁。
|
||
|
||
可并行工作流：
|
||
|
||
- E 视口可在 B5/B6 的网格和子形状协议稳定后与 C/D 并行。
|
||
- G 持久化可在 C1/C2 的对象和属性协议稳定后与 D/E 并行。
|
||
- F 应用壳可提前开始，但属性编辑器和模型树必须消费 BitBybit Facade 提供的 FreeCAD-compatible 投影，不能另建一套文档真值。
|
||
- H 的标准格式导入导出可在 B5 完成后开始；FCStd 兼容必须等待 C/D 的业务映射稳定。
|
||
- I 质量和发布不是最后补做；基准、浏览器测试和许可证扫描从阶段 0 进入持续流水线。
|
||
|
||
### 9.2 建议团队配置
|
||
|
||
- 1 名产品负责人/机械 CAD 领域负责人，负责 FreeCAD 语义、范围和验收模型。
|
||
- 1 名技术负责人，负责架构、协议、内核边界和关键决策记录。
|
||
- 2-3 名 CAD/几何/WASM 工程师，负责 OCCT、Sketch、PartDesign、拓扑和文件格式。
|
||
- 2-3 名前端/图形工程师，负责 React、Three.js、交互和性能。
|
||
- 1-2 名数据/平台工程师，负责 SQLite/OPFS、Worker、构建、离线和发布。
|
||
- 1-2 名质量工程师，负责黄金模型、跨浏览器、视觉、性能和恢复测试。
|
||
|
||
小团队可以一人兼任多个角色，但 CAD 领域验收、几何内核和跨浏览器数据可靠性不能无人专责。
|
||
|
||
## 10. 任务分解（WBS）
|
||
|
||
### A. 产品和领域
|
||
|
||
- A1 术语表、用户角色、用户旅程和 MVP 验收场景。
|
||
- A2 FreeCAD 工作流差异分析：App、Part、PartDesign、Sketcher、TechDraw、Assembly。
|
||
- A3 对象类型和属性字典；单位、容差、错误码和可见性状态。
|
||
- A4 命令目录、快捷键、事务语义和撤销规则。
|
||
- A5 兼容性等级、弃用政策和迁移策略。
|
||
- A6 固定 FreeCAD 基线版本，生成工作台/菜单/命令/对象/属性/任务/文件格式清单。
|
||
- A7 建立 FreeCAD UI 和业务行为黄金样例、差异分类和完成度仪表板。
|
||
|
||
交付：PRD、领域模型图、功能矩阵、验收场景、决策记录。
|
||
|
||
### B. 内核和 WASM
|
||
|
||
- B1 固定 BitBybit/OCCT 版本并验证许可证和构建来源。
|
||
- B2 定义并冻结 BitBybit Web CAD Facade，作为前端唯一依赖和唯一 Worker 网关。
|
||
- B3 评估并编译 FreeCAD App/Base/Sketcher/Part 可复用核心为 Facade 内部 WASM。
|
||
- B4 封装 BitBybit OCCT/Manifold/JSCAD 的对象句柄、生命周期和几何调用。
|
||
- B5 基本实体、布尔、变换、特征操作和拓扑访问。
|
||
- B6 三角化、法向、边线和材料分区。
|
||
- B7 Facade/Worker 消息、取消、超时、内存监控和错误映射。
|
||
- B8 可选线程化、SharedArrayBuffer 和 WebGPU 计算评估。
|
||
- B9 架构测试：阻止 React/业务包绕过 Facade 直接依赖内部库。
|
||
|
||
交付：BitBybit Facade 合同、FreeCAD WASM/兼容模块、内部 Kernel Adapter、能力矩阵、依赖检查、基准报告和错误诊断工具。
|
||
|
||
### C. 文档、参数和重计算
|
||
|
||
- C1 Document/Object/Container/Feature/Shape 数据结构。
|
||
- C2 属性系统、类型校验、单位换算和 UI 编辑元数据。
|
||
- C3 依赖图、拓扑排序、脏标记和增量重计算。
|
||
- C4 Body/Tip/特征顺序、可见性和抑制规则。
|
||
- C5 Command Bus、事务、撤销/重做和保存点。
|
||
- C6 诊断树、错误节点、上一次有效结果和恢复动作。
|
||
- C7 将 Document/Object/Property/Link/Expression 对齐固定 FreeCAD 版本并形成差异测试。
|
||
- C8 全部领域能力只经 BitBybit App/Model/Command API 暴露。
|
||
|
||
交付：领域包、协议文档、确定性测试集、错误码手册。
|
||
|
||
### D. Sketcher 和 PartDesign
|
||
|
||
- D1 草图几何模型、坐标变换、支持面和外部几何。
|
||
- D2 约束数据模型、求解器适配和欠约束/过约束诊断。
|
||
- D3 草图编辑交互、尺寸输入、吸附、修剪和投影。
|
||
- D4 Pad/Pocket/Revolution。
|
||
- D5 Fillet/Chamfer/Boolean。
|
||
- D6 Pattern/Hole/基准特征。
|
||
- D7 特征替换、重排、抑制、重命名和失败恢复。
|
||
- D8 与桌面 FreeCAD 的黄金零件对照。
|
||
|
||
交付：MVP 工作台、示例模型、求解器边界说明和回归集。
|
||
|
||
### E. Three.js 可视化
|
||
|
||
- E1 Renderer、相机、场景和资源生命周期。
|
||
- E2 BREP/网格缓存到 BufferGeometry 的转换。
|
||
- E3 对象/子形状拾取、预选和选择集。
|
||
- E4 线框、透明、剖切、测量、网格和基准显示。
|
||
- E5 视图状态、布局、LOD、实例化和性能模式。
|
||
- E6 WebGL2 基线、WebGPU 能力探测和回退。
|
||
|
||
交付：Viewport 包、交互规范、性能基准和视觉回归截图集。
|
||
|
||
### F. React 应用和交互
|
||
|
||
- F1 应用壳、路由、项目切换和加载状态。
|
||
- F2 模型树、搜索、过滤、拖放和上下文菜单。
|
||
- F3 属性编辑器、任务面板、约束列表和单位显示。
|
||
- F4 命令面板、快捷键、撤销/重做、进度和取消。
|
||
- F5 错误中心、诊断详情、帮助和可访问性。
|
||
- F6 响应式布局、主题、国际化和 PWA 安装体验。
|
||
- F7 逐工作台复现 FreeCAD 菜单、工具栏、任务面板、属性和命令状态。
|
||
- F8 前端依赖守卫：只允许导入 BitBybit Facade 和纯 UI 组件，禁止内部实现类型。
|
||
- F9 FreeCAD UI 结构、行为和状态三类兼容回归。
|
||
|
||
交付：完整桌面端工作区、最小触摸体验、可访问性报告。
|
||
|
||
### G. SQLite/OPFS
|
||
|
||
- G1 SQLite WASM 构建和 Worker 初始化。
|
||
- G2 模式、迁移、索引、事务日志和完整性检查。
|
||
- G3 资源管理器、OPFS 路径、哈希、引用计数和清理。
|
||
- G4 自动保存、恢复、备份、导入和配额错误。
|
||
- G5 BroadcastChannel 通知、单写者锁和多标签页冲突处理。
|
||
- G6 浏览器降级、存储能力检测和数据导出。
|
||
|
||
交付：Persistence Worker、迁移工具、恢复演练报告、数据格式说明。
|
||
|
||
### H. 文件互操作和兼容
|
||
|
||
- H1 STEP/IGES/网格导入适配和进度报告。
|
||
- H2 STEP/IGES/网格/GLB 导出和单位、材质处理。
|
||
- H3 Web CAD 项目包清单和校验。
|
||
- H4 FCStd 解析、对象映射、代理对象和兼容性报告。
|
||
- H5 版本差异样例、坏文件和大文件测试。
|
||
|
||
交付：格式适配包、样例仓库、互操作差异报告。
|
||
|
||
### I. 工程质量、发布和运营
|
||
|
||
- I1 CI/CD、版本、产物签名、SBOM 和许可证检查。
|
||
- I2 单元、集成、E2E、跨浏览器和视觉回归。
|
||
- I3 性能、内存、WASM 崩溃和存储配额监控。
|
||
- I4 安全测试：恶意文件、资源耗尽、插件沙箱和 CSP。
|
||
- I5 PWA 缓存、离线升级、迁移回滚和发布检查单。
|
||
- I6 用户反馈、问题分级、兼容矩阵和支持流程。
|
||
|
||
交付：发布流水线、质量门禁、运维手册和版本说明。
|
||
|
||
### J. FreeCAD 官方工作台完整覆盖
|
||
|
||
- J1 固定每个工作台的 FreeCAD 版本、源码提交、命令清单、对象类型和依赖模块。
|
||
- J2 Draft：工作平面、捕捉、二维几何、标注、转换、阵列和属性。
|
||
- J3 TechDraw：页面/模板、投影、剖视、尺寸、标注、中心线、导出和打印设置。
|
||
- J4 Spreadsheet：单元格、别名、表达式、格式、依赖和与模型属性的双向更新规则。
|
||
- J5 Mesh：导入、网格检查、修复、转换、简化、分组、显示和导出。
|
||
- J6 Assembly：组件实例、装配层级、约束、求解、碰撞、爆炸图和外部链接。
|
||
- J7 Path/CAM：Job、工具、刀路操作、模拟、后处理、G-code 和机床配置。
|
||
- J8 FEM：分析容器、材料、边界条件、网格、求解器适配、结果对象和后处理。
|
||
- J9 Arch/BIM：IFC/BIM 对象、层级、材料、空间、属性、导入导出和单位。
|
||
- J10 Robot、Raytracing/Rendering 及基线版本其他官方模块。
|
||
- J11 Python API 兼容子集、脚本权限、沙箱和 Addon manifest；第三方 Addon 单独评级。
|
||
|
||
- J12 每个工作台均实现 Facade 合同、React UI、任务流程、持久化、撤销、黄金模型和差异报告。
|
||
|
||
交付：按工作台发布的兼容矩阵、Facade API、UI 清单、示例工程、回归集和已知差异报告。没有 J12 的工作台不能标记为“完整支持”。
|
||
|
||
### K. 前端页面设计先行
|
||
|
||
- K1 固定 FreeCAD 版本并采集全局菜单、工作台、命令、快捷键、工具栏、面板、属性和任务清单。
|
||
- K2 建立应用级路由、文档标签、工作台上下文、任务覆盖层和系统页面导航图。
|
||
- K3 设计 FreeCAD 对标的视觉 Token、布局栅格、密度、图标、状态颜色、焦点和无障碍规范。
|
||
- K4 完成启动/欢迎、项目管理、导入、导出、恢复、只读分享页面。
|
||
- K5 完成默认 CAD 工作区、模型树、任务面板、Data/View 属性、报告/作业/诊断和选择测量页面。
|
||
- K6 完成 Start、Part、PartDesign、Sketcher、Draft、TechDraw、Spreadsheet、Mesh、Assembly 页面。
|
||
- K7 完成 Path/CAM、FEM、Arch/BIM、Robot、Rendering 及后续工作台的静态页面。
|
||
- K8 完成首选项、工作台/插件管理、命令搜索、依赖影响、重计算错误、存储错误、帮助和许可证页面。
|
||
- K9 为所有页面制作空、加载、进行中、预览、成功、警告、失败、取消、只读、兼容性和窄屏状态。
|
||
- K10 使用遵循 FreeCAD 对象/属性/任务结构的模拟数据，完成可点击原型和视觉回归截图。
|
||
- K11 组织 FreeCAD 用户评审，关闭结构/行为/状态差异，记录浏览器适配差异。
|
||
- K12 将页面字段、状态和操作映射到 BitBybit Facade API，并冻结设计到功能衔接 backlog。
|
||
|
||
交付：全量页面地图、UI manifest、设计系统、静态页面原型、状态矩阵、交互录屏、页面到 Facade 映射表和页面验收报告。
|
||
|
||
### 10.1 前端界面详细任务
|
||
|
||
以下任务按 FreeCAD 的界面心智拆分；每项都必须消费 BitBybit Facade 提供的 FreeCAD-compatible 投影和命令协议，不允许为了赶 UI 直接把参数写入 SQLite 或 WASM 句柄。
|
||
|
||
| ID | 任务 | 前置 | 主要验收 |
|
||
|---|---|---|---|
|
||
| UI-01 | 应用壳、菜单、文档标签、工作台切换器 | A1, C1 | 可打开多个文档，活动文档和工作台状态唯一 |
|
||
| UI-02 | Combo View：Model/Tasks 标签和可调整面板 | UI-01 | 任务开始自动切 Tasks，任务结束恢复 Model，布局可保存 |
|
||
| UI-03 | 模型树数据投影和虚拟化 | C1, C3 | 万级节点展开、搜索、状态徽标和选择同步不丢状态 |
|
||
| UI-04 | 模型树上下文菜单和拖放规则 | UI-03, C4 | 非法重排给出原因，删除前显示依赖影响 |
|
||
| UI-05 | Data/View 属性编辑器框架 | C2 | 属性按元数据生成，单位、只读、隐藏、输出属性符合定义 |
|
||
| UI-06 | 数值、单位、枚举、颜色、Placement、Link 编辑器 | UI-05 | 输入解析、校验、取消和提交都走 Command Bus |
|
||
| UI-07 | 多选属性和 mixed 值 | UI-05, C2 | 只显示共同可编辑属性，不覆盖未选对象的不同值 |
|
||
| UI-08 | TaskSession 面板框架 | C5 | 草稿、预览、Apply/OK/Cancel、Esc 取消和任务锁定可用 |
|
||
| UI-09 | Part/Part Design 命令工具栏和菜单 | A4, UI-08 | 命令根据工作台、选择谓词和文档状态正确启用/禁用 |
|
||
| UI-10 | Sketcher 二维编辑层 | D1-D3, E3 | 草图相机、吸附、选择、约束标识和退出恢复视图 |
|
||
| UI-11 | Three.js 视口交互适配 | E1-E4 | 预选、面/边/点选择、框选、右键菜单和标准视图一致 |
|
||
| UI-12 | 进度、Report、Jobs、Diagnostics | C6, G4 | 重算/导入/保存有进度、取消、错误定位和诊断详情 |
|
||
| UI-13 | 保存状态、恢复和关闭确认 | G4 | 自动保存失败持续可见，可直接导出备份 |
|
||
| UI-14 | 快捷键、命令搜索和帮助定位 | A4, UI-09 | 每个命令可搜索、显示前置条件、快捷键和帮助链接 |
|
||
| UI-15 | 主题、国际化、键盘无障碍和窄窗口降级 | UI-01-14 | 关键流程可键盘完成，窄窗口不遮挡操作，文本不溢出 |
|
||
| UI-16 | 视觉回归和交互录制 | I2 | 关键工作区、任务和错误状态具备稳定截图/录制样例 |
|
||
| UI-17 | FreeCAD UI manifest 生成和差异页 | A6, A7 | 每个菜单、命令、属性、任务和快捷键都有版本、状态和差异 |
|
||
| UI-18 | BitBybit 唯一入口依赖守卫 | B2, B9 | UI 构建图中不存在 FreeCAD/OCCT/Three.js/SQLite/OPFS 直接业务依赖 |
|
||
|
||
### 10.2 FreeCAD 业务逻辑详细任务
|
||
|
||
| ID | 任务 | 前置 | 主要验收 |
|
||
|---|---|---|---|
|
||
| BL-01 | App/View 状态边界和事件词汇表 | A2 | 几何定义与显示状态可独立保存、重建和测试 |
|
||
| BL-02 | Document/Object 注册、名称和 UUID 规则 | A3 | 内部名称稳定、标签可重命名、对象可跨重启恢复 |
|
||
| BL-03 | Property 类型、标志和编辑元数据 | A3, BL-02 | ReadOnly/Hidden/Output/NoRecompute/NoPersist 语义可测试 |
|
||
| BL-04 | PropertyLink、SubshapeLink 和跨文档引用 | BL-02, B5 | 循环检测、作用域校验、删除引用和替换引用有明确结果 |
|
||
| BL-05 | 版本化对象类型和代理对象 | BL-02 | 未支持类型可只读显示最近 Shape，并生成兼容性报告 |
|
||
| BL-06 | Document 状态机和版本号 | BL-02 | loading/recomputing/saving/closing 期间命令边界正确 |
|
||
| BL-07 | DAG、touched 传播和影响分析 | BL-04 | 可解释受影响闭包，不能产生循环或漏算 |
|
||
| BL-08 | Recompute Scheduler 和取消 | BL-06, BL-07, B7 | 结果只提交到匹配版本，取消不污染正式结果 |
|
||
| BL-09 | Feature execute 合约和错误诊断 | B5, BL-08 | 每个特征有输入快照、输出、诊断、耗时和内存摘要 |
|
||
| BL-10 | CommandDefinition 和 Selection Predicate | A4, BL-04 | 命令状态由工作台/选择/对象状态确定且可解释 |
|
||
| BL-11 | TaskSession 草稿和预览事务 | BL-09, BL-10 | Cancel 无持久化副作用，Apply/OK 产生正确事务 |
|
||
| BL-12 | Transaction、inverse 和撤销栈 | BL-02, BL-10 | 删除、重排、属性修改和特征创建可原子撤销/重做 |
|
||
| BL-13 | Body、Origin、Tip 和单实体规则 | C4, BL-07 | 历史顺序、Tip、抑制和多实体错误行为符合 PartDesign |
|
||
| BL-14 | Sketch 几何、约束和自由度模型 | D1-D2 | 欠约束、过约束、求解失败和支持面状态可诊断 |
|
||
| BL-15 | PartDesign 核心特征语义 | B5, BL-13, BL-14 | Pad/Pocket/Revolution/Fillet/Chamfer/Pattern/Hole 参数可重算 |
|
||
| BL-16 | Expression 受限解析和依赖边 | BL-03, BL-07 | 属性表达式可迁移、可检测循环、不执行任意脚本 |
|
||
| BL-17 | 稳定拓扑引用和重匹配 | B5, BL-04 | 上游修改后可靠匹配或进入人工确认，不静默误选 |
|
||
| BL-18 | Shape 结果、ViewObject 投影和缓存策略 | B6, E2 | 旧 Shape、预览 Shape、精细网格和显示属性生命周期一致 |
|
||
| BL-19 | 保存快照、恢复和数据库提交顺序 | G2-G4 | 参数、事务和 Shape 资产不会互相指向未提交版本 |
|
||
| BL-20 | FreeCAD 黄金模型和差异报告 | D8, H4 | 同一输入在 Web/桌面结果的几何、参数和已知差异可追踪 |
|
||
| BL-21 | FreeCAD 源码复用/等价实现判定 | A6, B3 | 每个模块记录复用方式、阻塞依赖、兼容等级和测试依据 |
|
||
| BL-22 | Facade 合同覆盖和泄漏检查 | B2, C8 | 所有前端用例只经 Facade 完成，公开类型不包含内部库对象 |
|
||
|
||
### 10.3 每个新特征的统一实施模板
|
||
|
||
以后增加 Pad 以外的任何特征，都必须按下列顺序交付，避免只完成按钮和几何函数：
|
||
|
||
1. **语义定义**：输入槽、参数、默认值、单位、约束、输出类型和失败条件。
|
||
2. **对象定义**：对象类型版本、属性元数据、内部名称、持久化和迁移规则。
|
||
3. **选择契约**：允许的对象/子形状、选择过滤、支持面和链接失效行为。
|
||
4. **领域命令**：CommandDefinition、TaskSession、预览参数和 Apply/OK/Cancel。
|
||
5. **内核适配**：由 BitBybit Facade 内部完成输入快照、Kernel Adapter 调用、容差、取消和内存释放。
|
||
6. **重计算规则**：touched 传播、依赖顺序、Tip 更新、旧结果和错误诊断。
|
||
7. **视图投影**：颜色、选择、边线、剖切、精细/粗糙网格和缓存淘汰。
|
||
8. **存储和撤销**：事务、inverse、数据库记录、Shape 资产和恢复顺序。
|
||
9. **互操作**：项目包和 FCStd 映射、无法导出的属性和兼容性警告。
|
||
10. **测试和帮助**：几何黄金样例、属性测试、浏览器 E2E、视觉回归、用户帮助和已知限制。
|
||
|
||
### 10.4 迭代实施顺序
|
||
|
||
每个迭代以一个可操作、可与锁定版本 FreeCAD 对照的垂直切片结束，顺序建议如下：
|
||
|
||
| 迭代 | 交付重点 | 必须贯通的链路 |
|
||
|---|---|---|
|
||
| 0 | 固定 FreeCAD 版本、UI/业务 manifest、WASM/OPFS POC | FreeCAD 源码/行为 → Facade 合同 → 决策记录 |
|
||
| 1 | 空文档、Document、模型树、保存状态 | React → BitBybit App/Project API → internal SQLite |
|
||
| 2 | Box/Cylinder、属性编辑、Undo/Redo | BitBybit Property/Command → internal OCCT → ViewObject → Project API |
|
||
| 3 | Body/Origin/Sketch 任务面板 | BitBybit Selection → TaskSession → FreeCAD-compatible Sketch 状态 |
|
||
| 4 | Pad/Pocket 及历史 Tip | BitBybit Model API → Scheduler → Viewport API 增量更新 |
|
||
| 5 | Fillet/Chamfer/Pattern、失败恢复 | Facade 诊断 → Task panel → inverse transaction |
|
||
| 6 | STEP/项目包、浏览器恢复 | BitBybit Project API → internal mapping/assets → export |
|
||
| 7 | FCStd A 档、跨浏览器和性能门禁 | 桌面 FreeCAD 对照 → compatibility report → release |
|
||
| 8+ | Draft/TechDraw/Spreadsheet/Mesh/Assembly/工程工作台 | 每个工作台 manifest → Facade → UI → persistence → parity tests |
|
||
|
||
每个迭代结束必须有可打开的示例项目、可重复的录制流程和自动化验收结果；未贯通保存、撤销、错误和恢复的几何功能不算完成。
|
||
|
||
## 11. 关键验收标准
|
||
|
||
### 11.1 功能验收
|
||
|
||
- React 界面只能通过 BitBybit Facade 完成全部 FreeCAD 工作流；依赖图和运行时日志证明没有直接内核、数据库、Three.js 业务入口。
|
||
- FreeCAD UI manifest 中目标批次的菜单、工作台、命令、任务面板、属性和快捷键均有实现状态及自动化覆盖，不存在未记录缺项。
|
||
- 用户能从空白文档创建带 Sketch、Pad、Pocket、Fillet 的零件，修改尺寸后只重算受影响特征。
|
||
- 浏览器刷新或重新打开后，模型树、参数、视图和撤销边界符合保存点。
|
||
- 选择任意面、边或顶点时，UI 显示稳定的对象和子形状引用。
|
||
- 发生失败特征时，界面保持可操作，错误指向具体输入并能恢复到上一次有效结果。
|
||
- 项目包可完整导出、导入、校验；损坏资源不会静默覆盖已有项目。
|
||
- 目标格式的导入导出样例通过几何、单位和基本材质校验。
|
||
|
||
### 11.2 性能验收
|
||
|
||
- 达到第 7 节定义的启动、重计算、帧率和主线程预算。
|
||
- 连续编辑 100 次后无可观测的 WASM 句柄、ArrayBuffer 或 Three.js 资源泄漏。
|
||
- 关闭并重新打开 500 MB 级项目时，页面不会因同步 I/O 卡死；失败能导出备份。
|
||
|
||
### 11.3 兼容和安全验收
|
||
|
||
- 锁定 FreeCAD 版本的对象、属性、命令、选择条件、任务流程、结果和错误均通过黄金样例；非 exact 项有用户可见差异说明。
|
||
- 对宣称“完整支持”的每个工作台，第 3.5 节和 J12 的界面、业务、存储、撤销、互操作和测试条件全部满足。
|
||
- 目标浏览器的能力矩阵、已知限制和降级行为均有自动化测试。
|
||
- 项目文件不能触发任意脚本执行；导入资源经过大小和路径校验。
|
||
- 发布包包含依赖许可证、WASM 来源和构建可复现信息。
|
||
|
||
### 11.4 页面设计阶段验收
|
||
|
||
- 第 6.1.3 节的所有页面均有唯一页面 ID、入口、出口、布局、组件清单、模拟数据和状态矩阵。
|
||
- 所有工作台至少有空状态、已有对象、任务进行中、预览、警告、失败、只读和窄屏稿；系统页至少有加载、成功、失败和恢复稿。
|
||
- 页面结构与锁定版本 FreeCAD 的菜单、工作台、Model/Tasks、Data/View、任务面板和命令状态完成对照审查。
|
||
- 静态原型可以用模拟数据完成核心页面流程，但没有直接导入或调用 BitBybit 内部 Worker、WASM、Three.js、SQLite 或 OPFS。
|
||
- 每个页面字段、状态和操作都映射到 BitBybit Facade 的 API 分组、事件和后续 WBS 任务。
|
||
- 通过桌面宽屏、窄窗口、键盘、触摸板、高对比度和文本溢出检查；关键页面拥有视觉回归基线。
|
||
- 页面冻结记录已批准；后续功能开发只能在不改变 FreeCAD 业务含义的前提下接入真实数据。
|
||
|
||
## 12. 风险与应对
|
||
|
||
| 风险 | 影响 | 应对 |
|
||
|---|---|---|
|
||
| 误把完整 FreeCAD 视为可直接 WASM 化 | 极高 | 阶段 0 先锁定复用边界；Qt/Python/GUI 明确排除 |
|
||
| BitBybit/OCCT WASM 体积和重计算速度不足 | 高 | Worker、按需加载、缓存、简化显示；设置模型规模上限和服务器后备路线 |
|
||
| Sketch 求解器移植成本超预期 | 极高 | 把求解器列为独立 POC；先支持受限约束集，保留服务化替换接口 |
|
||
| OCCT 拓扑命名导致链接丢失 | 高 | 自建稳定引用、特征映射、几何相似回退和明确的失效提示 |
|
||
| OPFS/多标签页/目标浏览器差异 | 高 | 启动能力探测；单写者；备份和降级；Chrome 回归 |
|
||
| WASM/SharedArrayBuffer 受安全响应头限制 | 中 | 首发不强依赖线程化；部署模板统一 COOP/COEP；检查第三方资源 |
|
||
| FCStd 兼容范围失控 | 高 | A/B/C 分档；不支持对象代理化；每个版本维护样例和差异报告 |
|
||
| 许可证和静态链接边界不清 | 高 | 在 POC 阶段完成 SBOM、NOTICE、动态/静态链接审查和法律确认 |
|
||
| 大型装配导致浏览器内存溢出 | 高 | 流式导入、LOD、实例化、资源淘汰、项目规模提示和可选服务器计算 |
|
||
| React 状态和三维场景状态不一致 | 中 | 领域状态单向投影；视口命令式控制器；禁止组件直接修改内核对象 |
|
||
| UI 或工作台绕过 BitBybit 唯一入口 | 极高 | Facade-only 包边界、静态依赖守卫、运行时消息审计和 CI 阻断 |
|
||
| “完整准确”没有固定 FreeCAD 版本 | 极高 | 锁定版本/提交，生成 UI/业务 manifest；升级作为独立迁移项目 |
|
||
| TypeScript 等价实现偏离 FreeCAD 行为 | 高 | FreeCAD 源码优先、黄金文档、同输入差分测试和兼容等级公开 |
|
||
|
||
## 13. 需要在 POC 前确认的决策
|
||
|
||
已经确认且不得在实施中弱化的决策：BitBybit 是唯一入口；界面和前端业务逻辑以 FreeCAD 为完整、准确的规范来源；FreeCAD 官方核心覆盖采用分批交付但不缩减最终兼容矩阵。
|
||
|
||
仍需在 POC 前固定的内容：
|
||
|
||
1. 是否正式批准 FreeCAD 1.1.1 发布标签及其精确源码提交作为首个兼容基线？
|
||
2. “官方核心完整”是否包含所有随 FreeCAD 发布的工作台；第三方 Addon 明确采用何种单独评级？
|
||
3. Core 1 是否要求读写 FCStd，还是读取 FCStd + STEP/项目包写出先行？
|
||
4. Sketcher 第一批和最终完整约束集的交付顺序是什么？
|
||
5. 是否接受 SQLite OPFS 在部分浏览器降级为显式文件保存？
|
||
6. 是否需要账号、云同步、团队权限和审计？
|
||
7. 目标最大模型规模、典型零件特征数量和设备档位是什么？
|
||
8. Path/FEM/BIM 等重型模块是否允许通过 BitBybit Facade 使用服务端计算后备？
|
||
9. 需要支持哪些语言、无障碍等级和触摸设备？
|
||
10. FreeCAD/OCCT/BitBybit 的版本锁定、源代码复用和许可证发布策略由谁审批？
|
||
|
||
## 14. 建议的首个里程碑
|
||
|
||
### 14.1 首个里程碑：全量前端页面设计冻结
|
||
|
||
这一里程碑不接入真实功能，目标是完成全部页面和工作台的 FreeCAD 对标设计：
|
||
|
||
1. 完成第 6.1.3 节所有应用级页面、CAD 工作区页面、工作台页面和系统页面的静态稿。
|
||
2. 每个页面具备空、加载、进行中、预览、成功、警告、失败、取消、只读、兼容性和窄屏状态。
|
||
3. 完成 FreeCAD UI manifest、页面导航图、页面字段表、组件状态表和页面到 BitBybit Facade 的映射。
|
||
4. 使用模拟数据走通新建项目、打开文档、切换工作台、创建 Body/Sketch、编辑属性、错误恢复、导入导出和首选项等页面流程。
|
||
5. 完成 FreeCAD 用户评审、视觉回归截图、键盘/无障碍检查和页面差异关闭清单。
|
||
6. 通过“无真实业务依赖”检查：页面原型不直接调用 WASM、Three.js 场景、SQLite、OPFS 或内部 Worker。
|
||
|
||
验收结果：所有页面有唯一 ID、入口、出口、状态、模拟字段、FreeCAD 对照依据和后续 Facade 衔接任务；未完成页面不得进入功能开发排期。
|
||
|
||
### 14.2 第二里程碑：FreeCAD + BitBybit 垂直功能切片
|
||
|
||
页面冻结后，再进行可测量的垂直功能切片：
|
||
|
||
1. React 工作区打开空白文档。
|
||
2. 工作区的菜单、Part Design 工作台、Model/Tasks、Data/View 和命令状态与锁定版本 FreeCAD 的垂直流程一致。
|
||
3. 用户只经 BitBybit Facade 创建 Box、Sketch、Pad、Pocket 和 Fillet。
|
||
4. BitBybit 内部 FreeCAD-compatible 业务模块和 OCCT WASM 在 Geometry Worker 中计算。
|
||
5. BitBybit Viewport API 使用内部 Three.js 显示结果并支持面选择。
|
||
6. BitBybit Project API 使用内部 SQLite WASM + OPFS 保存参数树和 Shape 缓存。
|
||
7. 刷新后恢复项目，导出 STEP 和 `*.webcad`。
|
||
8. 一组桌面 FreeCAD 对照模型、UI/业务差分、Facade-only 依赖检查和 Chrome 烟测通过。
|
||
|
||
这个垂直切片通过后，再扩大特征数量、文件兼容范围和协作能力。若其中任一关键路径无法满足性能或兼容性预算，应在此里程碑处重新选择“浏览器本地优先、服务器几何后备”或“缩小 FreeCAD 业务范围”，而不是继续堆叠 UI 功能。
|
||
|
||
### 14.3 当前仓库的前端冻结实现
|
||
|
||
当前提交已经把第一个里程碑的界面基线落到 `src/`，作为后续业务衔接的唯一视觉和交互入口：
|
||
|
||
| 实现项 | 当前状态 | 后续衔接边界 |
|
||
|---|---|---|
|
||
| `src/freecadManifest.ts` | 13 个工作台、菜单、命令分组、快捷键、对象类型的机器可读清单 | 替换为 BitBybit `Gui/Workbench/Command` projection，保持稳定 command id |
|
||
| `src/App.tsx` | Start、Projects、Import、Export、Settings、Help、Diagnostics、Sync 和 CAD Workspace 页面 | 所有按钮只改为调用 BitBybit Facade，不在 React 内实现模型规则 |
|
||
| CAD Workspace zones | FreeCAD 风格的菜单、全局工具栏、Workbench Navigation Bar、Document Tabs、Combo View、Viewport、Task Dock、Function Rail、Report View | Dock 状态、命令 enabled/disabled、任务生命周期由 Facade 事件驱动 |
|
||
| Model/Property/Task mock | 按 Document/Object/Body/Feature、Data/View、Apply/OK/Cancel 和警告状态组织 | 接入真实对象投影、Property metadata、TaskSession 和 Selection service |
|
||
| `src/styles.css` | 桌面 300px Combo View、360px Task Dock、44px 命令轨道，并有窄屏内部滚动布局 | 对照锁定 FreeCAD 版本做视觉回归，不改变业务语义 |
|
||
| 构建验收 | `./npmw run build` 通过；核心路由返回 200；已验收 1440x900 和 390x844 截图 | 增加 Playwright/视觉回归与键盘无障碍自动化 |
|
||
|
||
页面阶段的 viewport 仍是可交互的静态几何示意，不能宣称已完成 Three.js、FreeCAD 几何或存储能力。业务接入必须从 manifest 和冻结 DOM 结构开始，并通过 BitBybit 唯一入口完成。
|
||
|
||
## 15. 参考资料
|
||
|
||
- [BitBybit 官方文档](https://docs.bitbybit.dev/)
|
||
- [BitBybit 官方代码仓库](https://github.com/bitbybit-dev/bitbybit)
|
||
- [FreeCAD 官方代码仓库](https://github.com/FreeCAD/FreeCAD)
|
||
- [FreeCAD 官方发布版本](https://github.com/FreeCAD/FreeCAD/releases)
|
||
- [FreeCAD PartDesign 文档](https://github.com/FreeCAD/FreeCAD-documentation/blob/main/wiki/PartDesign_Workbench.md)
|
||
- [FreeCAD Scripting Basics：App 对象与 Gui/View 对象分离](https://github.com/FreeCAD/FreeCAD-documentation/blob/main/wiki/FreeCAD_Scripting_Basics.md)
|
||
- [FreeCAD Developers Handbook：属性变化与重计算](https://freecad.github.io/DevelopersHandbook/technical/PropertyChanges)
|
||
- [FreeCAD App::Document API：重计算、状态和依赖](https://freecad.github.io/SourceDoc/d8/d3e/classApp_1_1Document.html)
|
||
- [FreeCAD App::PropertyLink API：对象和特征引用](https://freecad.github.io/SourceDoc/d4/d77/classApp_1_1PropertyLink.html)
|
||
- [FreeCAD App::DocumentObject API：对象生命周期和特征类型](https://freecad.github.io/SourceDoc/d2/de4/classApp_1_1DocumentObject.html)
|
||
- [SQLite WASM 构建和 OPFS 文档](https://sqlite.org/wasm/doc/tip/persistence.md)
|
||
- [SQLite WASM 构建文档](https://sqlite.org/wasm/doc/c1244b92ce/building.md)
|
||
- [Three.js WebGPU/后端文档](https://threejs.org/docs/pages/Backend.html)
|
||
|
||
## 16. 执行版实施任务计划
|
||
|
||
本节是后续开发的执行基线。除非新增需求明确改变范围，否则按任务编号、前置依赖和阶段门推进；任务完成必须有代码、文档、测试或可审阅的决策记录，不能以“页面已显示”代替业务完成。
|
||
|
||
### 16.1 执行原则
|
||
|
||
1. **先合同，后实现**：先冻结 FreeCAD 版本、兼容等级、Facade 类型和事件，再实现内核、存储或页面接入。
|
||
2. **先最小垂直切片，后扩展广度**：先贯通 Document → Command → Geometry → Viewport → Project → Reload → Export，再扩展工作台和复杂格式。
|
||
3. **所有工作包可独立验收**：每个任务必须写明输入、输出、测试和失败处理；没有退出条件的任务不得标记完成。
|
||
4. **BitBybit-only**：React 只能依赖公开 Facade；Three.js、SQLite WASM、OPFS、FreeCAD/OCCT 和 Worker 消息只能出现在 Facade 内部包。
|
||
5. **可回滚**：数据库迁移、WASM 资源、页面合同和兼容矩阵都必须带版本；阶段门失败时回滚到上一个可运行切片。
|
||
6. **兼容等级公开**：每个命令、对象、属性和文件格式都标记 `exact`、`compatible`、`read-only`、`proxy` 或 `unsupported`。
|
||
|
||
### 16.2 当前基线和任务状态
|
||
|
||
状态取值：`DONE` 已通过退出条件；`IN PROGRESS` 正在实施；`PLANNED` 已排期但未开始；`BLOCKED` 只有在明确外部阻塞且有记录时使用。
|
||
|
||
| 基线项 | 状态 | 证据/说明 |
|
||
|---|---|---|
|
||
| FreeCAD UI 区域、工作台和核心术语盘点 | `DONE` | 官方文档依据已纳入第 15 节；界面 manifest 已落地 |
|
||
| 全量静态页面和 CAD Workspace | `DONE` | `src/App.tsx`、`src/styles.css`；桌面/移动截图验收通过 |
|
||
| 工作台/菜单/命令机器可读 manifest | `DONE` | `src/freecadManifest.ts`，13 个工作台和命令分组 |
|
||
| BitBybit Web CAD Facade 最小合同 | `DONE` | `src/facade/types.ts`、`src/facade/mockFacade.ts`；真实内核适配仍待 P3/P4 |
|
||
| FreeCAD/OCCT 几何 WASM | `IN PROGRESS` | `src/facade/geometryRuntime.ts` 已通过 BitBybit OCCT 1.1.1 Worker 接入基本体、布尔、Pad/Pocket/Revolution、Fillet/Chamfer 和 STEP/ASCII STL 导出；FreeCAD 自构建内核和完整特征历史仍未完成 |
|
||
| Three.js 真实视口适配器 | `IN PROGRESS` | `src/facade/threeViewport.ts`，锁定当前最新 `three@0.185.1`，WebGL2 适配器已挂入 Facade |
|
||
| React Facade 投影和静态替身 | `DONE` | 工作台、选择、文档树、通知已由 Facade 事件驱动 |
|
||
| SQLite WASM + OPFS 持久化 | `IN PROGRESS` | schema v4、OPFS/内存降级、单写者队列、内容寻址资源、自动保存已落地；迁移回滚、配额回收、跨标签写者和崩溃恢复仍待 P2 |
|
||
| 标准格式与 FCStd 兼容 | `IN PROGRESS` | BitBybit STEP/ASCII STL 导出已接入；`src/facade/fcstd.ts` 已完成安全 ZIP 预检和 Document.xml 元数据/代理报告，FCStd 对象映射、BRep 读写和 round-trip 仍待 P7 |
|
||
| Facade 单元测试和入口依赖守卫 | `DONE` | `tests/facade.test.ts`、`scripts/check-facade-boundary.mjs` |
|
||
| 自动化测试、性能门禁和发布流水线 | `IN PROGRESS` | `./npmw run verify` 已通过 47 个 Facade 测试、入口守卫和构建；跨浏览器、黄金几何、压力、fuzz 和发布流水线仍待 P8 |
|
||
|
||
### 16.3 阶段门和交付节奏
|
||
|
||
| 阶段门 | 目标 | 必须通过的条件 | 通过后才能开始 |
|
||
|---|---|---|---|
|
||
| G0 基线门 | 锁定 FreeCAD/BitBybit/浏览器/许可证基线 | 版本、源码提交、兼容矩阵、许可证和黄金样例已评审 | P1、P2、P3 |
|
||
| G1 合同门 | 冻结 Facade、领域 ID、错误和事件协议 | TypeScript 类型、JSON Schema、版本策略、架构依赖测试通过 | P3、P4、P5、P6 |
|
||
| G2 内核门 | 完成第一个确定性几何切片 | 基本体、Boolean、取消、诊断和三角化在目标浏览器通过 | P4、P5 |
|
||
| G3 文档门 | 形成可重算的 FreeCAD-compatible 对象图 | Document/Body/Sketch/Feature/Property/Link/Expression、事务和重计算黄金测试通过 | P6、P7 |
|
||
| G4 本地数据门 | 刷新后完整恢复工程 | SQLite/OPFS 单写者、迁移、校验、崩溃恢复和备份通过 | P7、P8 |
|
||
| G5 垂直切片门 | 贯通零件建模流程 | 新建 → Body → Sketch → Pad → Pocket → Fillet → 保存 → 恢复 → 导出通过 | MVP 试用 |
|
||
| G6 发布门 | 可发布、可回滚、可诊断 | CI、跨浏览器、性能、安全、许可证、迁移和发布检查单通过 | 生产部署 |
|
||
|
||
建议采用两周迭代：第 1 周实现和单元测试，第 2 周集成、黄金样例、视觉/性能回归和阶段门证据。每个迭代最多允许一个未解决的高风险项进入下一迭代。
|
||
|
||
### 16.4 工作包任务清单
|
||
|
||
#### P0：基线、治理和兼容矩阵
|
||
|
||
| ID | 任务 | 输出 | 前置 | 退出条件 |
|
||
|---|---|---|---|---|
|
||
| P0-01 | 锁定 FreeCAD 1.1.1 精确源码提交和构建参数 | `freecad-baseline.json`、源码/补丁清单 | 无 | 领域和技术负责人签字 |
|
||
| P0-02 | 锁定 BitBybit、OCCT、SQLite WASM、Three.js 版本 | `runtime-baseline.json`、SBOM 初稿 | 无 | 依赖可复现且无浮动范围 |
|
||
| P0-03 | 建立菜单/工作台/命令/对象/属性/任务兼容矩阵 | manifest、差异说明 | P0-01 | 每项有等级、来源和黄金场景 |
|
||
| P0-04 | 建立 20 个黄金模型和 10 个错误模型 | `fixtures/`、预期树/参数/诊断 | P0-01 | 桌面 FreeCAD 可重复生成 |
|
||
| P0-05 | 完成许可证、浏览器、内存和安全评审 | ADR、风险登记册 | P0-01/P0-02 | G0 通过 |
|
||
|
||
#### P1：BitBybit Facade 和协议
|
||
|
||
| ID | 任务 | 输出 | 前置 | 退出条件 |
|
||
|---|---|---|---|---|
|
||
| P1-01 | 定义 App/Gui/Workbench/Command/Selection/Task/Project/Viewport API | 版本化 TypeScript 类型和 JSON Schema | P0-03 | React 只通过 Facade 类型编译 |
|
||
| P1-02 | 定义命令状态、选择前置和禁用原因 | `CommandState`、能力查询、错误码 | P1-01 | 无选择/单选/多选状态可预测 |
|
||
| P1-03 | 定义事件、请求 ID、取消、进度和诊断 | 事件协议、错误手册、日志字段 | P1-01 | 一次操作全链路可关联 |
|
||
| P1-04 | 定义 Worker 网关和资源生命周期 | 内部消息协议、句柄回收规则 | P1-03 | 前端不能发送内部 Worker 消息 |
|
||
| P1-05 | 用静态内存 Facade 替换当前 UI mock | `MockFacadeAdapter`、页面适配层 | P1-01 | 页面不直接修改模型树/属性 |
|
||
| P1-06 | 建立 Facade-only 依赖守卫 | ESLint/依赖图/CI 检查 | P1-01 | 绕过入口的 import 会让 CI 失败 |
|
||
|
||
#### P2：SQLite WASM、OPFS 和 Project API
|
||
|
||
| ID | 任务 | 输出 | 前置 | 退出条件 |
|
||
|---|---|---|---|---|
|
||
| P2-01 | 固定数据库 schema、迁移版本和索引 | schema SQL、migration runner | P1-01 | 空库可从 0 迁移到当前版本 |
|
||
| P2-02 | 建立 Persistence Worker 和单写者队列 | Worker、请求/响应协议 | P1-03 | 1000 次事务无丢失且不阻塞 UI |
|
||
| P2-03 | 实现 OPFS 数据库/资源管理 | 哈希、引用计数、配额处理 | P2-01 | 资源可写入、校验和清理 |
|
||
| P2-04 | 实现自动保存、恢复和备份 | Project API、恢复报告 | P2-02/P2-03 | 强刷后恢复最后有效保存点 |
|
||
| P2-05 | 实现多标签页通知和锁冲突 | BroadcastChannel、Web Locks 互斥、`subscribeExternalChanges`、单写者提示 | P2-02 | 支持 Web Locks 时第二标签页不能静默覆盖；不支持时能力矩阵明确标记 `local-queue` 降级 |
|
||
| P2-06 | 实现能力检测和降级 | capability matrix、备份入口 | P2-03 | 不支持 OPFS 时可显式导出恢复 |
|
||
|
||
#### P3：FreeCAD/OCCT 几何运行时
|
||
|
||
| ID | 任务 | 输出 | 前置 | 退出条件 |
|
||
|---|---|---|---|---|
|
||
| P3-01 | 复现 FreeCAD/OCCT/BitBybit 构建 | WASM 构建脚本、资源清单 | G0/G1 | 干净环境生成同一 hash |
|
||
| P3-02 | 定义 ShapeHandle、SubshapeRef、MeshAsset | 句柄/拓扑/三角化类型 | P1-04 | 不暴露底层指针或临时索引 |
|
||
| P3-03 | 实现基本体和变换 | Box、Cylinder、Sphere、Cone、Placement | P3-01 | 尺寸和包围盒误差在预算内 |
|
||
| P3-04 | 实现 Boolean、Pad/Pocket、Revolution | Kernel Adapter、诊断；Pocket `throughAll` 基体范围计算 | P3-03 | 可取消，失败保留有效结果；`Up to face` 未实现时必须返回明确诊断 |
|
||
| P3-05 | 实现 Fillet、Chamfer、Pattern、Hole | 特征执行器 | P3-04 | 错误包含输入和子形状上下文 |
|
||
| P3-06 | 建立性能、内存和资源回收基准 | benchmark 报告 | P3-03 | 达到预算或形成降级决策 |
|
||
|
||
#### P4：文档、属性和重计算
|
||
|
||
| ID | 任务 | 输出 | 前置 | 退出条件 |
|
||
|---|---|---|---|---|
|
||
| P4-01 | 实现 Document/Object/Container/Feature/Shape | 领域包和序列化投影 | G1 | UUID、类型、标签和生命周期稳定 |
|
||
| P4-02 | 实现 Property/Link/Expression/Unit | 元数据、校验和单位换算 | P4-01 | Data/View 编辑器由 metadata 驱动 |
|
||
| P4-03 | 实现依赖 DAG、脏标记和拓扑调度 | recompute scheduler、稳定 `levels`、同层并发执行 | P4-01 | 只重算受影响闭包；同层对象无依赖；调度器以 `Promise.all` 并发执行并按计划顺序提交结果，未来再下沉到并行 Worker |
|
||
| P4-04 | 实现事务、撤销/重做和保存点 | Command Bus、undo journal | P4-03 | 100 次撤销/重做可回到原 hash |
|
||
| P4-05 | 实现 Body/Tip/特征顺序/可见性 | PartDesign 领域规则 | P4-01/P3-04 | 非法多实体和 Tip 操作被拒绝 |
|
||
| P4-06 | 实现诊断树和失败恢复 | Diagnostic model、repair actions | P4-03 | 失败节点可定位、回退或修复 |
|
||
|
||
#### P5：Three.js Viewport Adapter
|
||
|
||
| ID | 任务 | 输出 | 前置 | 退出条件 |
|
||
|---|---|---|---|---|
|
||
| P5-01 | 实现 WebGL2 renderer、相机和场景生命周期 | Viewport Adapter | P1-04 | 创建/销毁视口无 GPU 泄漏 |
|
||
| P5-02 | 实现 Shape/mesh 增量更新和缓存 | BufferGeometry、材质缓存；Pad/Pocket OCCT 预览链 | P3-02 | 单特征更新不重建整个场景；预览链在卸载时释放全部 Shape 句柄 |
|
||
| P5-03 | 实现对象/面/边/点拾取和预选 | Selection mapping | P3-02/P4-01 | 拾取返回稳定 SubshapeRef |
|
||
| P5-04 | 实现导航、标准视图、剖切、网格和测量 | Gui/Viewport commands | P5-01 | 视口和文档状态可区分 |
|
||
| P5-05 | 建立百万三角形和大装配基准 | 性能/内存报告 | P5-02 | 达到预算或触发 LOD 后备 |
|
||
| P5-06 | WebGPU 探测和回退 | optional backend | P5-01 | WebGPU 失败不影响 WebGL2 |
|
||
|
||
#### P6：React 页面和工作台接入
|
||
|
||
| ID | 任务 | 输出 | 前置 | 退出条件 |
|
||
|---|---|---|---|---|
|
||
| P6-01 | 将静态页面接入 Facade Provider | projection adapter | P1-05/P4-01 | React 不维护第二套文档真值 |
|
||
| P6-02 | 接入 Model/Tasks/Property/Selection 投影 | Combo View、Task Dock | P4-02/P4-05 | 选择、属性、任务单向同步 |
|
||
| P6-03 | 接入命令/工作台状态 | manifest runtime adapter | P1-02/P4-03 | disabled 原因可展示且不会执行；Diagnostics 页面实时展示 Facade/OCCT/SQLite/OPFS 能力 |
|
||
| P6-04 | 接入真实 Viewport 和报告视图 | Three.js adapter、diagnostics | P5-03/P4-06 | 可见预览、提交和错误结果 |
|
||
| P6-05 | 完成 Part/Part Design/Sketcher 垂直 UI | Core 1 页面 | P3-04/P4-05/P5-04 | G5 流程通过 |
|
||
| P6-06 | 完成键盘、窄屏、只读和恢复状态 | a11y/UX regression | P6-02 | 核心流程可键盘完成 |
|
||
|
||
#### P7：文件互操作和 FCStd 兼容
|
||
|
||
| ID | 任务 | 输出 | 前置 | 退出条件 |
|
||
|---|---|---|---|---|
|
||
| P7-01 | STEP/IGES/网格导入 | importer、进度、取消 | P3-03/P4-01 | 样例树、单位和形状可检查 |
|
||
| P7-02 | STEP/IGES/网格/GLB 导出 | exporter、单位/材质策略 | P3-02/P5-02 | 目标工具可重新打开 |
|
||
| P7-03 | Web CAD 项目包导入导出 | manifest、hash、schema version；Facade Shape 的 STEP/STL 下载 | P2-04 | 干净浏览器可恢复；没有有效 Shape 时导出按钮必须给出重计算诊断 |
|
||
| P7-04 | FCStd A 档对象映射 | compatibility importer | P4-01/P4-02 | 支持对象有等级，其余有 proxy 报告 |
|
||
| P7-05 | FCStd B/C 档差异评估 | golden samples、差异报告 | P7-04 | 无静默丢失 |
|
||
|
||
#### P8：质量、发布和运营
|
||
|
||
| ID | 任务 | 输出 | 前置 | 退出条件 |
|
||
|---|---|---|---|---|
|
||
| P8-01 | 单元、集成、E2E、黄金模型和属性测试 | test suites | P3/P4/P6 | G2/G3/G5 自动执行 |
|
||
| P8-02 | 跨浏览器和视觉回归 | Playwright matrix、截图基线 | P6-05 | 目标浏览器无 P0/P1 回归 |
|
||
| P8-03 | 性能、内存、WASM 崩溃和配额监控 | benchmark/diagnostic tooling | P2/P3/P5 | 指标可复现且可告警 |
|
||
| P8-04 | 安全、恶意文件和资源耗尽测试 | security report、CSP/SBOM | P7-01/P7-04 | 高危问题关闭或阻断发布 |
|
||
| P8-05 | PWA、缓存、迁移回滚和发布检查单 | release pipeline、runbook | P2-04/P8-01 | 可发布、可回滚、可恢复 |
|
||
| P8-06 | 兼容矩阵、帮助和支持流程 | release notes、support playbook | P8-02/P8-04 | 用户看到准确限制 |
|
||
|
||
### 16.5 依赖关系和并行分组
|
||
|
||
```text
|
||
P0 基线/治理
|
||
├── P1 Facade 合同/协议 ──────┬── P3 几何运行时 ──┐
|
||
│ ├── P4 文档/重计算 ─┼── P6 React 接入 ──┐
|
||
│ └── P5 Three.js ────┘ │
|
||
└── P2 SQLite/OPFS ────────────────────────────────────────────────┤
|
||
├── P7 文件互操作
|
||
└── P8 质量/发布
|
||
```
|
||
|
||
并行规则：P1 冻结前 P3-P7 只能做实验；P3 的 ShapeHandle/SubshapeRef 稳定后 P5/P7 才能真实实现；P4 的对象、属性和事务稳定后才能定版 P2 schema、P6 属性编辑器和 P7 FCStd 映射；P8 从第一天运行。
|
||
|
||
### 16.6 后续第一个迭代任务
|
||
|
||
下一次开发迭代固定执行以下任务，不再扩大范围：
|
||
|
||
1. `P0-01`：提交 FreeCAD 1.1.1 精确源码提交、构建环境和 UI/业务来源清单。
|
||
2. `P0-03`：将现有 `src/freecadManifest.ts` 与兼容矩阵字段对齐，补充选择前置、状态和兼容等级。
|
||
3. `P1-01`：建立 `BitBybitWebCadFacade` 最小 TypeScript 合同，只包含 app.document、gui.workbench、gui.command、selection 和 task。
|
||
4. `P1-05`：把当前静态回调替换为 `MockFacadeAdapter`，验证页面不直接修改模型树或属性。
|
||
5. `P1-06`：加入 Facade-only 依赖检查和 CI 失败示例。
|
||
6. `P4-01/P4-04`：验证最小 Document/Object 投影、特征追加、事务版本和撤销/重做边界。
|
||
7. `P8-01`：为新建文档、工作台切换、选择 Pad、打开 Task Dock、特征提交和属性编辑建立第一批自动化场景。
|
||
|
||
迭代退出条件：`./npmw run build`、类型检查、Facade-only 架构检查和桌面/移动页面截图全部通过；提交信息必须包含任务 ID，例如 `P1-01: define facade contract`。
|
||
|
||
### 16.7 任务执行和变更控制
|
||
|
||
- 每个任务建立一个分支或独立提交；跨任务改动必须在 PR 描述中列出原因和影响范围。
|
||
- 提交前更新任务状态、变更文件、测试命令、已知差异和下一步依赖。
|
||
- 新增工作台、对象、属性或文件格式时，先更新 P0-03 和 P1/P4 合同，再写实现。
|
||
- 数据库 schema 变化必须增加迁移、回滚和旧版本恢复测试。
|
||
- 与桌面 FreeCAD 不同的行为必须记录原因、兼容等级和用户可见提示。
|
||
- 高危几何错误、静默数据丢失、绕过 BitBybit 入口或不可恢复数据库问题，立即阻断阶段门。
|
||
- 每两周输出迭代报告：完成项、未完成项、阶段门、性能、差异、风险和下一迭代。
|
||
|
||
### 16.8 完成定义（Definition of Done）
|
||
|
||
一个任务只有同时满足以下条件才可标记 `DONE`：
|
||
|
||
1. 代码或文档已合并，类型、格式和依赖检查通过。
|
||
2. 有与风险匹配的单元、集成、黄金模型、视觉或恢复测试。
|
||
3. 失败、取消、只读、禁用和兼容性状态已定义，不能只覆盖成功路径。
|
||
4. API、事件、数据库 schema 或文件格式变化时，版本和迁移说明已更新。
|
||
5. 已记录 FreeCAD 来源、BitBybit Facade 映射、兼容等级和已知差异。
|
||
6. 阶段门证据可由其他成员在干净环境复现。
|
||
|
||
阶段门未通过时，任务只能保持 `IN PROGRESS` 或 `BLOCKED`，不得为了排期标记完成。
|
||
|
||
### 16.9 迭代 1 执行记录
|
||
|
||
本次开发已完成第一批合同和入口任务，状态如下：
|
||
|
||
| 任务 | 状态 | 实际证据 |
|
||
|---|---|---|
|
||
| P0-01 FreeCAD 基线文件 | `IN PROGRESS` | `config/freecad-baseline.json` 已建立；精确源码提交和构建参数仍需 POC 验证 |
|
||
| P0-02 运行时版本基线 | `IN PROGRESS` | `config/runtime-baseline.json` 已建立；Three.js 锁定 `0.185.1`，Bitbybit OCCT Worker/OCCT/Base 锁定 `1.1.1` 并记录 WASM SHA-256；FreeCAD 自构建内核仍待锁定 |
|
||
| P0-03 兼容矩阵 | `DONE` | `config/compatibility-matrix.json` 覆盖 13 个工作台和命令状态 |
|
||
| P1-01 Facade 最小合同 | `DONE` | `src/facade/types.ts` 定义 App/Gui/Command/Selection/Task/Viewport 合同 |
|
||
| P1-02 命令状态和选择前置 | `DONE` | MockFacade 根据工作台、选择对象类型和命令清单返回 enabled/disabled 原因；Part 布尔/检查仅接受 Shape-producing 对象，Sketcher 求解仅接受 Sketch，Part Design 特征拒绝文件夹和无几何对象 |
|
||
| P1-03 请求上下文、事件和诊断 | `DONE` | 命令事件携带 API 版本、请求 ID、文档 ID/版本和工作台；禁用命令生成结构化诊断 |
|
||
| P1-05 MockFacadeAdapter | `DONE` | `src/facade/mockFacade.ts`，React 工作区已通过事件投影工作台、选择、文档树和通知 |
|
||
| P1-06 Facade-only 依赖守卫 | `DONE` | `scripts/check-facade-boundary.mjs`，禁止 UI 绕过入口导入 Three.js/SQLite/OPFS/Worker |
|
||
| P4-01/P4-04 Document/Object 与事务最小切片 | `IN PROGRESS` | Pad/Pocket/Fillet/Chamfer 等已通过 Task 确认追加到 Body；新增 Part Design 特征会原子更新 Body.Tip，并按 Sketch/实体来源写入 Profile/Base；Feature 支持可持久化抑制、下游跳过、Shape 释放和解除后的最小闭包重算；文档版本、dirty、Undo/Redo、异步重算 generation 和过期结果拒绝已接通；真实 Shape 事务、完整容器/Tip 重定向规则和原子崩溃恢复仍待实现 |
|
||
| P4-06 诊断树与修复动作 | `PASS (基础闭环)` | 同步/异步重算错误生成带文档版本、generation、根因对象和依赖路径的结构化诊断；Facade 提供诊断树以及定位对象、合并当前 dirty 集后重算根因闭包、合法特征抑制动作；循环不会错误提供抑制修复；Diagnostics 页面通过 Facade 投影并执行动作；最近有效 Shape 显式回滚、复杂修复建议和性能计数器仍待实现 |
|
||
| P4-02 Property/Link/Unit | `IN PROGRESS` | DocumentObject 已携带 Data/View 类型化属性元数据；编辑经过 Facade 校验、版本、dirty、Undo/Redo、autosave 和 SQLite；基础表达式/单位/Link DAG 已落地；`App::PropertyLinkSub` 使用版本化 TopoRef，生成 `topo-ref` DAG 边并可保存加载。3D 多 Mesh 对象/OCCT analytic 面边点拾取、预选、整条 BRep Edge 折线高亮、诊断闪烁和 window/crossing 空间框选已接入 Three.js/Facade；模型树修饰键增删与 Visibility/Space 投影已落地；完整原生操作历史迁移写回、locale 和属性 mixed 仍待实现 |
|
||
| P2-01/P2-02 SQLite schema 与 Persistence Worker | `PASS (领域/压力门禁)` | schema v6 在 v5 checkpoints 基础上新增 `objects.topology_json`，保存 generation 拓扑快照；统一 migration runner 在一个事务中排序、跳过已应用版本并在失败时 rollback；`PersistenceWriteQueue` 的 1000 次写入压力覆盖严格顺序、最大并发 1 和 8 次失败后的继续执行。实际 SQLite v4→v5→v6 浏览器升级演练仍须进入 E2E/发布矩阵 |
|
||
| P2-03 OPFS 资源管理 | `IN PROGRESS` | Worker 提供 SHA-256 内容寻址、引用计数、读取/释放；新增 5% 配额预留、重复内容免重写、缺失文件重建，以及数据库记录/OPFS 文件对账清扫报告。配额与清扫策略单测和生产构建通过；真实 OPFS 孤儿文件、QuotaExceeded 和大资源浏览器压力仍待验证 |
|
||
| Worker memory resource fallback | `PASS` | Worker 在 SQLite WASM 无 OPFS 时使用 transient content-addressed resource map，保持 `put/get/release` 引用计数语义；不再把资源 API 错误地绑定到 OPFS |
|
||
| P2-04 自动保存调度 | `IN PROGRESS` | `ProjectAutosaveScheduler` 在 Facade 文档事务后按空闲窗口合并最新版本；每次保存与规范化文档同事务写入完整 checkpoint，每文档裁剪为最近 5 版；Recovery 报告列出版本，`loadCheckpoint()` 可无损加载指定/最新版且返回深克隆。内存回放测试通过；SQLite/OPFS 崩溃注入和用户可配置保留策略仍待补齐 |
|
||
| Document list/load/recovery transaction | `PASS` | `project.list()` 从 SQLite/内存快照返回 documentId、版本、对象数、dirty/readOnly 和更新时间；`app.document.load(documentId)` 通过 Project Facade 恢复快照，取消旧重算、释放缓存 Shape、清空选择/任务、提交可撤销的活动文档并按完整对象图异步重算；Recovery 对“数据库完整但目标快照不存在”返回 `unavailable`，工程管理页按真实 ID 打开 |
|
||
| P2-05 多标签页写入协调 | `DONE (降级可观测)` | `SqliteProjectPersistence` 在保存和资源写入外包 `navigator.locks` 独占锁，成功保存通过 `BroadcastChannel` 广播文档版本，Facade 暴露 `project.subscribeExternalChanges()`；无 Web Locks 的运行时能力标记为 `local-queue`，不宣称跨标签页互斥 |
|
||
| P5-01 Three.js 视口适配器 | `IN PROGRESS` | `src/facade/threeViewport.ts` 使用 `three@0.185.1`，已挂载 WebGL2 场景和资源释放；React 视口通过 Facade OCCT 预览链生成 Pad/Pocket Mesh |
|
||
| P3-01 Bitbybit OCCT WASM 运行时 | `IN PROGRESS` | 精确锁定 `@bitbybit-dev/occt-worker@1.1.1`，专用 Worker 可加载 34,524,750 字节 OCCT WASM；尚未建立 FreeCAD/OCCT 自构建脚本，不能标记完成 |
|
||
| P3-02 几何句柄与网格协议 | `IN PROGRESS` | Facade 已定义并实现受控 `ShapeHandle`、`MeshAsset`、`SubshapeRef` 与带对象 ID 的 `ViewportMeshAsset`；成功 generation 写入对象拓扑快照、迁移 matches 和保守历史；重算自动迁移 LinkSub/外部几何，歧义/删除保持显式状态和诊断；候选替换事务只接受源对象最新同 kind persistentId，属性/诊断 UI 可提交并支持 Undo/Redo；多对象视口注册及 OCCT `edgeList`/BRepGraph vertex 拾取已由 Chrome 双实体场景证明。插件失败时保留网格回退，但完整 OCCT 操作历史和跨 Boolean 映射仍未实现 |
|
||
| P3-03 基本体和变换 | `IN PROGRESS` | 真实 OCCT Box/Cylinder/Sphere/Cone 和浏览器矩阵已验证基础 Placement；Facade 重算 executor 现在对对象 Placement 做严格结构校验，在 Shape 生成后执行平移/轴角旋转，恒等变换跳过额外句柄，失败时释放临时 Shape 并保留最近有效缓存；Node/fallback 已覆盖失败释放、畸形输入和保存恢复。0.05 mm 网格精度下曲面包围盒最大离散误差约 0.023 mm，自动化浏览器黄金/体积测试尚未进入 CI |
|
||
| P3-04 Boolean/Pad/Pocket/Revolution | `IN PROGRESS` | 文档作用域 Union/Cut/Intersection 与 PlanarProfile 驱动的 Pad/Pocket/Revolution 已通过真实 OCCT 浏览器矩阵；重算 executor 已在 Worker ready 时执行 Pad/Pocket/Revolution，Revolution Angle/Reversed 已接入，Fillet/Chamfer 也有 Shape 缓存回写；Up to face、FCStd Shape 持久化仍待完成 |
|
||
| P3-05 Fillet/Chamfer/Mirrored/MultiTransform/Pattern/Hole | `IN PROGRESS` | Fillet/Chamfer 已接入 Shape 缓存；Mirrored 使用 OCCT plane-normal mirror；MultiTransform 组合结构化 Linear/Polar/Mirrored 步骤并限制最多 100 实例；Linear/Polar Pattern 已贯通 Placement/union；基础 Hole 支持 Diameter、Depth、Dimension/Through all。变换类当前操作整 Shape，Hole 固定原点法向；局部特征历史、Datum/TopoRef 平面、连接单实体过滤及完整孔语义仍待实现 |
|
||
| P5-02 网格增量接入 | `IN PROGRESS` | Three Adapter 可用 `BufferGeometry` 接收 Facade `MeshAsset`，替换时释放旧 GPU geometry；视口优先使用重计算缓存的对象 Shape，失败时保留最近有效结果，无缓存时才创建并释放 Pad/Pocket 临时预览链；对象级增量缓存与选择映射尚未实现 |
|
||
| P8-01 第一批自动化场景 | `IN PROGRESS` | `tests/facade.test.ts` 已覆盖 67 个场景，包括 Part/PartDesign Mirrored/MultiTransform/Pattern/Hole、TopoRef generation/候选替换、Sketch provider、几何重算、诊断修复、FCStd 安全、schema migration、1000 次写队列、检查点和资源治理；E2E/黄金几何待补齐 |
|
||
|
||
本迭代验证命令：`./npmw run check:facade-boundary`、`./npmw run test:facade`、`./npmw run build`。构建产物将 Three.js 拆为独立 chunk，避免把全部渲染库重复打入应用主 chunk。当前 npm registry 的 `three` 最新版本为 `0.185.1`，已在 `package.json` 和运行时基线中锁定。下一迭代继续完成 P0-01/P0-02 的精确锁定、P2-01/P2-02 的 SQLite/OPFS schema 与 Worker 单写者实验，以及 P3-01 的 FreeCAD/OCCT WASM 构建验证。
|
||
|
||
### 16.10 P2 持久化/视口验证记录
|
||
|
||
本次 P2 前置切片已产生真实浏览器证据，而不是只验证类型和打包：
|
||
|
||
| 检查 | 结果 | 证据 |
|
||
|---|---|---|
|
||
| COOP/COEP | `PASS` | `curl -I http://localhost:5173/` 返回 `same-origin` 与 `require-corp` |
|
||
| SQLite WASM Worker | `PASS` | 构建产物包含 `persistenceWorker`、SQLite Worker、OPFS proxy 和 `sqlite3.wasm` |
|
||
| OPFS VFS | `PASS` | Chrome `crossOriginIsolated=true`、`navigator.storage.getDirectory()` 可用 |
|
||
| 数据库创建 | `PASS` | 保存文档后 OPFS 根目录出现 `bitbybit-project.sqlite3` |
|
||
| OPFS 资源对象 | `PASS` | Worker 写入/读取 5 字节资源，重复写入复用 hash，释放两次后资源目录为空 |
|
||
| Three.js WebGL2 | `PASS` | Chrome SwiftShader 工作区检测到 1 个 canvas 且 `getContext('webgl2')` 成功 |
|
||
| 降级路径 | `PASS` | Node Facade 测试使用显式内存 Project adapter；不会假称 OPFS 已可用 |
|
||
|
||
仍未通过 G4/G5：自动保存恢复报告、1000 次压力报告、崩溃恢复、迁移回滚、完整 FCStd Shape 资源持久化和完整 FreeCAD/OCCT 计算尚未完成；当前 Facade 已有内存 Shape 缓存和 Pad/Pocket/Fillet/Chamfer executor，但这些仍由 P2-02 至 P4-06 的剩余任务负责。
|
||
|
||
### 16.11 P3 Bitbybit OCCT 几何运行时验证记录
|
||
|
||
本次接入使用 Bitbybit 官方发布的 OCCT WASM 包，不把它表述为 FreeCAD 业务逻辑已经移植。FreeCAD 的 DocumentObject、Property、Expression、重计算、PartDesign Body/Tip、Sketcher 求解器、稳定拓扑命名和 FCStd 映射仍由 P4/P7 后续任务实现。
|
||
|
||
| 检查 | 结果 | 证据 |
|
||
|---|---|---|
|
||
| 精确依赖 | `PASS` | `@bitbybit-dev/occt-worker`、`@bitbybit-dev/occt`、`@bitbybit-dev/base` 均为 `1.1.1`，无浮动版本 |
|
||
| WASM 资源 | `PASS` | 原始资源 34,524,750 字节；SHA-256 `1b6a8fc7b83d222854f73b66af8d0e45ad4fdee025904b447e885d4e18ae8656` |
|
||
| Worker 隔离 | `PASS` | OCCT 初始化和计算在专用 module Worker；React 及页面不导入 OCCT/Worker/Three |
|
||
| Facade Box | `PASS` | Chrome 中创建 `2 × 3 × 4` Box，得到 24 个面顶点、12 个三角形，所有坐标为有限数 |
|
||
| 轴语义 | `PASS` | `originOnCenter=true` 时包围盒为 X `[-1,1]`、Y `[-2,2]`、Z `[-1.5,1.5]`，即 Bitbybit Box 的 `width→X`、`height→Y`、`length→Z` |
|
||
| 句柄生命周期 | `PASS` | Facade 不公开 OCCT hash；释放后再次网格化被拒绝，已知 ID 的字段篡改触发完整性错误 |
|
||
| Three 网格消费 | `PASS` | `MeshAsset` 转为 Three `BufferGeometry`，旧 geometry 在替换/销毁时释放；选择变化不再重建场景 |
|
||
| 生产构建 | `PASS` | Vite 输出独立 `geometryWorker` 与 OCCT WASM；WASM 约 34.5 MB，gzip 约 8.6 MB |
|
||
|
||
限制和下一任务：P3-02 还需继续完善边/点级稳定 `SubshapeRef` 的持久命名算法；P3-03 需要把已通过的浏览器黄金包围盒矩阵纳入 CI，并补充体积核验；P5-02 已按文档对象 ID 建立多对象视口注册，但仍需做跨重算的 BufferGeometry 增量复用和大场景缓存淘汰。
|
||
|
||
### 16.12 P3-03 基本体与 Placement 验证记录
|
||
|
||
所有输入先在 Facade 边界验证有限数、正尺寸、角度范围、非零方向向量和文档版本；错误输入不会触发 Worker 初始化。Placement 使用平移和轴角旋转，固定 `scaleFactor=1`，不把缩放混入 FreeCAD Placement 语义。变换产生新句柄，源形状保持不变。
|
||
|
||
| 算例 | 结果 | 包围盒/误差 |
|
||
|---|---|---|
|
||
| Cylinder `r=2,h=4,Y轴,中心原点` | 106 顶点、100 三角形 | X `[-1.9854,1.9854]`、Y `[-2,2]`、Z `[-2,2]`；最大离散误差约 0.0146 mm |
|
||
| Sphere `r=1.5,center=[1,2,3]` | 168 顶点、306 三角形 | Z `[1.5,4.5]`；X/Y 极值最大离散误差约 0.0228 mm |
|
||
| Cone `r1=2,r2=1,h=3,Y轴` | 138 顶点、160 三角形 | Y `[0,3]`、Z `[-2,2]`；X 极值误差约 0.0146 mm |
|
||
| Box Placement `translation=[5,-1,2]` | 24 顶点、12 三角形 | 变换后 X `[4,6]`、Y `[-3,1]`、Z `[0.5,3.5]`，与解析值一致 |
|
||
| 相同 Box 双句柄 | `PASS` | 释放第一个句柄后第二个仍可网格化；最终引用释放才删除 OCCT 缓存形状 |
|
||
|
||
对象 Placement 的 Facade 重算合同：没有 `Placement` 属性时保持原有 Shape；存在但结构畸形、轴为零或角度越界时返回 `GEOMETRY_EXECUTION_FAILED`，且不调用几何创建器；非恒等变换失败会释放本次生成的局部 Shape，不覆盖上一次成功缓存。SQLite fallback 保存/加载后重新执行同一 Placement，验证结构化值未被扁平化。该合同仍只覆盖对象级变换，不覆盖 FreeCAD Body/Tip、Support、AttachmentOffset 或特征局部坐标链。
|
||
|
||
浏览器验证使用 `crossOriginIsolated=true` 的 Chrome、专用 OCCT Worker 和 `precision=0.05`。上述曲面误差均小于网格精度；这是三角网格显示误差，不代表 B-Rep 几何尺寸误差。
|
||
|
||
### 16.13 P3-04 Boolean 子阶段验证记录
|
||
|
||
Facade 已提供 `union`、`cut`、`intersection` 三个文档作用域 API。每个操作至少需要规定数量的输入，所有 ShapeHandle 必须属于结果 `documentId`，且输入版本不能高于结果版本；运算返回新句柄，源句柄保持有效。
|
||
|
||
Bitbybit OCCT Worker 1.1.1 的内置 Intersection 包装在调用 `BRepAlgoAPI_Common.Build()` 之前检查 `HasGenerated()`，可对正常相交实体返回空 Compound。项目没有静默接受空结果，而是在自有 Worker 插件中直接按正确顺序执行 `Build()`、检查 `IsDone()/HasErrors()`、取得 `Shape()` 并统一同域面。调用仍通过 Bitbybit `OCCTWorkerManager`，React 和页面无法访问 Worker 或 OCCT。
|
||
|
||
| 算例 | 结果 | 包围盒 |
|
||
|---|---|---|
|
||
| 两个 4 mm Box，第二个沿 X 偏移 2 mm，Union | 12 三角形 | X `[-2,4]`、Y/Z `[-2,2]` |
|
||
| 同一输入，Cut `A-B` | 12 三角形 | X `[-2,0]`、Y/Z `[-2,2]` |
|
||
| 同一输入，Intersection | 12 三角形 | X `[0,2]`、Y/Z `[-2,2]` |
|
||
| 释放三个结果后访问两个源 Box | `PASS` | 源包围盒分别保持 `[-2,2]` 和 X `[0,4]` |
|
||
| 跨文档/未来版本/输入不足 | `PASS` | Facade 同步拒绝，不触发 OCCT 运算 |
|
||
|
||
OCCT Boolean 结果可能与源形状共享底层拓扑。1.1.1 的 `deleteShape` 会执行全量几何清理，逐个删除结果可能破坏仍存活源形状。因此当前 Facade 在句柄释放时更新内部引用计数，并在活动句柄归零后统一 `cleanAllCache()`；Worker 终止时也会释放全部 WASM 内存。P3-06 需实现依赖感知的细粒度安全回收和长会话内存基准。
|
||
|
||
### 16.14 P3-04 Pad/Pocket/Revolution 验证记录
|
||
|
||
`PlanarProfile` 由一个外环和零到多个孔环构成。Facade 接受首尾重复或不重复的闭合表示，拒绝少于三个有效点、连续重复点、共线环、非有限坐标和不共面环；进入 OCCT 前会自动把孔环绕向调整为外环的反向。自相交、孔嵌套和轮廓相交仍需 Sketcher/ShapeFix 黄金验证，当前不能静默宣称完整草图兼容。
|
||
|
||
| 算例 | 结果 | 包围盒 |
|
||
|---|---|---|
|
||
| XZ 平面 `4×2` 轮廓 Pad，长度 3 | 24 顶点、12 三角形 | X `[-2,2]`、Y `[0,3]`、Z `[-1,1]` |
|
||
| 同轮廓 symmetricToPlane Pad，长度 4 | 24 顶点、12 三角形 | X `[-2,2]`、Y `[-2,2]`、Z `[-1,1]` |
|
||
| `6×6` 外环、`2×2` 孔环 Pad，长度 2 | 48 顶点、32 三角形 | X/Z `[-3,3]`、Y `[0,2]`，孔壁已生成 |
|
||
| `6×4×6` Box 上的 `2×2` 贯穿 Pocket | 48 顶点、32 三角形 | 外包围盒保持 X/Z `[-3,3]`、Y `[-2,2]` |
|
||
| X `[1,2]`、Y `[-1,1]` 面绕 Y 轴 360° Revolution | 212 顶点、208 三角形 | X `[-2,2]`、Y `[-1,1]`、Z 约 `[-1.9854,1.9854]` |
|
||
| 释放全部特征结果后访问 Pocket 基体 | `PASS` | 基体仍为 24 顶点、12 三角形，包围盒不变 |
|
||
|
||
Pad/Pocket 的方向向量在 Facade 内归一化，`length` 单独控制尺寸；`reversed` 改变方向，`symmetricToPlane` 将起始面移动到长度中点。Revolution Worker 插件支持任意轴原点和方向，弥补 Bitbybit 1.1.1 高层 `revolve` 固定绕原点轴的限制。Pocket 的 `Through all` 现在读取基体网格投影范围，按范围加余量生成对称切削工具；`Up to face`、双向长度和轮廓支持面映射继续由 P4-02/P4-05 与 P3-04 后续任务实现，未支持时返回 `UP_TO_FACE_UNSUPPORTED`，不会退化为固定长度。
|
||
|
||
### 16.15 P4-02 Property 元数据与编辑器验证记录
|
||
|
||
DocumentSnapshot 现在区分模型树投影与 `DocumentObjectSnapshot` 真值。每个对象包含 FreeCAD 风格的 `typeId` 和类型化 Property：String、Length、Angle、Bool、Enumeration、Link、Color、Percent、Float；metadata 同时声明 Data/View scope、group、unit、readOnly、hidden、recompute、options 和 expression。React 不再按 Pad/Pocket 名称硬编码属性行；Angle 属性使用 deg 单位和 0–360°输入约束。
|
||
|
||
| 检查 | 结果 | 证据 |
|
||
|---|---|---|
|
||
| Data 编辑 | `PASS` | 浏览器将 Pad Length 从 42 改为 50，树版本 v18→v19、对象 Status→Touched、tree state→dirty |
|
||
| View/Data 分离 | `PASS` | Visibility 等 View 属性提交文档事务但不把几何对象标记 Touched |
|
||
| 类型控件 | `PASS` | View 标签由 metadata 生成 1 个 checkbox、2 个 enumeration、2 个 numeric、2 个 color 控件 |
|
||
| Part primitive Task | `PASS` | Part 工作台任务可选择 Box/Cylinder/Sphere/Cone，尺寸和角度草稿写入 `Part::*` 对象属性并进入 OCCT 重算 |
|
||
| Part Boolean Task | `PASS` | Union/Cut/Intersection 任务提供 Base/Tool 对象选择槽，链接写入对象依赖图；确认后将新对象及其依赖闭包标记 dirty 并触发异步重算 |
|
||
| Part Design Task | `PASS` | Pad/Pocket/Revolution/Fillet/Chamfer 任务草稿写入核心参数；Linear/Polar Pattern 与结构化 MultiTransform 写入 Base 和变换参数；Hole 写入 Base、Diameter、Depth、Type；确认后均通过 Facade 历史边界提交并更新 Body.Tip |
|
||
| 选择谓词 | `PASS` | 选择 Origin/文件夹后 Part Union/Check geometry 被禁用；选择非 Sketch 对象后 Sketcher Solve 被禁用，并返回可解释原因 |
|
||
| 校验 | `PASS` | 负 Length、越界 Percent、未知 Enumeration、无效颜色、缺失 Link、只读 Property 在 Facade 拒绝 |
|
||
| Undo/Redo | `PASS` | Length 42→50 可撤销回 42、重做至 50，Property 和树投影同步 |
|
||
| SQLite/OPFS | `PASS` | Chrome `sqlite-opfs` 保存 v19 后重新加载 Length=61、Status=Touched、tree state=dirty |
|
||
| 移动布局 | `PASS` | 390×844 下 Combo View 560 px、Property Editor 280 px，7 个控件无横向溢出 |
|
||
|
||
持久化复用 schema v1 已有 `object_properties` 表：`value_json` 保存完整 Property snapshot，`property_type` 保留可查询类型；删除/重写对象时依赖外键级联清理旧属性。内存降级、autosave、Undo/Redo 和 Facade state 均使用深拷贝，避免 options/property 数组共享引用。
|
||
|
||
当前限制：Expression/Quantity 已完成基础词法、四则运算、`^` 幂运算、长度/面积/体积/角度/百分比换算、对象属性引用、维度校验，以及 `abs/sin/cos/tan/atan2/min/max/clamp/round/pow` 函数的基础维度规则；locale 规则、Spreadsheet alias 和完整 FreeCAD 表达式兼容仍待 EXU。PropertyLink、Expression 和下游对象现在进入统一依赖 DAG，支持 SCC 循环诊断、拓扑重算计划和 schema v3 持久化；当前重算执行器仍是 Facade 领域切片，尚未把每个节点调度到 OCCT/Sketcher Worker。多选 mixed、批量编辑、重置默认值和属性搜索仍由 P4-02/P6-02 后续任务完成。
|
||
|
||
### 16.17 EXU/DAG/TSN 基础切片验证记录
|
||
|
||
| 检查 | 结果 | 证据 |
|
||
|---|---|---|
|
||
| Quantity 基础运算 | `PASS` | `1 in + 2 mm = 27.4 mm`；长度/角度相加、除零会结构化失败 |
|
||
| Property Expression | `PASS` | Pad Length 可保存 `1 in + 2 mm`；Pocket 可引用 `pad.Length` 并生成 expression dependency |
|
||
| 依赖 DAG | `PASS` | `pad → pocket → fillet → body` 下游传播和稳定拓扑顺序均有测试 |
|
||
| 循环检测 | `PASS` | `pad.Length ↔ pocket.Length` 返回 `DEPENDENCY_CYCLE`，不提交伪造重算结果 |
|
||
| SQLite schema | `PASS` | schema v1→v2 增加 `recompute_json`，v2→v3 增加 dependency property/reference 字段 |
|
||
| 子形状签名 | `PASS` | 面签名不使用 transient `faceIndex`；重复签名标记 `ambiguous`，唯一候选可匹配 |
|
||
| Sketcher 领域模型 | `PASS` | Sketch 几何/约束快照、基础求解器、DOF/冲突诊断和 Facade 事务已接入，SQLite schema v4 保存 `sketch_json` |
|
||
| OCCT Fillet/Chamfer | `PASS` | Facade 调用 Bitbybit `filletEdges`/`chamferEdges`，半径/距离和边索引在边界校验；真实稳定 TopoRef 选边仍待 TSN |
|
||
| STEP/STL 几何导出 | `PASS` | Facade 通过 Bitbybit IO Worker 导出 STEP 和 ASCII STL；FCStd 参数化文档读写仍未完成 |
|
||
|
||
TSN 当前已接入普通单向 Pad/Pocket/Revolution/Groove 的 OCCT `Generated/Modified/Deleted` 历史、邻接指纹消歧、对象级 `FaceN/EdgeN/VertexN` ElementMap 和 FCStd live map 写出；仍未完成的是复合/多阶段跨 Boolean lineage、完整 ElementMap2 历史 token 迁移、所有对称模型的 exact 命名以及完整附着迁移。签名与邻接仍是无法由原生关系证明时的可审计 fallback，不能把 fallback 单独宣称为 FreeCAD 稳定拓扑命名。
|
||
|
||
Sketcher 当前边界：领域模型可往返保存点、线、圆、弧、椭圆和 B-spline（次数、控制点、权重、节点、周期标志）；基础适配器只对前四类及 Coincident/Horizontal/Vertical/Distance/Radius/Diameter/Angle/Equal/Symmetric/Tangent/Block 做确定性约束处理，对椭圆/B-spline 返回明确 unsupported 诊断。SK-04 已增加版本化 provider 协议、能力探测、取消/过期结果隔离和回放合同。仓库没有 FreeCAD 源码或 planegcs WASM 产物，因此对应 provider 明确返回 unavailable；完整 FreeCAD `planegcs` 数值求解、冗余约束分类、B-spline 求解、外部几何、自动约束和拖拽交互仍需 SK-03、SK-07、SK-09、SK-10 的 WASM/浏览器回放门禁。
|
||
|
||
### 16.16 引擎版本修复与完整 FreeCAD 对标专项
|
||
|
||
本项目原先以系统 Node `v20.19.2` 执行 npm，而依赖要求 Node 22，因而出现 `EBADENGINE`。现已增加项目内、SHA-256 校验的 Node `22.23.2`/npm `10.9.8` 运行时；日常命令统一使用 `./npmw` 或 `./nodew`，系统解释器不被修改。详见 [项目运行时基线](project-runtime.zh-CN.md)。
|
||
|
||
“完整 FreeCAD 对标”不等于已有页面或少量 OCCT 特征。稳定子形状命名、Sketcher 求解器、Expression/单位、依赖 DAG/重计算、剩余工作台和 FCStd/交换格式兼容已拆成独立的可验收任务包、阶段门和黄金测试，详见 [完整 FreeCAD 对标实施方案](freecad-full-parity-plan.zh-CN.md)。FreeCAD `1.1.1` 标签已核对并记录精确提交；构建参数和 WASM 端口仍须通过该方案的 F0 基线门后才能宣称兼容。
|
||
|
||
### 16.18 全功能范围与主任务账本
|
||
|
||
全功能范围已经按锁定源码的 34 个 `src/Mod` 目录重新审计，并补入 App/Base/Gui 的文档、事务、Property、选择、偏好、多文档、Python 控制台、宏、插件、剪贴板和打印行为。逐模块任务、依赖波次和退出条件见 [FreeCAD 1.1.1 全功能对标主任务账本](freecad-complete-parity-backlog.zh-CN.md)。
|
||
|
||
主任务账本把原来笼统的“其他模块”拆分为数据/交换、应用/扩展、Robot/Plot、脚本/桌面通用和开发/测试模块。任何能力即使由于浏览器安全或外部二进制无法端口，也必须登记为带诊断和数据保留策略的 `unsupported`，不能从清册中消失。
|
||
|
||
执行顺序固定为：范围/oracle → 平台内核 → OCCT 原生历史/TopoRef → planegcs Sketcher → Part/PartDesign → FCStd 双向往返 → TechDraw/Spreadsheet/Draft/Plot → Assembly/BIM/Mesh/Surface → FEM/CAM/Robot/Inspection/数据与应用模块 → 发布门禁。所有项目 Node/npm 命令只允许通过 `./npmw` 执行。
|
||
|
||
几何实现遵循 Bitbybit 优先策略：先复用其 OCCT Worker、建模、IO、三角化和缓存能力，再对缺口扩展锁定的 Bitbybit/OCCT 源码绑定并用 Emscripten 构建自有 WASM provider。自构建代码不得绕过 `BitBybitWebCadFacade`，并须通过来源/补丁/SBOM/hash、句柄生命周期和 Bitbybit↔自构建 provider↔FreeCAD 三方黄金差分门禁。对应任务为主账本 `BYB-01..08`。
|