Web_FreeCAD_Bitbybit/docs/web-cad-implementation-plan.zh-CN.md

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 的公开类型和事件：

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 分层结构

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 工作区布局

┌──────────────────────────────────────────────────────────────────────────┐
│ 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/Edge、Firefox、Safari 的最新两个稳定大版本；明确 WebAssembly、WebGL2、Worker、OPFS 和 File System Access API 的支持差异。Safari 的 OPFS VFS 兼容性必须以实际版本测试为准，不能仅依赖能力探测。

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 官方核心覆盖”不可省略的后续计划。以需求、交互和技术决策已能及时确认作为前提，建议采用以下排期口径：

交付层级	建议团队	预计周期	范围
全量前端页面设计	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/Safari/多标签页差异	高	启动能力探测；单写者；备份和降级；跨浏览器回归
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/Firefox/Safari 烟测通过。

这个垂直切片通过后，再扩大特征数量、文件兼容范围和协作能力。若其中任一关键路径无法满足性能或兼容性预算，应在此里程碑处重新选择“浏览器本地优先、服务器几何后备”或“缩小 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 版本做视觉回归，不改变业务语义
构建验收	npm run build 通过；核心路由返回 200；已验收 1440x900 和 390x844 截图	增加 Playwright/视觉回归与键盘无障碍自动化

页面阶段的 viewport 仍是可交互的静态几何示意，不能宣称已完成 Three.js、FreeCAD 几何或存储能力。业务接入必须从 manifest 和冻结 DOM 结构开始，并通过 BitBybit 唯一入口完成。

15. 参考资料

• BitBybit 官方文档
• BitBybit 官方代码仓库
• FreeCAD 官方代码仓库
• FreeCAD 官方发布版本
• FreeCAD PartDesign 文档
• FreeCAD Scripting Basics：App 对象与 Gui/View 对象分离
• FreeCAD Developers Handbook：属性变化与重计算
• FreeCAD App::Document API：重计算、状态和依赖
• FreeCAD App::PropertyLink API：对象和特征引用
• FreeCAD App::DocumentObject API：对象生命周期和特征类型
• SQLite WASM 构建和 OPFS 文档
• SQLite WASM 构建文档
• Three.js WebGPU/后端文档

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 依赖关系和并行分组

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、特征提交和属性编辑建立第一批自动化场景。

迭代退出条件：npm 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 子形状拾取、重算迁移写回、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 类型；成功 generation 写入对象拓扑快照、迁移 matches 和保守历史；重算自动迁移 LinkSub/外部几何，歧义/删除保持显式状态和诊断；候选替换事务只接受源对象最新同 kind persistentId，属性/诊断 UI 可提交并支持 Undo/Redo。OCCT 原生历史、邻接/曲率签名、跨 Boolean 映射和 3D 候选高亮仍未实现
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/黄金几何待补齐

本迭代验证命令：npm run check:facade-boundary、npm run test:facade、npm 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 建立多对象网格缓存，而不是仅加载一个启动预览实体。

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 工作：OCCT Generated/Modified/Deleted 历史捕获、跨布尔/特征的真实拓扑映射、面/边/顶点统一命名、附着和 TopoRef 文件迁移。当前签名是可审计的基础候选层，不能单独宣称 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，系统解释器不被修改。详见 项目运行时基线。

“完整 FreeCAD 对标”不等于已有页面或少量 OCCT 特征。稳定子形状命名、Sketcher 求解器、Expression/单位、依赖 DAG/重计算、剩余工作台和 FCStd/交换格式兼容已拆成独立的可验收任务包、阶段门和黄金测试，详见 完整 FreeCAD 对标实施方案。FreeCAD 1.1.1 标签已核对并记录精确提交；构建参数和 WASM 端口仍须通过该方案的 F0 基线门后才能宣称兼容。