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

工程分析/经验记录.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. 后续如何避免问题：耗时任务即使暂时没有后端实时进度，也要用单向推进的阶段式进度条，避免使用反复跳动的加载条表达处理进度。