docs: 更正草原指南倍速播放缓冲死锁

changelogs/2026-07/16_notice_grassland_guide_4k_playback_buffering.md

@@ -8,6 +8,11 @@
 >
 > 本次后端接口、字段和 OSS 地址均无变化
 
+> [!IMPORTANT]
+> 2026-07-16 线上验证发现：原通知中的“主动暂停并等待固定缓冲秒数”会与浏览器原生媒体加载策略形成死锁，已经撤销。前端必须按独立更正通知
+> [`16_fix_grassland_guide_playback_buffer_deadlock.md`](./16_fix_grassland_guide_playback_buffer_deadlock.md)
+> 处理，不得再以 `8/15` 秒阈值阻塞播放或切换倍速。
+
 ## 1. 问题与诊断结论
 
 草原指南详情直接播放后端返回的 OSS 原始 MP4。正式环境真实 4K 样本的媒体参数为：
@@ -58,15 +63,16 @@ function getBufferAhead(video) {
 
 ### 2.3 `1x` 与倍速播放缓冲策略
 
-- 用户首次点击 `1x` 播放时，若前向缓冲不足 `8` 秒，先显示“正在缓冲”；达到 `8` 秒后再开始播放。
-- `1x` 播放过程中前向缓冲低于 `3` 秒时进入缓冲状态，恢复到 `8～10` 秒后继续播放。
-- 用户选择 `2x` 时，若前向缓冲不足 `15` 秒，先保持暂停并显示“正在缓冲”，达到 `15` 秒后再以 `2x` 播放。
-- `2x` 播放过程中前向缓冲低于 `5` 秒时进入缓冲状态，恢复到 `12～15` 秒后继续播放。
-- 原生播放器触发 `waiting` 或 `stalled` 时，无论当前倍速是多少，都进入统一缓冲流程并按当前 `playbackRate` 对应的恢复水位继续播放。
-- 用户主动暂停、拖动进度或离开页面时取消自动恢复，避免播放器违背用户操作。
-- `preload="auto"` 只是浏览器提示，不能单独保证缓冲量；必须以 `video.buffered` 的实际结果作为判断依据。
+- 用户点击播放时直接调用原生 `video.play()`，不得先暂停等待固定缓冲秒数。
+- 用户切换 `2x` 时只设置 `video.playbackRate = 2`，不得调用 `pause()`，也不得重新执行“初始缓冲门槛”。
+- `waiting` 事件只负责显示“正在缓冲”和记录诊断；不得在事件处理器内再次调用 `pause()`。
+- 保持原生播放请求后，浏览器会继续 Range 取流；数据恢复后通过 `playing` 事件关闭缓冲提示。
+- `stalled` 用于记录网络加载停滞；仅当仍有播放意图且 `readyState < HTMLMediaElement.HAVE_FUTURE_DATA` 时显示缓冲提示，不主动暂停。
+- `timeupdate` 只采集缓冲指标，不得因低于人为水位而主动暂停。
+- 用户主动暂停、拖动进度或离开页面时清除缓冲提示，避免与真实播放意图混淆。
+- `preload="auto"` 只是浏览器提示，不能强制浏览器预取指定秒数。
 
-阈值是针对当前约 `40 Mbps` 的 4K 原片给出的首轮参数。前端应按播放倍速集中定义为常量，便于根据真机数据调整，不要散落魔法值。
+`video.buffered` 用于诊断和观测，不再作为阻塞 `play()` 或切换倍速的硬门槛。简单的原生 `<video>` 无法保证“暂停后一定继续预取到 N 秒”；若业务将来要求确定性分片缓冲，需要另行评估 MSE/HLS 或 CDN，不应在原生 MP4 播放器中模拟。
 
 ### 2.4 记录卡顿证据
 
@@ -111,9 +117,9 @@ GET /admin/grassland-guide/public/videos/{videoId}/play
 
 - [ ] `<video>` 使用接口原始 `videoUrl`，并设置 `preload="auto"`。
 - [ ] 没有将完整 MP4 下载为 Blob。
-- [ ] 首次 `1x` 播放前按真实 `buffered` 结果预缓冲，播放中有低水位保护。
-- [ ] `2x` 播放前使用更高的预缓冲与恢复水位。
-- [ ] `waiting`/`stalled` 在 `1x` 和倍速播放下均进入统一缓冲恢复流程。
+- [ ] 首次 `1x` 播放不受固定缓冲秒数阻塞。
+- [ ] 切换 `2x` 不调用 `pause()`，不等待 `15` 秒缓冲。
+- [ ] `waiting`/`stalled` 只更新提示与日志，不主动暂停；`playing` 能可靠关闭提示。
 - [ ] 用户暂停、拖动和离开页面时不会被自动恢复播放。
 - [ ] 能区分并记录缓冲耗尽与设备解码掉帧。
 - [ ] 使用正式 4K 样本分别连续验证 `1x` 和 `2x`，记录等待次数、累计等待时长、最小前向缓冲和掉帧数。