224 lines
14 KiB
Markdown
224 lines
14 KiB
Markdown
# Web FreeCAD 用户实际验证与上线手册
|
||
|
||
版本：1.0
|
||
日期：2026-09-15
|
||
适用对象：试用用户、业务验收人员、上线值守人员
|
||
|
||
## 1. 验证原则
|
||
|
||
本手册验证 Web FreeCAD 的实际可用性，不替代源码审查。几何算法必须由 OCCT WASM 完成，Three.js 只负责显示。验证人员应记录实际结果，不因界面显示正常而推断模型算法正确。
|
||
|
||
## 2. 环境与启动
|
||
|
||
1. 使用最新版 Chrome、Edge 或 Firefox，启用 WebAssembly、Web Worker、IndexedDB/OPFS。
|
||
2. 解压发布目录，确认 `index.html`、`kernel/FreeCADWebKernel.wasm`、`kernel/FreeCADWebKernel.js` 和 `modules/manifest.json` 存在。
|
||
3. 通过 HTTP(S) 服务访问，不要直接双击 `file://`。例如在 `web/dist` 执行 `python3 -m http.server 8080`，浏览器打开 `http://localhost:8080/`。
|
||
4. 打开开发者工具 Console，确认无启动异常；Network 中确认 WASM 和模块请求返回 200。
|
||
5. 记录浏览器版本、操作系统、屏幕分辨率和测试日期。
|
||
|
||
## 3. 启动与界面烟测
|
||
|
||
1. 首次打开应出现项目工作区、文档标签、模型树、属性区和 Three.js 视口。
|
||
2. 新建两个文档，切换标签，确认活动文档唯一且模型树互不串扰。
|
||
3. 刷新页面，确认应用可以重新启动；若存在恢复提示，记录提示内容。
|
||
4. 切换 Part、PartDesign、Sketcher、Draft、BIM、TechDraw、Mesh、FEM、CAM、Spreadsheet、Inspection、Robot、Assembly、Web、Python 等工作台入口，确认页面可进入且无白屏。
|
||
5. 改变视口尺寸，执行旋转、平移、缩放、适合视图，确认只影响显示，不改变模型数据。
|
||
|
||
## 4. 基础建模与 OCCT 几何验证
|
||
|
||
1. 新建文档，创建 Part Box，输入长度 2、宽度 3、高度 4，应用并重算。
|
||
2. 检查属性值和模型树对象名称；若界面提供体积信息，应为约 24。
|
||
3. 创建第二个基本体，移动或改变尺寸，确认两个对象同时显示且互不覆盖数据。
|
||
4. 执行撤销、重做，确认事务前后属性和模型树一致。
|
||
5. 选择对象并删除，再撤销删除；确认选择状态、树节点和视口同步。
|
||
6. 对可用的布尔、变换、复制、链接、分组命令各执行一次，确认结果来自 WASM 返回的几何/文档数据，而不是前端生成的替代几何。
|
||
|
||
## 5. 文档、属性与事务
|
||
|
||
1. 在模型树选择对象，逐项查看属性；修改长度、角度、颜色、可见性和标签。
|
||
2. 点击应用/重算，确认修改后的值保留；取消编辑，确认未提交值不污染文档。
|
||
3. 使用复制、剪切、粘贴、删除、选择全部、依赖关系、表达式（如界面提供）并记录结果。
|
||
4. 连续执行三次修改后逐级撤销，再逐级重做，确认事务顺序正确。
|
||
5. 在两个文档之间切换，确认属性面板始终对应当前活动文档。
|
||
|
||
## 6. 文件导入、导出、保存与重开
|
||
|
||
1. 导入示例 STEP 文件，等待 Worker 返回网格，确认模型树对象出现、视口有三角网格且无 NaN/空白。
|
||
2. 依次尝试项目支持的 FCStd、STEP、IGES、BREP、STL、OBJ、DXF、IFC 等格式；对不支持格式应显示明确错误，不得静默成功。
|
||
3. 保存为 FCStd，确认下载文件或 OPFS 文件列表出现。
|
||
4. 修改模型后再次保存，确认文件大小/修改时间变化；关闭文档并重新打开，确认对象数量、标签和关键属性恢复。
|
||
5. 导出 STL/网格格式后，用外部查看器检查文件可读；再次导入并比较包围盒、面数或体积（允许记录格式误差）。
|
||
6. 浏览器刷新后从 OPFS 选择文档打开，确认持久化恢复；清理站点数据后应明确提示文档已不存在。
|
||
|
||
## 7. 模型树、链接与结构
|
||
|
||
1. 创建 Part、VarSet 或等效结构对象，确认树层级、Tip 和选择分组正确。
|
||
2. 创建对象链接/子链接，替换链接目标，再解除链接；检查事务、树显示和视口结果。
|
||
3. 执行分组、解组、克隆/取消克隆（模块提供时），确认原对象和新对象的生命周期明确。
|
||
4. 在结构操作后保存、重开，确认链接关系没有变成空引用。
|
||
|
||
## 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、取消与错误恢复
|
||
|
||
1. 发起一个导入或重算操作，操作未完成前点击取消；确认界面回到可操作状态。
|
||
2. 重复提交相同请求，确认不会产生重复对象或重复事务。
|
||
3. 输入空文件、损坏文件、无效尺寸和不存在路径，确认返回可理解错误码/消息。
|
||
4. 错误后立即执行一次正常 Box 创建或打开已有文档，确认 Worker 和 WASM 实例可继续工作。
|
||
5. 观察长任务期间页面仍可切换文档；若业务规定串行，应显示忙碌状态而非无限等待。
|
||
|
||
## 10. 显示与数据一致性
|
||
|
||
1. 改变颜色、透明度、可见性和视图模式，确认只改变 Three.js 显示对象。
|
||
2. 隐藏/显示对象后保存并重开，按产品定义检查可见性是否持久化。
|
||
3. 选中模型树节点，确认视口高亮对象与节点一致；删除后不得残留孤立网格。
|
||
4. 检查大模型加载时内存和帧率，记录浏览器 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 须有明确修复计划和负责人。
|