2026-05-21-00-58-25 增加WebGL降级并更新测试文档

工程分析/经验记录.md

@@ -1441,3 +1441,21 @@ C. 解决问题方案
 D. 后续如何避免问题
 
 所有文件导入、导出、保存这类长操作失败时，都要在主操作路径旁保留显眼错误卡，不能只写入边栏或短暂 toast。后端对 4xx/5xx 的可恢复业务错误应记录足够上下文，尤其是项目 ID、导入类型、文件数量和原始异常消息，方便从用户截图快速定位。
+
+## 2026-05-21-00-58-25 三维视图需要 WebGL 降级保护且软著截图要强制视口
+
+A. 具体问题
+
+自动化浏览器回归进入逆向工作区时，Headless Chrome 在默认图形参数下无法创建 WebGL 上下文，`FusionThreeView` 直接抛出 Three.js 渲染错误，导致工作区组件崩溃。软著截图第一次生成时浏览器实际截图尺寸为 1680x963，与素材清单中约定的 1680x1050 不一致。
+
+B. 产生问题原因
+
+三维融合视图和 STL 切面预览此前默认 `new THREE.WebGLRenderer` 一定成功，没有捕获无 GPU、远程桌面、浏览器禁用硬件加速或 Headless 图形实现异常。截图脚本只设置了 Chrome 窗口大小，没有通过 DevTools `Emulation.setDeviceMetricsOverride` 强制页面视口，因此截图高度受 Headless 浏览器可用视区影响。
+
+C. 解决问题方案
+
+在 `FusionThreeView` 与 `CutSectionPreview` 初始化 WebGLRenderer 时增加 try/catch，创建失败时显示三维视图不可用提示，并保留二维 DICOM、逆向分割映射、保存和导出等功能继续可用。软著截图改用 Chrome Headless + SwiftShader WebGL 参数，并通过 DevTools 强制 1680x1050 视口；截图后用文件尺寸、章节图片数量、Word drawing 数量和代码汇总行数做校验。
+
+D. 后续如何避免问题
+
+所有 WebGL/Three.js 视图都应把渲染器创建失败视为可恢复状态，不能让单个三维画布拖垮整个工作区。自动生成软著或验收截图时，除了设置浏览器窗口，还必须设置设备视口，并在生成后校验图片尺寸、非空像素、章节数量、图片引用和 docx 内嵌图片位置数量。