14 KiB
Web FreeCAD 用户实际验证与上线手册
版本：1.0
日期：2026-09-15
适用对象：试用用户、业务验收人员、上线值守人员
1. 验证原则
本手册验证 Web FreeCAD 的实际可用性，不替代源码审查。几何算法必须由 OCCT WASM 完成，Three.js 只负责显示。验证人员应记录实际结果，不因界面显示正常而推断模型算法正确。
2. 环境与启动
- 使用最新版 Chrome、Edge 或 Firefox，启用 WebAssembly、Web Worker、IndexedDB/OPFS。
- 解压发布目录，确认
index.html、kernel/FreeCADWebKernel.wasm、kernel/FreeCADWebKernel.js和modules/manifest.json存在。 - 通过 HTTP(S) 服务访问，不要直接双击
file://。例如在web/dist执行python3 -m http.server 8080，浏览器打开http://localhost:8080/。 - 打开开发者工具 Console，确认无启动异常；Network 中确认 WASM 和模块请求返回 200。
- 记录浏览器版本、操作系统、屏幕分辨率和测试日期。
3. 启动与界面烟测
- 首次打开应出现项目工作区、文档标签、模型树、属性区和 Three.js 视口。
- 新建两个文档，切换标签，确认活动文档唯一且模型树互不串扰。
- 刷新页面，确认应用可以重新启动；若存在恢复提示，记录提示内容。
- 切换 Part、PartDesign、Sketcher、Draft、BIM、TechDraw、Mesh、FEM、CAM、Spreadsheet、Inspection、Robot、Assembly、Web、Python 等工作台入口，确认页面可进入且无白屏。
- 改变视口尺寸，执行旋转、平移、缩放、适合视图，确认只影响显示，不改变模型数据。
4. 基础建模与 OCCT 几何验证
- 新建文档，创建 Part Box，输入长度 2、宽度 3、高度 4，应用并重算。
- 检查属性值和模型树对象名称；若界面提供体积信息，应为约 24。
- 创建第二个基本体，移动或改变尺寸，确认两个对象同时显示且互不覆盖数据。
- 执行撤销、重做，确认事务前后属性和模型树一致。
- 选择对象并删除，再撤销删除；确认选择状态、树节点和视口同步。
- 对可用的布尔、变换、复制、链接、分组命令各执行一次，确认结果来自 WASM 返回的几何/文档数据，而不是前端生成的替代几何。
5. 文档、属性与事务
- 在模型树选择对象，逐项查看属性；修改长度、角度、颜色、可见性和标签。
- 点击应用/重算，确认修改后的值保留；取消编辑，确认未提交值不污染文档。
- 使用复制、剪切、粘贴、删除、选择全部、依赖关系、表达式（如界面提供）并记录结果。
- 连续执行三次修改后逐级撤销，再逐级重做，确认事务顺序正确。
- 在两个文档之间切换，确认属性面板始终对应当前活动文档。
6. 文件导入、导出、保存与重开
- 导入示例 STEP 文件，等待 Worker 返回网格，确认模型树对象出现、视口有三角网格且无 NaN/空白。
- 依次尝试项目支持的 FCStd、STEP、IGES、BREP、STL、OBJ、DXF、IFC 等格式；对不支持格式应显示明确错误，不得静默成功。
- 保存为 FCStd，确认下载文件或 OPFS 文件列表出现。
- 修改模型后再次保存，确认文件大小/修改时间变化；关闭文档并重新打开，确认对象数量、标签和关键属性恢复。
- 导出 STL/网格格式后，用外部查看器检查文件可读；再次导入并比较包围盒、面数或体积（允许记录格式误差）。
- 浏览器刷新后从 OPFS 选择文档打开，确认持久化恢复；清理站点数据后应明确提示文档已不存在。
7. 模型树、链接与结构
- 创建 Part、VarSet 或等效结构对象，确认树层级、Tip 和选择分组正确。
- 创建对象链接/子链接，替换链接目标，再解除链接；检查事务、树显示和视口结果。
- 执行分组、解组、克隆/取消克隆（模块提供时），确认原对象和新对象的生命周期明确。
- 在结构操作后保存、重开，确认链接关系没有变成空引用。
8. 各功能模块验证矩阵
对每个模块至少执行“进入—创建/读取—修改—保存/返回”一条链路，并记录不适用项：
| 模块 | 最低验证动作 |
|---|---|
| Part/PartDesign | 基本体、特征、重算、属性修改 |
| Sketcher | 创建草图/几何约束，退出编辑并保存 |
| Draft/BIM | 创建对象、层级/关系、可见性和窗口焦点 |
| TechDraw | 创建页面/视图，检查页面对象和导出入口 |
| Mesh/STL | 导入网格、显示、导出并重开 |
| Import/STEP/IGES | 导入、生成网格、保存 FCStd |
| FEM/CAM | 打开任务面板，创建可用任务或显示明确依赖提示 |
| Spreadsheet | 新建表格、编辑单元格、表达式/保存 |
| Inspection/Measure | 选择几何、执行测量、读取结果 |
| Assembly/Robot | 创建或读取装配/机器人对象，检查树和变换 |
| Surface/ReverseEngineering | 创建/读取曲面对象，检查属性和显示 |
| OpenSCAD/TemplatePyMod/Python | 执行支持的脚本/导入流程，记录依赖提示 |
| Web/Cloud/Sandbox | 初始化、请求、取消、错误恢复和持久化 |
| Std 命令 | 新建、打开、保存、撤销/重做、工作台和视图命令 |
源语义定义为空操作的 Std_Test5/6 等命令，应记录“按桌面语义无业务副作用”，不能判定为缺失。
9. Worker、取消与错误恢复
- 发起一个导入或重算操作，操作未完成前点击取消；确认界面回到可操作状态。
- 重复提交相同请求，确认不会产生重复对象或重复事务。
- 输入空文件、损坏文件、无效尺寸和不存在路径，确认返回可理解错误码/消息。
- 错误后立即执行一次正常 Box 创建或打开已有文档，确认 Worker 和 WASM 实例可继续工作。
- 观察长任务期间页面仍可切换文档；若业务规定串行，应显示忙碌状态而非无限等待。
10. 显示与数据一致性
- 改变颜色、透明度、可见性和视图模式，确认只改变 Three.js 显示对象。
- 隐藏/显示对象后保存并重开，按产品定义检查可见性是否持久化。
- 选中模型树节点，确认视口高亮对象与节点一致；删除后不得残留孤立网格。
- 检查大模型加载时内存和帧率，记录浏览器 Console 的 WebGL/WASM 警告。
11. 上线前准入标准
- 启动、模块加载、WASM 内核烟测全部通过。
- 核心 Part Box、STEP 导入、FCStd 保存/重开、OPFS 恢复链路通过。
- 所有模块入口可达；不支持能力返回明确提示。
- 几何边界审计无发现，Three.js 未进入 Facade/Worker 算法层。
- 关键错误可恢复，无持续空转、重复请求或页面死锁。
- 所有失败项均有复现步骤、日志、截图和责任人；未验证项不得标记为“通过”。
12. 缺陷记录模板
记录：日期、浏览器/系统、URL、模块、命令、输入文件 SHA-256、操作步骤、预期、实际、错误消息、Console/Network 日志、截图、是否可重现、严重级别和处理结论。
严重级别：P0（无法启动/数据损坏）、P1（核心建模或保存失败）、P2（单模块功能异常）、P3（显示或文案问题）。P0/P1 未关闭不得上线。
13. 已完成自动烟测与用户验证边界
自动烟测已覆盖 WASM 版本、OCCT Box 体积/包围盒、STEP 网格生成与清理、几何边界审计和 Vite 生产打包。浏览器兼容性、真实业务数据、性能容量和最终验收必须由用户按本手册执行并签字确认。
14. 逐项执行记录规则
每项测试均按“准备—操作—观察—判定—记录”五步执行。预期结果全部满足记为通过；任一步骤异常记为失败，不得用“基本正常”代替。每项记录测试编号、开始/结束时间、文档名、输入文件、浏览器、实际结果和截图路径。
15. 启动与界面逐步测试
UI-01 首次启动
准备：清空该站点缓存后打开根 URL。操作：等待首页完全加载，观察 Console 和 Network。预期：页面在 30 秒内显示工作区；FreeCADWebKernel.js/wasm、modules/manifest.json 返回 200；无未捕获异常。失败：白屏、循环加载、WASM 404 或未捕获异常。
UI-02 文档标签隔离
操作：新建文档 A、B；在 A 创建 Box，在 B 创建不同尺寸 Box；来回切换标签。预期：模型树、属性和视口只显示当前文档内容，修改 A 不改变 B。失败：对象串文档、活动标签错误或切换后树为空。
UI-03 工作台入口
操作：依次点击各工作台入口，等待每页首屏；返回首页后重复一次。预期：每个入口可达，无白屏；不可用功能显示明确依赖/能力提示。失败：路由 404、加载卡死或静默无响应。
UI-04 视口交互
操作：在有模型文档中拖拽旋转、滚轮缩放、中键平移、点击适合视图，再调整浏览器窗口大小。预期：模型连续显示、无明显残影，模型数据和属性不变。失败：交互导致模型数据变化、视口崩溃或出现孤立网格。
16. 几何与建模逐步测试
GEO-01 Box 参数与重算
操作：新建文档→Part→Box；输入 2、3、4→应用/重算；读取属性和体积。预期：体积约 24，包围盒约 [0,0,0]-[2,3,4]，树中只有一个对象。失败：数值错误、重算失败或体积为空。
GEO-02 参数修改事务
操作：将长度改为 5→应用；再改为 7→取消；执行撤销、重做各一次。预期：取消后仍为 5；撤销回到 5 之前状态，重做恢复 5；事务顺序稳定。失败：取消仍写入、撤销越界或重做产生重复对象。
GEO-03 多对象与布尔
操作：创建两个基本体→移动使其相交→执行可用布尔操作→重算。预期：结果对象可选、可见、可保存；原对象处理符合界面语义。失败：前端生成替代几何、结果无拓扑或保存后丢失。
GEO-04 选择与删除恢复
操作：框选/树选对象→删除→撤销删除→再次删除。预期：树、属性、视口同步更新；撤销后对象完整恢复。失败：残留显示、空树节点或选择指向已删除对象。
17. 文件流程逐步测试
FILE-01 STEP 导入
操作：打开示例 STEP→等待导入完成→检查树、面数/体积和视口→保存 FCStd。预期：树出现导入对象，视口有非空三角网格，保存成功。失败：导入超时、空网格、NaN 或保存文件为 0 字节。
FILE-02 多格式导入
操作：分别导入项目支持的 IGES、BREP、STL、OBJ、DXF、IFC 文件；每次关闭当前文档后再测下一格式。预期：支持格式有明确对象和显示；不支持格式返回明确错误码。失败：格式错投、静默成功或错误后 Worker 无法继续。
FILE-03 保存与重开
操作：创建并修改 Box→保存 FCStd→关闭→从文件选择器重开→核对对象数量、标签、尺寸。预期：数据与保存前一致。失败：标签丢失、尺寸回退或重开后空文档。
FILE-04 OPFS 刷新恢复
操作：保存到 OPFS→刷新页面→在 OPFS 列表选择文件→打开。预期：文件仍在列表，文档和对象恢复；清除站点数据后文件消失并给出提示。失败：刷新后列表丢失、恢复串文档或无提示。
FILE-05 STL 导出回读
操作：导出 STL→下载到本地→重新导入 STL→比较包围盒和面数。预期：文件可读，几何误差在业务容差内。失败：文件损坏、导入空网格或比例明显错误。
18. 文档树、属性和链接逐步测试
DOC-01 属性编辑
操作：选择对象→依次修改标签、颜色、透明度、可见性和尺寸→应用→保存重开。预期：可编辑属性生效；持久化属性重开后保留。失败：界面值与模型值不一致。
DOC-02 分组与层级
操作：创建 Part/VarSet→将对象加入/移出→设置 Tip→保存重开。预期：层级、Tip、选择范围一致。失败：树层级错乱或对象丢失。
DOC-03 链接替换与解除
操作：建立对象链接→替换目标→解除链接→分别撤销/重做。预期：每一步事务可回退，解除后无空引用。失败：旧目标残留、链接指向 null 或重开失效。
19. 模块逐步测试通用模板
对表格中的每个模块执行：①进入模块；②创建或打开一个最小对象；③修改一个属性；④执行应用/重算；⑤保存并返回；⑥重新进入检查对象。记录“模块、对象、命令、输入、预期、实际、截图”。模块没有对应数据时，使用其自带示例，并将“依赖不可用”记录为环境结果而非通过。
20. Worker 与异常恢复逐步测试
ERR-01 取消
操作：启动较大的导入或重算→立即点击取消→等待状态结束。预期：状态回到可操作，未产生半成品对象。失败：按钮永久忙碌、页面冻结或产生重复对象。
ERR-02 非法输入
操作：输入空文件、损坏文件、零/负尺寸、不存在路径。预期：显示明确错误，随后可正常创建 Box。失败：崩溃、无限等待或错误后所有命令失效。
ERR-03 重复请求
操作：连续双击保存/导入/应用按钮。预期：只生成一个事务和一个对象。失败：重复对象、重复文件或状态计数增长两次。
21. 性能和上线前逐步测试
PERF-01 大文件加载
操作：使用小、中、大三组真实文件，分别记录从选择文件到首个可见网格的时间、峰值内存和浏览器帧率。预期：无崩溃、无持续空转；超出限制时给出提示。失败：浏览器无响应或 Worker 泄漏。
PERF-02 长时间稳定性
操作：连续执行导入→修改→保存→重开循环 20 次，每 5 次刷新页面。预期：无累计错误、对象数不异常增长、OPFS 列表无重复。失败：错误率上升、内存持续增长或恢复失败。
22. 最终签署
完成全部编号后，验收人员填写：通过项数/总项数、失败项及 P0/P1 数量、未测项及原因、浏览器范围、测试数据清单、上线建议和签名日期。存在任何 P0/P1 或未解释的空转/阻塞，不得签署上线；P2/P3 须有明确修复计划和负责人。