2026-05-18-19-56-47 重构双视频同步与单帧对比

工程分析/实现方案-2026-05-18-19-56-47.md

@@ -0,0 +1,48 @@
+# 实现方案
+
+开始时间：2026-05-18-19-56-47
+
+## 后端改造
+
+1. 视频分割返回时间映射
+   - 在 `_process_video` 中读取源视频 `fps`、总帧数、时长。
+   - 每个返回帧增加：
+     - `source_time`：源视频中的时间。
+     - `result_time`：结果视频中的时间。
+     - `result_index`：结果视频内部帧序号。
+   - 返回 `source_fps`、`result_fps`、`duration`、`result_duration`。
+
+2. 新增单帧多方法对比接口
+   - `POST /api/compare-frame`
+   - 参数：文件、`frame_index`、`sensitivity`。
+   - 后端定位到对应帧和上一帧，对该帧运行 `compare_frame`，返回多方法图片结果。
+
+## 前端改造
+
+1. 双视频区域
+   - 左侧：原始视频。
+   - 右侧：结果视频。
+   - 右侧标题改为“预览与结果视频”。
+
+2. 视频同步
+   - 维护 `currentFrame` 和后端返回的时间映射。
+   - 点击下方帧列表时同时 seek 原始视频与结果视频。
+   - 用户 seek/play/pause 任一视频时同步另一个视频，使用锁避免递归触发。
+
+3. 下方帧列表
+   - 新增“预览与结果查看”区域。
+   - 复用现有结果图片卡片；点击后设置当前帧并同步两个视频。
+
+4. 多方法对比
+   - 控制面板中移除方法卡片里的“多方法对比”，改为运行按钮下方的独立按钮。
+   - 默认禁用。
+   - 分割完成且当前帧存在时启用。
+   - 点击后调用 `/api/compare-frame`，在弹窗中显示当前帧多方法对比。
+
+5. 进度条
+   - 移除 CSS 无限动画。
+   - 使用 JS 设置固定阶段进度：准备、上传处理、生成结果、完成。
+
+## 注意
+
+结果视频目前由抽样帧组成，因此同步采用返回的 `source_time` 与 `result_time` 映射，并在用户拖动时选择最近的分割帧。

工程分析/测试方案-2026-05-18-19-56-47.md

@@ -0,0 +1,42 @@
+# 测试方案
+
+开始时间：2026-05-18-19-56-47
+
+## 自动化测试
+
+- `pytest -q`
+- 更新 API 测试：
+  - `/api/samples` 返回版本化样例。
+  - `/api/segment` 视频结果包含 `source_time` 和 `result_time`。
+  - `/api/compare-frame` 可以返回多方法对比结果。
+
+## 运行验证
+
+- `curl -s http://127.0.0.1:8001/api/health`
+- 使用样例视频调用 `/api/segment`。
+- 使用样例视频调用 `/api/compare-frame`。
+- Chrome DevTools Protocol 打开页面、加载样例、运行分割，检查：
+  - 结果视频元素出现。
+  - 帧列表出现。
+  - 多方法对比按钮启用。
+
+## 手工验证
+
+1. 打开 `http://192.168.3.11:8001/`。
+2. 点击“加载样例”。
+3. 点击“运行分割”。
+4. 右侧应显示“预览与结果视频”的视频播放器。
+5. 下方“预览与结果查看”出现结果帧列表。
+6. 点击任一结果帧，原始视频和结果视频同步跳转。
+7. 点击“多方法对比”，查看当前帧的多方法结果。
+
+## 执行结果
+
+- `python3 -m compileall backend tests`：通过。
+- `node --check frontend/app.js`：通过。
+- `pytest -q`：5 passed。
+- `curl http://127.0.0.1:8001/api/health`：服务返回 `ok`。
+- `/api/segment` 使用内置样例视频：返回 H.264 结果视频、`source_time`、`result_time`、`result_index`。
+- `/api/compare-frame` 使用内置样例视频第 24 帧：返回 4 种方法结果。
+- Chrome headless 页面流程：加载样例、运行分割、结果视频展示、12 个结果帧、多方法对比 4 张卡片均通过。
+- Chrome headless 双向同步验证：源视频 seek 到 2 秒后结果视频跳到最近处理帧 0.625 秒；结果视频 seek 到 0.375 秒后源视频跳到对应源帧 1.25 秒。

工程分析/经验记录.md

@@ -117,3 +117,25 @@ B. 产生问题原因：实测 Chrome 自动点击流程可以看到画面，视
 C. 解决问题方案：后端 `/api/samples` 返回带 `mtime_ns` 的版本化 URL；前端加载样例时追加时间戳，并使用 `fetch(..., { cache: "reload" })` 强制绕过旧缓存。
 
 D. 后续如何避免问题：静态样例、模型文件、前端资源发生兼容性修复时，URL 必须版本化，避免用户浏览器继续使用旧缓存。
+
+## 2026-05-18-19-56-47 双视频同步与当前帧多方法对比
+
+### 1. 结果视频与原始视频时间轴不一致
+
+A. 具体问题：结果视频由抽帧后的叠加帧组成，播放时长和原始视频不同；如果直接用同一个 `currentTime` 同步，会跳到错误画面。
+
+B. 产生问题原因：后端按 `frame_stride` 抽取关键帧，结果视频用固定 `result_fps` 写出，源视频时间轴与结果视频时间轴天然不等长。
+
+C. 解决问题方案：后端为每个结果帧返回 `source_time`、`result_time`、`result_index`；前端点击帧卡片或拖动任一视频时，使用最近结果帧的时间映射同步另一个视频。
+
+D. 后续如何避免问题：凡是结果媒体来自抽样、降帧、裁剪或重编码，都必须在 API 中显式返回源时间与结果时间映射，前端不要假设两个视频时长一致。
+
+### 2. 进度条循环动画造成任务状态误导
+
+A. 具体问题：“正在上传、抽帧并执行导丝分割”的进度条一直往复跳动，看起来像任务卡住或没有真实进度。
+
+B. 产生问题原因：旧样式使用 CSS 无限动画模拟进度，没有和前端请求阶段绑定。
+
+C. 解决问题方案：移除无限动画，改为 JavaScript 按阶段设置固定进度：上传准备、抽帧、生成掩膜和叠加视频、整理结果、完成或失败。
+
+D. 后续如何避免问题：耗时任务即使暂时没有后端实时进度，也要用单向推进的阶段式进度条，避免使用反复跳动的加载条表达处理进度。

工程分析/需求分析-2026-05-18-19-56-47.md

@@ -0,0 +1,23 @@
+# 需求分析
+
+开始时间：2026-05-18-19-56-47
+
+## 用户目标
+
+用户希望将网页端工作台调整为以视频对照为核心的交互：
+
+1. “正在上传、抽帧并执行导丝分割”的进度条不要一直循环跳动。
+2. “预览与结果”改为“预览与结果视频”，其中内容应是视频。
+3. 下方增加“预览与结果查看”，放置当前图片帧列表；选择某一帧时，原始视频和结果视频跳到对应位置。
+4. 原始视频和预览结果视频同步，调整一个另一个一起调整。
+5. “多方法对比”移动到“运行分割”按钮下方；它只针对当前所在帧有效。运行后在结果视频右侧出现可用的“多方法对比”按钮，点击查看当前帧的多方法对比；原始视频右侧不要显示“视频 · 多方法对比”。
+
+## 验收标准
+
+- 运行分割时进度条为确定式推进，不再循环动画。
+- 右侧面板标题为“预览与结果视频”，主内容是结果视频播放器。
+- 下方有“预览与结果查看”帧列表。
+- 点击帧列表项后，原始视频与结果视频跳到对应位置。
+- 拖动或播放其中一个视频，另一个视频同步。
+- 左侧控制面板中“多方法对比”位于“运行分割”按钮下方。
+- 分割完成前，多方法对比按钮不可用；分割完成并选中帧后，结果视频右侧按钮亮起。