# K1 客户端对接：详情 + 播放 + 进度续看 + 收藏（看剧闭环）+ UI 调整 —— 计划（2026-10-16）

> 依据：`docs/plans/INBOX.md` 19:40 条目。用户指令：「现在你要做的事对接客户端接口及 UI 调整，
> 仍然严格按照 specs 执行」→ 本轮做客户端 `ReelShort`（Flutter），目标是一条完整看剧闭环：
> **首页点进剧 → 详情正确 → 能起播 → 进度能续看 → 能收藏**，全链路走真接口。
> 契约以 `FruitServer/docs/api-phase1.md` §1.4 / §1.5 为准。

## 一、勘察更正（先说清，免得后面对不上）

条目里写「客户端只调了 6 个接口、没有详情和票据」—— 这条**不准确**，实测：

| 接口 | 现状 |
| --- | --- |
| `GET /app/dramas/{id}` | **已接**：`CatalogApi.dramaDetail` + `CatalogController.requireDetail`，详情页在用 |
| `GET /app/episodes/{id}/play` | **半接**：`CatalogApi.playTicket` + `CatalogController.resolvePlay` 存在，但**没有任何页面调用**；详情下发的 `playUrl`（免费集已带签名）被直接使用 |
| `/app/watch/*` | **没接**：`WatchHistoryRepository` 是 `SharedPreferences` 本地实现，`demoProfileId` 假身份 |
| `/app/favorites/*` | **没接**：收藏走本地 `EngagementController`（SharedPreferences），点赞也是本地（点赞属 K3，不动） |

所以本轮真正要做的是：**播放票据接上并带过期重取**、**进度从本地换远程**、**收藏换服务端**、
**三态 UI**，以及把详情页已有的加载/失败态补齐（空态、续看进度条）。

## 二、方案（分层：api → repository → logic → view）

### 1. 新增 api 类（`lib/core/data/remote/`）

| 文件 | 方法 | 对应接口 |
| --- | --- | --- |
| `playback_api.dart`（新增） | `ticket(episodeId)` | `GET /app/episodes/{id}/play` |
| `watch_api.dart`（新增） | `saveProgress` / `progressOfDrama` / `recent` | `POST /app/watch/progress`、`GET /app/watch/progress?dramaId=`、`GET /app/watch/recent?limit=` |
| `library_api.dart`（新增） | `toggleFavorite` / `favorites` / `removeFavorite` | `POST /app/favorites/toggle`、`GET /app/favorites`、`DELETE /app/favorites/{dramaId}` |

票据调用从 `CatalogApi` **搬**到 `PlaybackApi`（条目要求新增 playback_api），
`CatalogRepository.resolvePlay` 随之移到新的 `PlaybackRepository`——这是本轮唯一"动到既有目录层"的地方，最小接线。

### 2. repository（保留抽象，测试注入假实现）

- `playback_repository.dart`（新增）：`ticketFor(episodeId, {forceRefresh})`。
  `HttpPlaybackRepository` 内含**短时缓存**：默认 TTL 10 分钟（签名有效期契约是 15 分钟，留余量），
  **时钟与 TTL 可注入** → 过期自动重取，测试用假时钟钉死。
- `watch_history_repository.dart`（**改签名**）：服务端按 `(user, drama)` 存一条续看记录，
  所以接口从 `(profileId, dramaId, episodeId)` 变成
  `progressFor(dramaId)` / `save({episodeId, position, duration, finished})` / `recent(limit)`；
  `HttpWatchHistoryRepository` + `InMemoryWatchHistoryRepository`（测试用）；
  `demoProfileId` 删除；`clampResumePosition` 保留（续看钳位规则不变）。
- `favorite_repository.dart`（新增）：`toggle` / `list` / `remove`；HTTP + 内存实现。

### 3. controller / logic

- `favorite_controller.dart`（新增）：`savedIds` + `cards` + `loading/error`，
  `toggle(dramaId)` **乐观更新 → 失败回滚**（`DELETE`/`toggle` 任一失败都回到原状态）。
- `DramaDetailLogic` / `MineLogic` / `PlayerLogic`：改用新的 `WatchHistoryRepository`，
  续看点从 `WatchProgress(episodeId, positionMs)` 来（不再是本地 episodeId 字符串）。
- `PlayerLogic`：
  - 起播前 `ticketFor(episode)`，把签名地址写回 session 的剧集对象；**地址原样交给播放器**
    （`AppConfig.mediaUrl` 只补 host，不动 path/query —— 新增测试钉住 `?e=&s=` 原样保留）；
  - 票据拿不到 / `accessType=COIN_REQUIRED|NO_MEDIA` → 由**后端返回值**驱动 UI（锁定/无片源提示 + 重试）；
  - 进度上报**节流 10 秒**（原实现是 5 秒），切集/退出/切后台各补一次，`finished` 在播完时上报。

### 4. UI

- 详情页：加载中 / 失败（可重试）/ 空剧集三态；续看位置在"继续观看"按钮与对应剧集行上给进度条。
- 播放页：票据加载中 / 失败（可重试）/ 锁定（`accessType` 驱动）三态；收藏按钮真实状态 + 回滚 +
  失败提示（未登录先引导登录，沿用现有 `ensureSignedIn`）。
- 我的页：最近观看卡片三态（服务端续看位置驱动）、收藏列表三态，去掉 `demoProfileId` 假身份。
- 文案：新增键写进 `app_en.arb` / `app_zh.arb` / `app_id.arb`，`flutter gen-l10n` 重新生成。

## 三、影响面清单

新增：`playback_api.dart`、`watch_api.dart`、`library_api.dart`、`watch_progress.dart`（模型）、
`playback_repository.dart`、`favorite_repository.dart`、`favorite_controller.dart`。

改：`watch_history_repository.dart`（签名）、`catalog_api.dart`（去掉 playTicket）、
`catalog_repository.dart`（去掉 resolvePlay）、`catalog_controller.dart`（同步）、
`play_ticket.dart`（补 dramaId/number/previewSeconds）、`app.dart`（注入三个仓库 + FavoriteController）、
`drama_detail_{logic,view,binding}.dart`、`mine_{logic,view,binding}.dart`、
`player_{logic,view,binding}.dart`、`discover_{logic,binding}.dart`（续看点来源）、
`app_{en,zh,id}.arb` + 生成的 4 个 l10n 文件。

测试：改 `test/support/fake_watch_history.dart`、`test/playback/watch_history_test.dart`、
`test/catalog/catalog_controller_test.dart`、`test/support/fake_catalog.dart`、
`test/{discover,mine,drama_detail,player}/…`（续看点改签名）；新增
`playback_ticket_expiry_test.dart`、`progress_throttle_test.dart`、`watch_history_remote_test.dart`、
`favorite_controller_test.dart`、`player_ticket_gate_test.dart`、`integration/live_watch_flow_test.dart`。

## 四、风险 / 待确认

1. **改动面比"只加接口"大**：`WatchHistoryRepository` 的签名必须改（服务端是"每剧一条续看记录"，
   没有 profile 概念），这会连带改 4 个 logic + 6 个测试文件。这是接口模型决定的，不是顺手重构。
2. **未登录的边界**：`/app/watch/*` 与 `/app/favorites/*` 需要登录态。客户端策略：
   未登录时**不发**这些请求（浏览/试看仍可匿名），收藏按钮沿用"先引导登录"。
3. **票据过期无法从响应判断**（契约里没有 expiresAt 字段），所以用**客户端 TTL（10 分钟）**保守失效重取；
   若后端后续补 `expiresAt`，直接换成按字段判断即可（口径已写进计划）。
4. **`/app/watch/recent` 只给 dramaId/episodeId/位置**，没有剧名封面 —— K1 里"我的"页用
   已加载的首页/发现卡片按 id 映射显示；映射不到就不显示（K2 的记录页再做成独立请求）。
5. 联调测试需要登录态：新增的 live 测试会**注册一个一次性邮箱账号**，跑完在库里清掉（回执写明）。