docs: add executable implementation task plan

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

@@ -1138,6 +1138,7 @@ SQLite 是运行时的主存储，不要求项目包直接暴露数据库内部
 - J9 Arch/BIM：IFC/BIM 对象、层级、材料、空间、属性、导入导出和单位。
 - J10 Robot、Raytracing/Rendering 及基线版本其他官方模块。
 - J11 Python API 兼容子集、脚本权限、沙箱和 Addon manifest；第三方 Addon 单独评级。
+
 - J12 每个工作台均实现 Facade 合同、React UI、任务流程、持久化、撤销、黄金模型和差异报告。
 
 交付：按工作台发布的兼容矩阵、Facade API、UI 清单、示例工程、回归集和已知差异报告。没有 J12 的工作台不能标记为“完整支持”。
@@ -1376,3 +1377,195 @@ SQLite 是运行时的主存储，不要求项目包直接暴露数据库内部
 - [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 真实合同 | `PLANNED` | 由 P1 工作包冻结；当前只有页面层静态替身 |
+| FreeCAD/OCCT 几何 WASM | `PLANNED` | 由 P3 工作包实施；当前 viewport 是静态示意 |
+| Three.js 真实视口适配器 | `PLANNED` | 由 P5 工作包实施；当前不保存 Three.js 对象作为领域真值 |
+| SQLite WASM + OPFS 持久化 | `PLANNED` | 由 P2 工作包实施；当前页面仅展示存储状态 |
+| 标准格式与 FCStd 兼容 | `PLANNED` | 由 P7 工作包实施 |
+| 自动化测试、性能门禁和发布流水线 | `PLANNED` | 由 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、单写者提示 | P2-02 | 第二标签页不能静默覆盖 |
+| 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、诊断 | P3-03 | 可取消，失败保留有效结果 |
+| 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 | P4-01 | 只重算受影响闭包 |
+| 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、材质缓存 | P3-02 | 单特征更新不重建整个场景 |
+| 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 原因可展示且不会执行 |
+| 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 | P2-04 | 干净浏览器可恢复 |
+| 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. `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`，不得为了排期标记完成。