2026-05-18-19-46-56 强制刷新样例视频缓存

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

@@ -0,0 +1,30 @@
+# 需求分析
+
+开始时间：2026-05-18-19-46-56
+
+## 用户反馈
+
+用户访问 `http://192.168.3.11:8001/` 后点击“加载样例”，左侧“查看原始视频”仍然看不到画面，希望我们自己实测并解决。
+
+## 实测结果
+
+使用 Chrome DevTools Protocol 自动打开页面、点击“加载样例”后，视频元素状态如下：
+
+- `readyState=4`
+- `error=null`
+- `videoWidth=640`
+- `videoHeight=420`
+- `currentTime=0.1`
+
+截图 `/tmp/isiseg_clicked_sample.png` 中可以看到样例视频画面。
+
+## 问题判断
+
+服务端样例视频已修为 H.264，但用户浏览器仍可能命中过去的旧 `mp4v` 样例缓存。需要让样例资源 URL 版本化，并让前端加载样例时强制绕过缓存。
+
+## 本轮目标
+
+- `/api/samples` 返回带版本参数的样例 URL。
+- 前端加载样例时追加时间戳并设置 `cache: "reload"`。
+- 保留 H.264 样例视频。
+- 重新验证点击样例后的真实浏览器显示状态。