From f1c11df5d5bde5e8b7e4e7f13a08c4989098be5c Mon Sep 17 00:00:00 2001
From: Zhou Weidong <502333560@qq.com>
Date: Wed, 21 Oct 2026 10:25:10 +0800
Subject: [PATCH] =?UTF-8?q?docs(plans):=20=E7=95=99=E7=97=95=20K79=20?=
 =?UTF-8?q?=E8=BF=9B=E5=BA=A6=E6=8B=96=E5=8A=A8=E9=98=B2=E9=97=AA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/plans/INBOX.md    | 71 +++++++++++++++++++++++++++---------------
 docs/plans/PROGRESS.md | 29 +++++++++++++++++
 2 files changed, 75 insertions(+), 25 deletions(-)

diff --git a/docs/plans/INBOX.md b/docs/plans/INBOX.md
index aea96b5..1302fa9 100644
--- a/docs/plans/INBOX.md
+++ b/docs/plans/INBOX.md
@@ -1,44 +1,65 @@
 # INBOX
 
-## [已处理] K78-A 底部导航图标与文字放大
+## [已处理] K79-A 拖动进度条闪一下（加载态闪烁）修复
 
-### 需求
+### 现象
 
-底部导航（首页/剧场/创作/我的，浅色与首页 feed 深色共用 `AppBottomNav`）的图标和文字偏小，
-整体放大一档。
+拖动 / 点按进度条 seek 之后，进度条会闪一下：整条正常进度条被加载轨道替换一瞬，再切回来。
 
-### 现状
+### 根因
 
-`lib/core/theme/app_dimens.dart`：
+K77-A 引入的加载态判定是「`isBuffering` 为 true 就切成 `LoadingProgressTrack`」：
 
-- `navIcon = 20`
-- `navLabel = 10`
-- `navHeight = 64`
+- `lib/pages/player/widgets/seek_progress_bar.dart`：`loading = !isInitialized || isBuffering`
+- `lib/pages/player/widgets/home_feed_overlay_parts.dart`：`if (!value.isInitialized || value.isBuffering) return _loadingTrack();`
 
-`AppBottomNav` 里图标与文字间距 `SizedBox(height: 2)`。
+seek 本身会触发播放器短暂的 buffering（几百毫秒），于是拖动过程中/松手瞬间
+进度条被替换成加载轨道，表现为「闪一下」；拖动时也没有排除加载态。
 
-### 改动
+### 修复方案
 
-1. `lib/core/theme/app_dimens.dart`
-   - `navIcon`：`20` → `24`
-   - `navLabel`：`10` → `12`
-   - `navHeight`：`64` → `68`
-2. `lib/core/widgets/app_bottom_nav.dart`
-   - 图标与文字间距 `2` → `3`，其余布局不变（四等分、选中态主题色、深色/浅色两种底不变）
-3. `test/theme/app_dimens_test.dart`
-   - 断言同步为 `navLabel = 12`、`navHeight = 68`（如断言了 `navIcon` 一并更新）
+1. **拖动期间永不显示加载态**：只要处于拖动预览（`_previewFraction != null` / `_preview != null`），
+   一律渲染正常进度条与滑块。
+2. **缓冲态加去抖**：buffering 需要持续 **350ms** 以上才切到加载轨道；
+   恢复播放 / 缓冲结束立即取消定时器并切回正常进度条。
+   `!isInitialized`（首帧没出来）仍然立即显示加载轨道，不去抖。
+
+### 实现
+
+1. `lib/pages/player/widgets/seek_progress_bar.dart`
+   - `_SeekProgressBarState` 增加：
+     - `Timer? _bufferTimer; bool _buffering = false;`
+     - 监听 `widget.valueListenable`（`initState` / `didUpdateWidget` 处理控制器切换 / `dispose` 移除）
+     - 监听回调里：未初始化 → 直接置 buffering；buffering 持续 350ms 才 `setState(_buffering = true)`；
+       否则取消定时器并复位
+   - `_buildTrack`：`final scrubbing = _previewFraction.value != null;`
+     `final loading = !scrubbing && (!video.isInitialized || _buffering);`
+2. `lib/pages/player/widgets/home_feed_overlay_parts.dart` `_FeedProgressBarState`
+   - 同样的 `Timer + _buffering` 去抖；监听 `widget.controller`
+   - `build` 里：`final scrubbing = _preview != null;`
+     `if (source == null || (!scrubbing && _buffering)) return _loadingTrack();`
+     `source == null`（控制器都没有）仍立即显示加载轨道
+   - 加载态期间不响应拖动（`GestureDetector` 的 onHorizontalDrag* 传 null）
+
+### 测试
+
+- `test/playback/seek_progress_bar_test.dart`：
+  - 原「buffering 立即出现 `progress-loading`」用例改为 `pump(400ms)` 后出现
+  - 新增：`pump(200ms)` 时仍是 `Slider`（去抖生效）
+  - 新增：拖动中（`onChangeStart` 后）即使 buffering 也不出现 `progress-loading`
+- 首页 feed 进度条如有相关用例，同样按去抖（>350ms）与拖动中不切加载态调整
 
 ### 验收
 
-- 空间检查：`navHeight 68` 下 24 图标 + 3 间距 + 12 文字垂直居中不溢出
-- 门禁：`dart analyze lib test` 零告警、`flutter test` 全过、`flutter build apk --debug` 成功
+- 门禁：`dart analyze lib test` 零告警、`flutter test` 全过、`flutter build apk --debug` 成功。
+- 真机自查：连续拖动进度条，进度条与滑块不再闪成加载态；真正卡顿（>350ms）仍会显示加载轨道。
 
 ### Git
 
-- 从 `develop` 拉 `feat/bottom-nav-larger`。
-- 提交：`feat(nav): 底部导航图标与文字放大`，作者 `Zhou Weidong <502333560@qq.com>`。
-- `--no-ff` 合回 `develop` 并 push；`FruitServer/docs/plans/PROGRESS.md` 追加 K78-A 留痕。
+- 从 `develop` 拉 `fix/progress-scrub-flicker`。
+- 提交：`fix(player): 修复拖动进度条时加载态闪烁`，作者 `Zhou Weidong <502333560@qq.com>`。
+- `--no-ff` 合回 `develop` 并 push；`FruitServer/docs/plans/PROGRESS.md` 追加 K79-A 留痕。
 
 ### 约束
 
-- 全程中文；禁止 `git add -A`；只动导航尺寸与相关断言；完成后停住等待验收。
+- 全程中文；禁止 `git add -A`；不改其它播放逻辑；完成后停住等待验收。
diff --git a/docs/plans/PROGRESS.md b/docs/plans/PROGRESS.md
index 6b610f0..117b884 100644
--- a/docs/plans/PROGRESS.md
+++ b/docs/plans/PROGRESS.md
@@ -22710,6 +22710,35 @@ Running Gradle task 'assembleDebug'...
 
 解读：静态检查零告警，486 条测试全部通过，debug APK 构建成功。真机验收由用户执行。
 
+## 2026-10-21 ReelShort：K79-A 拖动进度条加载态闪烁修复
+
+- 前置状态：K78-A 已完成并合并，develop 合并提交 `7270863`。
+- 分支：`fix/progress-scrub-flicker`
+- 功能提交：`1993ff1 fix(player): 修复拖动进度条时加载态闪烁`
+- develop 合并提交：`c06a67c merge: 合并 K79-A 进度拖动防闪`，已推送 `7270863..c06a67c`。
+- 全屏 `SeekProgressBar` 与首页 feed `_FeedProgressBar` 均增加 350ms buffering 去抖；短暂 buffering 不再切换加载轨道，缓冲结束立即取消计时器并恢复。
+- 未初始化状态仍立即显示 `progress-loading`；`_previewFraction` / `_preview` 存在时始终保留正常进度条和滑块，不显示加载态。
+- 控制器切换时正确移除旧监听、取消计时器并监听新控制器，销毁时移除监听并清理计时器；首页 feed 加载态期间禁用拖动回调。
+- 测试覆盖 200ms 短暂缓冲仍显示 Slider、400ms 持续缓冲显示加载轨道、拖动中持续 buffering 仍保留 Slider，以及首页 feed 的去抖和拖动保护。
+
+门禁原始输出：
+
+```text
+$ dart analyze lib test
+Analyzing lib, test...
+No issues found!
+
+$ flutter test
+01:01 +488: All tests passed!
+
+$ flutter build apk --debug
+Running Gradle task 'assembleDebug'...
+   13.3s
+✓ Built build/app/outputs/flutter-apk/app-debug.apk
+```
+
+解读：静态检查零告警，488 条测试全部通过，debug APK 构建成功。真机验收由用户执行。
+
 ## 2026-10-21 ReelShort：K78-A 底部导航图标与文字放大
 
 - 前置状态：K77-A 已完成并合并，develop 合并提交 `0ba6ea9`。