docs(plans): 留痕 K31-D 首页频道吸顶

2026-10-20 12:56:27 +08:00
1 parent 02a675a07c
commit 4aa80d0fc7
@@ -1,3 +1,31 @@
+## [已处理] 2026-10-20 | K31-D 首页频道行滚动时固定吸顶（仅 App 端）
+
+**用户指令（2026-10-20，原文）**：
+> 「上滑的时候 上方的tab要固定」
+
+**现状**：`lib/pages/home/home_browse_view.dart` 中频道行（热门/免费/新剧/榜单）作为 `_heroWithChannels()` 的一部分放在 `ListView` 内，随列表一起滚动，上滑后会滚出屏幕。
+
+**口径（只改 Flutter，不动后端、不改接口）**
+1. 频道行移出滚动内容，固定在列表可视区顶部：
+   - `_body()` 的 `Expanded` 内改为 `Stack`：底层保持 `RefreshIndicator + ListView`（`home-browse-page`），顶层 `Positioned(top: 0, left: 0, right: 0)` 放频道行；
+   - 轮播仍从可视区顶部开始，因此初始状态下频道行依旧悬浮在轮播图上。
+2. 吸顶样式切换：给 `ListView` 绑定 `ScrollController`，监听滚动偏移：
+   - 偏移 `< AppDimens.heroBannerHeight - 频道行高(44)` 时：保持现状（透明背景、图上白字/未选中 white70、选中主题色）；
+   - 偏移 `>=` 该阈值后（轮播已滚出频道行下方）：频道行改为不透明背景 `AppColors.ink`、底部 1px `AppColors.border` 分隔线，未选中文字 `AppColors.muted`、选中仍为 `AppColors.blue`，去图上白色；
+   - 阈值不要硬编码 154，直接用 `AppDimens.heroBannerHeight - _channelRowHeight`。
+3. 无 banner 场景：频道行同样固定吸顶，始终使用非叠加配色（`onSurface`/`muted` + 主题色选中 + `AppColors.ink` 背景）。
+4. `HomeBrowseHeader`、`RefreshIndicator` 下拉刷新、Key（`home-channels`、`home-channel-*`、`home-channel-underline-*`、`home-browse-page`、`home-hero-banner`）全部保持不变。
+5. 频道行自身仍可横向滚动；纵向手势不被频道行拦截，保证列表可正常上滑。
+
+**测试/门禁**
+- 新增用例：向上滚动 300px 后，`home-channel-hot` 的屏幕 y 坐标与滚动前一致（吸顶），且出现吸顶背景状态（可用新增 Key `home-channels-pinned` 标识）；
+- 既有频道切换、下拉刷新、发现页轮播用例保持通过；
+- `dart analyze lib test` 零告警 + `flutter test` 全过 + `flutter build apk --debug`。
+
+**流程**：从 `develop` 拉 `feature/flutter-k31-sticky-channels`；作者 `Zhou Weidong <502333560@qq.com>`；`--no-ff` 合回 develop 并 push；PROGRESS 留痕；真机验收由用户执行。
+
+---
+
 ## [已处理] 2026-10-20 | K31-C 首页频道选中态改用主题色（仅 App 端）

 **用户指令（2026-10-20，原文）**：
@@ -20363,3 +20363,32 @@ Running Gradle task 'assembleDebug'...
 ```

 解读：静态检查零告警，401 条测试全部通过，debug APK 构建成功。工作区原有 `pubspec.lock` 变更未纳入本批提交。真机验收由用户执行。
+
+## 2026-10-20 ReelShort：K31-D 首页频道行滚动吸顶
+
+- 分支：`feature/flutter-k31-sticky-channels`
+- 功能提交：`7cc65b7 feat(flutter): 首页频道行滚动吸顶`
+- develop 合并提交：`8e2cd5c merge: 合并 K31-D 首页频道吸顶`，已推送。
+- `home_browse_view.dart`：频道行从 ListView 内容移出，`_body` 改为 `Stack`；底层 `Positioned.fill(RefreshIndicator + ListView(controller))`，顶层 `Positioned(top:0)` 放频道层，初始仍悬浮在轮播图上。
+- `ScrollController` 监听偏移：`offset >= heroBannerHeight - 44`（196）切吸顶态——背景 `AppColors.ink` + 底部 1px 分隔线，未选中 `AppColors.muted`，选中仍为 `AppColors.blue`，并挂 `home-channels-pinned`；未过阈值保持透明叠加配色（未选中 white70、选中主题色）。
+- 无 banner 时频道行始终吸顶并使用非叠加配色；`HomeBrowseHeader`、刷新逻辑与既有 Key 未动。
+- 频道行外层加纵向拖动转发（`onVerticalDragUpdate` 手动滚动页面列表），自身横向滚动不受影响，纵向手势不会被挡住。
+- 测试：改写 K31-B 叠加用例（频道层不在 `home-browse-page` 内、top 与 hero 顶部一致、无 pinned key）；新增 `should_pin_home_channels_when_scrolling`：上滑 300 后 `home-channel-hot` 的屏幕 y 不变且出现 `home-channels-pinned`。
+
+门禁原始输出：
+
+```text
+$ dart analyze lib test
+Analyzing lib, test...
+No issues found!
+
+$ flutter test
+00:36 +402: All tests passed!
+
+$ flutter build apk --debug
+Running Gradle task 'assembleDebug'...
+   7.1s
+✓ Built build/app/outputs/flutter-apk/app-debug.apk
+```
+
+解读：静态检查零告警，402 条测试全部通过（较 K31-C 新增 1 条吸顶用例），debug APK 构建成功。工作区原有 `pubspec.lock` 变更未纳入本批提交。真机验收由用户执行。