# K95 修复首页频道快速切换卡 Loading

## 目标

- 频道请求完成后始终写回发起请求的频道缓存，不再因用户切走而丢失结果。
- 每频道明确区分 loaded / loading / in-flight / error，无请求时绝不显示首屏转圈。
- 首屏和刷新请求增加可注入的 10 秒超时兜底。
- PlayerLogic 保证连续 feed 更新串行应用，只让最后一次 feed/session 生效。

## 分支

- ReelShort：`fix/k95-feed-switch-loading`，从 `origin/develop` 创建。
- FruitServer 仅提交计划与 PROGRESS，不改功能代码。

## A. HomeFeedController

每个频道状态增加：

- `List<Drama> dramas`
- `String? cursor`
- `bool hasMore`
- `bool loaded`
- `bool loading`
- `bool loadingMore`
- `String? lastError`
- `int requestSeq`
- `Future<bool>? inFlight`

请求规则：

1. 响应成功/失败都写入发起请求的频道状态。
2. 只有频道仍为当前频道时才 `notifyListeners`。
3. `requestSeq` 只比较同一频道的新旧请求，不参与跨频道过滤。
4. 超时时间通过构造参数注入，默认 10 秒。
5. `loadingFirstPage = !loaded && loading`。
6. `selectChannel`：
   - 有缓存：同步显示，未在飞时后台静默刷新
   - 无缓存且正在飞：等待现有请求，不重复发
   - 无缓存且有历史错误：自动重试
   - 从未加载：发起首屏请求
7. `refreshCurrent` 同样复用 in-flight，防止并发重复刷新。
8. `loadMore` 失败保留 cursor/hasMore，允许下次继续重试。

## B. PlayerLogic / PlayerPage

### B1 Feed revision

- PlayerLogic 增加 `int feedRevision`。
- 每次 `updateFeed` 自增 revision，记录最新目标 feed。
- `_replaceSession` 与 `selectEpisode` 在 await 后校验 revision，过期流程直接返回。
- 连续 updateFeed 使用串行队列：当前应用结束后再应用最新待处理 feed。

### B2 空队列与频道切换

- 空 feed 不创建新 session，只清空 queue/visibleIndices 并停播。
- 空 → 非空必须恢复 route visible，并 select 第 0 个。
- 频道变化通过额外 reset 标志传入 `updateFeed`，即使 drama id 列表相同，
  也重置到第 1 个并开始播放。

### B3 PlayerPage 更新判定

- `didUpdateWidget` 用 `feedDramas` 的 drama id 列表签名判断内容变化。
- 同一列表的新 List 实例不重复 updateFeed。
- 频道变化始终触发 updateFeed，并传 `resetToFirst=true`。

## C. 测试

### HomeFeedController

- A 挂起 → B 成功 → A 成功：A/B loaded 均为 true，切回 A 立即有数据。
- 同频道旧失败响应不得覆盖新成功响应。
- 无在飞请求时 `loadingFirstPage=false`。
- 永不返回的请求在注入超时后结束 loading、写 lastError、loaded=true。
- 失败频道再次 select 自动重试。
- loadMore 失败保留原有 hasMore/cursor。

### PlayerLogic

- 连续 5 次 updateFeed，最终 queue/session 对应最后一次列表。
- 空 → 非空会创建 session 并 select 第 0 个。
- 频道变化时相同 id 列表也回到第 1 个。

门禁：

- `dart analyze lib test`
- `flutter test --no-pub`
- `flutter build apk --debug`

## 风险与控制

1. 跨频道响应写回缓存必须与同频道 seq 校验同时存在；前者解决缓存丢失，后者解决同频道旧请求覆盖新结果。
2. Player session 替换以 revision 作为唯一有效性判断，避免旧 close/select 回调干扰新 session。
3. 空队列期间不创建 PlaybackSession；恢复非空时重新创建并起播。
4. 不改后端、ReelShortWeb、specs；不安装或操作真机。

## Git

- 提交：`fix(home): 修复频道快速切换卡 loading`
- `--no-ff` 合回 ReelShort `develop` 并 push。
- 作者：`Zhou Weidong <502333560@qq.com>`；禁止 `git add -A`。