docs(plans): 记录 K87 下拉刷新完成后回弹

docs/plans/2026-10-21-K87-pull-to-refresh-hold.md

@@ -0,0 +1,47 @@
+# K87 下拉刷新完成后回弹实施计划
+
+## 目标
+
+将全局 `AppPullToRefresh` 改为刷新完成前保持下拉高度：松手达到阈值后内容停在 56px，显示“正在刷新”，`onRefresh` 完成后再用 200ms easeOut 回弹到 0。
+
+## 根因
+
+- 当前下拉位移主要由 `BouncingScrollPhysics` 的系统 overscroll 提供。
+- 松手后滚动位置立即执行系统回弹，组件只保留一个小指示器。
+- 刷新期间没有独立的内容保持位移，因此无法维持下拉状态。
+
+## 范围
+
+- ReelShort `lib/core/widgets/app_pull_to_refresh.dart`
+- ReelShort `test/core/app_pull_to_refresh_test.dart`
+- FruitServer `docs/plans/PROGRESS.md`
+
+## 实现计划
+
+1. 将 `AppPullToRefresh.physics` 从 Bouncing 改为 Clamping，阻止系统 overscroll 自行产生内容位移。
+2. 使用 `AnimationController` 和 `Transform.translate` 统一控制内容位移；pull/armed 使用当前拖动距离，refreshing 固定 56，完成后回 0。
+3. 松手达到阈值后，200ms easeOut 将当前距离过渡到 56；刷新期间忽略滚动通知并通过 `IgnorePointer` 阻止重复下拉。
+4. `onRefresh` 完成后以 200ms easeOut 回到 0；指示器透明度跟随位移回弹淡出，结束后状态为 idle。
+5. 检查全部 11 个使用方均传入 `AppPullToRefresh.physics`，保证全局组件行为一致。
+
+## 测试计划
+
+- 使用挂起的 `Completer` 模拟刷新未完成。
+- 松手瞬间断言内容仍高于 hold，200ms 后稳定为 56，再等待 300ms 仍保持 56。
+- 断言刷新状态显示 `CircularProgressIndicator` 与 `Refreshing…`。
+- 刷新中再次下拉，断言 `onRefresh` 调用数仍为 1、offset 仍为 56。
+- 完成 `Completer` 后断言 offset 回到 0、刷新指示器消失。
+
+## 风险与处理
+
+- 改为 Clamping 后不再依赖平台 overscroll 提供下拉视觉；内容位移完全由组件控制，避免双倍移动。
+- 刷新期间阻止列表交互，避免用户手势破坏保持高度。
+- 组件卸载时动画控制器会取消动画；异步刷新完成后仅在 mounted 时执行回弹收尾。
+
+## Git
+
+- ReelShort 从 `develop` 创建 `feat/pull-to-refresh-hold`。
+- 提交：`feat(ui): 下拉刷新完成后才回弹`。
+- 作者：`Zhou Weidong <502333560@qq.com>`。
+- `--no-ff` 合回 `develop` 并 push，不使用 force push，不执行 `git add -A`。
+- FruitServer 追加 PROGRESS 留痕；不安装真机，完成后等待用户验收。

docs/plans/PROGRESS.md

@@ -23592,3 +23592,27 @@ $ flutter test --no-pub
 ```
 
 解读：ReelShort 静态检查零告警，514 条测试全部通过。未安装真机，等待用户验收。
+
+## 2026-10-21 ReelShort：K87 下拉刷新完成后回弹
+
+- 功能分支：`feat/pull-to-refresh-hold`，从 ReelShort develop `d39d8d4` 创建。
+- 功能提交：`45e8707 feat(ui): 下拉刷新完成后才回弹`。
+- develop 合并提交：`01bef7f merge: 合并 K87 下拉刷新完成后回弹`，已推送 `d39d8d4..01bef7f`。
+- `AppPullToRefresh.physics` 从 Bouncing 改为 Clamping，系统不再自行提供 overscroll 位移；内容下拉统一由 `AnimationController` 和 `Transform.translate` 控制，避免刷新保持与系统回弹叠加。
+- 松手达到阈值后，当前位移用 200ms easeOut 过渡到固定 hold 56px；刷新 pending 期间保持 56px，忽略滚动通知并通过 `IgnorePointer` 阻止重复手势。
+- `onRefresh` 完成后用 200ms easeOut 回弹到 0，指示器透明度随位移降低并淡出，最终状态恢复 idle；刷新中固定显示进度圈与 `refreshingLabel`。
+- 已核对 11 个使用方均传入 `AppPullToRefresh.physics`，剧场、榜单、钱包、收藏、下载、通知、新剧、观看记录等页面自动生效。
+- 测试使用挂起 Completer 覆盖：松手瞬间 offset 高于 56、200ms 后稳定在 56、pending 再等 300ms 仍保持 56、刷新中重复下拉不增加调用且不改变保持高度、完成后回 0 且指示器消失。
+
+门禁原始输出：
+
+```text
+$ dart analyze lib test
+Analyzing lib, test...
+No issues found!
+
+$ flutter test --no-pub
+00:49 +514: All tests passed!
+```
+
+解读：ReelShort 静态检查零告警，514 条测试全部通过。未安装真机，等待用户验收。