docs(plans): 留痕 K63 播放器路由暂停修复

2026-10-20 19:25:44 +08:00
1 parent 0de7436baf
commit 0f477c6b15
@@ -1,56 +1,69 @@
 # INBOX

-## [已处理] K62-A 提交安卓桌面图标资源改造
+## [已处理] K63-A 首页 feed 跳转登录页时暂停播放

-### 背景
+### 现象

-安卓桌面图标此前使用「奶油色底 + 前景缩到 72% + inset 16%」的自适应图标配置，与设计源图
-`assets/icon/fruitshorts.png`（橙渐变 + 满版果篮 + 播放按钮）观感差距大：颜色发淡、元素偏小。
-已在本机重做全部图标资源并完成真机验证（应用信息页图标完整无裁切）。
+安卓端从首页 feed 点右侧「收藏 / 评论 / 喜欢」（未登录）→ 引导进入登录页 `AuthPage`，
+播放器没有暂停，画面和声音继续播；返回首页后也没有恢复/续播的判定。

-### 当前工作区改动（ReelShort 仓库，develop 分支，未提交）
+### 根因

-修改：
- `android/app/src/main/res/drawable-mdpi/ic_launcher_foreground.png`
- `android/app/src/main/res/drawable-hdpi/ic_launcher_foreground.png`
- `android/app/src/main/res/drawable-xhdpi/ic_launcher_foreground.png`
- `android/app/src/main/res/drawable-xxhdpi/ic_launcher_foreground.png`
- `android/app/src/main/res/drawable-xxxhdpi/ic_launcher_foreground.png`
- `android/app/src/main/res/mipmap-mdpi/ic_launcher.png`
- `android/app/src/main/res/mipmap-hdpi/ic_launcher.png`
- `android/app/src/main/res/mipmap-xhdpi/ic_launcher.png`
- `android/app/src/main/res/mipmap-xxhdpi/ic_launcher.png`
- `android/app/src/main/res/mipmap-xxxhdpi/ic_launcher.png`
- `android/app/src/main/res/mipmap-anydpi-v26/ic_launcher.xml`
+暂停由 `PlaybackSession._mayPlay = _visible && !_overlayOpen && _userWantsPlay` 控制，
+其中 `_visible = !_closed && _appResumed && _routeVisible`。

-新增：
- `android/app/src/main/res/mipmap-mdpi/ic_launcher_background.png`
- `android/app/src/main/res/mipmap-hdpi/ic_launcher_background.png`
- `android/app/src/main/res/mipmap-xhdpi/ic_launcher_background.png`
- `android/app/src/main/res/mipmap-xxhdpi/ic_launcher_background.png`
- `android/app/src/main/res/mipmap-xxxhdpi/ic_launcher_background.png`
+`_routeVisible` 只有这几处显式设置：`openDetail()`、`openSeriesAt()`、`showEpisodes()`、
+`PlayerLogic.dispose()`、`onPageUpdated()`。登录页是普通 `Navigator.push`（
+`lib/core/widgets/auth_gate.dart` → `openAuthPage`），没有任何一处通知播放器，
+于是 `_routeVisible` 一直为 true，继续播放。

-`ic_launcher.xml` 目标内容：
+### 方案：引入全局 RouteObserver

-```xml
-<?xml version="1.0" encoding="utf-8"?>
-<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
-  <background android:drawable="@mipmap/ic_launcher_background"/>
-  <foreground android:drawable="@drawable/ic_launcher_foreground"/>
-</adaptive-icon>
+1. 新增 `lib/core/navigation/app_route_observer.dart`：
+
+```dart
+// Author: fruit.com.cn
+
+import 'package:flutter/widgets.dart';
+
+/// 全局页面路由观察者：供播放器在路由被覆盖时暂停。
+final RouteObserver<PageRoute<dynamic>> appRouteObserver =
+    RouteObserver<PageRoute<dynamic>>();
 ```

-### 任务
+2. `lib/app.dart` 的 `MaterialApp` 增加 `navigatorObservers: [appRouteObserver]`。

-1. 从 `develop` 拉分支 `fix/android-launcher-icon`（当前工作区改动保留，直接带入分支）。
-2. 只提交上述 16 个资源文件，禁止 `git add -A`，禁止改动其它文件。
-3. 提交信息：`fix(android): 按设计源图重做桌面图标资源`。
-4. 门禁：`dart analyze lib test`、`flutter test`、`flutter build apk --debug` 全部通过。
-5. `--no-ff` 合并回 `develop` 并 push。
-6. 在 `FruitServer/docs/plans/PROGRESS.md` 留痕：分支名、commit、门禁结果。
+3. `lib/pages/player/player_view.dart` 的 `_PlayerPageState` 混入 `RouteAware`：
+   - `didChangeDependencies()`：`final route = ModalRoute.of(context);`
+     若 `route is PageRoute` 且尚未订阅，则 `appRouteObserver.subscribe(this, route)`（防重复订阅）
+   - `dispose()`：`appRouteObserver.unsubscribe(this)`
+   - `didPushNext()`：调 `logic.onRouteCovered()`
+   - `didPopNext()`：调 `logic.onRouteRevealed()`
+
+4. `PlayerLogic` 新增两个方法（放在 `onLifecycle` 附近）：
+   - `void onRouteCovered()`：`session.setRouteVisible(false); cancelScrub(); unawaited(saveCurrentProgress());`
+   - `void onRouteRevealed()`：`if (isMounted()) session.setRouteVisible(active);`
+   与 `openDetail()` / `openSeriesAt()` 已有的显式设置重复时同值，不应产生抖动。
+
+5. 覆盖场景验收：
+   - 首页 feed 未登录点收藏 / 评论 / 喜欢 → 进登录页：暂停；返回：恢复播放
+   - 首页 feed → 详情页（仍走 `openDetail` 的 overlay 逻辑）：暂停 / 返回恢复
+   - 全屏播放页 → 登录页：暂停 / 返回恢复
+   - 首页 feed 打开选集弹层（PopupRoute）：行为不变，仍由 `setOverlayOpen` 控制
+
+### 测试要求
+
+- `test/player/` 下补充用例：push 一个 `PageRoute` 后 `session` 不可播放、pop 后恢复；
+  首页 feed 进 `AuthPage` 暂停（可用 `RouteObserver` + 测试路由验证）。
+- 门禁：`dart analyze lib test` 零告警、`flutter test` 全过、`flutter build apk --debug` 成功。
+
+### Git
+
+- 从 `develop` 拉 `fix/player-pause-on-route`。
+- 提交：`fix(player): 路由覆盖时暂停播放`，作者 `Zhou Weidong <502333560@qq.com>`。
+- `--no-ff` 合回 `develop` 并 push；`FruitServer/docs/plans/PROGRESS.md` 追加 K63-A 留痕。

 ### 约束

- 全程中文；作者 `Zhou Weidong <502333560@qq.com>`。
- 不改 Dart 代码、不改其它资源。
+- 全程中文；禁止 `git add -A`；不改图标、启动图等无关资源。
 - 完成后停住，等待验收。
@@ -21385,6 +21385,34 @@ Running Gradle task 'assembleDebug'...

 解读：静态检查零告警，444 条测试全部通过，debug APK 构建成功。工作区原有 `pubspec.lock` 变更未纳入本批提交。真机验收由用户执行。

+## 2026-10-20 ReelShort：K63-A 首页 feed 跳转登录页时暂停播放
+
+- 前置状态：K62-A 已完成并合并，develop 合并提交 `911f13f`。
+- 分支：`fix/player-pause-on-route`
+- 功能提交：`699fd42 fix(player): 路由覆盖时暂停播放`
+- develop 合并提交：`210ccc9 merge: 合并 K63-A 首页 feed 跳转登录页暂停播放`，已推送。
+- 新增全局 `appRouteObserver` 并挂到 `MaterialApp.navigatorObservers`；`PlayerPage` 通过 `RouteAware` 防重复订阅当前 `PageRoute`，路由被普通页面覆盖时调用 `onRouteCovered()`，返回时调用 `onRouteRevealed()`。
+- `PlayerLogic.onRouteCovered()` 关闭路由可见状态、取消拖动并保存进度；`onRouteRevealed()` 在当前页面仍挂载时恢复当前活动 Tab 的播放状态。首页 feed 进入登录页会暂停，返回后恢复。
+- 测试新增普通 `PageRoute` 覆盖后暂停/返回恢复，以及首页 feed 进入 `AuthPage` 后暂停、返回恢复两个场景。
+
+门禁原始输出：
+
+```text
+$ dart analyze lib test
+Analyzing lib, test...
+No issues found!
+
+$ flutter test
+00:48 +475: All tests passed!
+
+$ flutter build apk --debug
+Running Gradle task 'assembleDebug'...
+   8.0s
+✓ Built build/app/outputs/flutter-apk/app-debug.apk
+```
+
+解读：静态检查零告警，475 条测试全部通过，debug APK 构建成功。真机验收由用户执行。
+
 ## 2026-10-20 ReelShort：K62-A 安卓桌面图标资源改造

 - 前置状态：K61-A 已完成并合并，develop 合并提交 `51e9402`。