7.6 KiB
经验记录
本文件用于记录每次执行中出现的关键问题和解决方案。
2026-05-18-17-40-02 Web 导丝分割系统第一版
1. pytest 无法导入本地 backend 包
A. 具体问题：执行 pytest -q 时，tests/test_api.py 和 tests/test_segmentation.py 报 ModuleNotFoundError: No module named 'backend'。
B. 产生问题原因：项目是从空目录新建，尚未安装为 Python 包；pytest 启动时没有稳定地把项目根目录放入 pythonpath。
C. 解决问题方案：新增 pytest.ini，配置 pythonpath = . 和 testpaths = tests。
D. 后续如何避免问题：从零构建 Python 项目时同步添加 pytest 配置，或使用标准包管理配置声明测试路径。
2. scikit-image 0.26 参数变更警告
A. 具体问题：remove_small_objects 使用 min_size 时测试出现 FutureWarning。
B. 产生问题原因：当前环境的 scikit-image 版本将 min_size 标记为废弃参数，并引入 max_size 表达“移除小于等于该面积的对象”。
C. 解决问题方案：将 remove_small_objects(binary, min_size=...) 改为 remove_small_objects(binary, max_size=...)。
D. 后续如何避免问题：固定依赖版本后仍要关注测试警告；图像处理库升级时优先查看函数签名和文档。
3. 融合模式首帧过分割
A. 具体问题：视频第 0 帧没有前帧，融合模式覆盖率一度达到约 22%，明显偏宽。
B. 产生问题原因：时序差分在无前帧时退化为 Hessian，融合投票逻辑对无前帧使用了一票通过，导致边缘形态学噪声被并入。
C. 解决问题方案：融合模式统一使用两票通过，低响应时才回退到一票；同时将边缘形态学改成暗线候选约束下的边缘检测。
D. 后续如何避免问题：视频算法要单独检查首帧、丢帧和单图退化路径；融合策略必须记录每个子方法的置信约束。
2026-05-18-17-55-29 运行确认与演示视频录制
1. Playwright 安装下载卡住
A. 具体问题：尝试安装 playwright==1.55.0 用于浏览器录屏时，pip 长时间停留在大型 wheel 下载阶段，没有继续输出。
B. 产生问题原因：Playwright 包体积较大，当前网络下载速度或连接稳定性不足；继续等待会影响本次“确保可运行”的收口。
C. 解决问题方案：终止该安装进程，改用系统已有 google-chrome --headless 截取首页，并使用当前已安装的 OpenCV 将真实页面截图和真实 API 分割结果合成为演示 mp4。
D. 后续如何避免问题：演示录制优先复用本机已有工具；只有确实需要完整浏览器交互录屏时，再单独安装 Playwright 并预留下载时间。
2026-05-18-19-06-50 网页端工作台增强
1. CSS 覆盖 hidden 导致初始预览控件显示
A. 具体问题：Chrome headless 截图发现初始页面里本应隐藏的视频控件和图像预览同时显示，破坏首屏布局。
B. 产生问题原因：CSS 中对 #videoPreview、#imagePreview 设置了 display: block，其选择器优先级覆盖了浏览器对 hidden 属性的默认 display: none。
C. 解决问题方案：在全局 CSS 中增加 [hidden] { display: none !important; }，确保所有使用 hidden 的状态元素都能可靠隐藏。
D. 后续如何避免问题：前端页面涉及显隐状态时，必须用 headless 截图检查初始状态；如果自定义了 display 样式，需要显式保护 [hidden]。
2026-05-18-19-19-36 加载样例控制台提示处理
1. favicon.ico 404 干扰问题判断
A. 具体问题：点击“加载样例”后，浏览器控制台出现 /favicon.ico 404，同时还有 Unchecked runtime.lastError。
B. 产生问题原因：项目没有提供 /favicon.ico，浏览器会默认请求该资源并记录 404；runtime.lastError 更常见于浏览器扩展消息通道关闭，通常不是普通网页代码产生。
C. 解决问题方案：后端增加 /favicon.ico 响应，前端为“加载样例”增加明确的成功/失败状态提示和异常捕获。
D. 后续如何避免问题：网页端交付时补齐 favicon、状态提示和错误处理；遇到 runtime.lastError 时优先用无痕模式或禁用扩展排查来源。
2026-05-18-19-31-18 原始媒体查看入口增强
1. 文件加载后的原始内容查看入口不够明确
A. 具体问题：用户加载样例或上传视频/图像后，希望在“预览与结果”区域明确查看原始视频，否则不容易确认当前已加载内容。
B. 产生问题原因：页面虽然已有内嵌预览区域，但缺少显式的“查看原始视频/图像”操作入口，大尺寸查看也不方便。
C. 解决问题方案：在“预览与结果”标题区新增按文件类型切换文案的按钮；加载视频时显示“查看原始视频”，加载图像时显示“查看原始图像”；点击后打开原始媒体弹窗。
D. 后续如何避免问题：输入数据、处理中结果、最终结果应分别提供清晰入口，尤其是医学影像类工具需要让用户随时核对原始输入。
2026-05-18-19-37-10 原始视频与结果同级分栏
1. 原始媒体入口层级不符合用户预期
A. 具体问题：用户希望“查看原始视频”和“预览与结果”是同一级，而不是把原始视频查看作为“预览与结果”标题区里的按钮。
B. 产生问题原因：上一版将原始媒体查看入口作为辅助操作放在结果区标题右侧，信息架构上仍然偏向“结果主导”，不符合用户希望的左右对照工作流。
C. 解决问题方案：将右侧工作区拆成左右两个 workspace-pane：左侧固定展示原始视频/图像，右侧展示分割进度、摘要和结果帧；保留“放大查看”作为左侧面板内的辅助操作。
D. 后续如何避免问题：医学影像交互页面应优先考虑“原始输入”和“算法输出”并列对照，而不是把原始输入藏在结果区域的附属操作中。
2026-05-18-19-41-29 样例视频浏览器不显示画面
1. 样例视频控件显示但画面不渲染
A. 具体问题：用户点击“加载样例”后，左侧“查看原始视频”出现视频控件，但看不到原始视频画面。
B. 产生问题原因：内置样例视频由 OpenCV 直接写出，编码为 mpeg4/mp4v；Chrome 对这种 MP4 兼容性不如 H.264 稳定，可能只显示控件不显示画面。
C. 解决问题方案：修改样例生成脚本，生成后用 ffmpeg 转码为 libx264、yuv420p、faststart MP4；前端视频加载后调用 load() 并在 metadata 加载后轻微 seek 到 0.1s。
D. 后续如何避免问题：面向网页播放的样例视频统一转为 H.264/yuv420p，并用 Chrome 实际播放或截图验证，而不是只验证 OpenCV 能读取。
2026-05-18-19-46-56 样例视频旧缓存处理
1. 修复编码后用户仍看到黑色视频
A. 具体问题：样例视频已转为 H.264 后，用户点击“加载样例”仍然反馈左侧原始视频没有画面。
B. 产生问题原因：实测 Chrome 自动点击流程可以看到画面，视频元素 readyState=4 且 videoWidth/videoHeight 正常；用户端仍异常更可能是浏览器继续使用旧 mp4v 样例缓存。
C. 解决问题方案：后端 /api/samples 返回带 mtime_ns 的版本化 URL；前端加载样例时追加时间戳，并使用 fetch(..., { cache: "reload" }) 强制绕过旧缓存。
D. 后续如何避免问题：静态样例、模型文件、前端资源发生兼容性修复时，URL 必须版本化，避免用户浏览器继续使用旧缓存。