docs(inbox): 下发 K2 客户端第二批（分类/记录/收藏/下载授权 + UI）

docs/plans/INBOX.md

@@ -20,6 +20,113 @@
 
 ---
 
+## [待处理] 2026-10-17 | K2 客户端第二批：分类 + 观看记录 + 收藏列表 + 下载授权（A3/A5 剩余）+ UI
+
+**用户指令（2026-10-17）**：「现在先做客户端 对接相关接口 及ui 严格执行specs 内的要求」。
+
+> **本批只做 K2，做完停下写回执，不要连做 K3/K4。**
+> 规范以 specs 为准（`docs/plans/codex-研发任务清单.md` 阶段 A3/A5、`docs/16-测试用例库.md` CONTENT/RECORD、`docs/09-测试计划.md`）；
+> 接口只认 `FruitServer/docs/api-phase1.md` §1.3 / §1.5 / §1.6，**契约里没有的接口一律不许自造**。
+
+### 一、PM 已勘察的现状（实测，直接用）
+
+- `ReelShort`（`develop` `00280ca`）已接：`/app/home/feed`、`/app/discover/feed`、`/app/dramas/{id}`、`/app/episodes/{id}/play`、`/app/watch/progress`（POST/GET）、`/app/watch/recent`、`DELETE /app/watch/progress/{dramaId}`、`/app/favorites`（toggle/list/delete）、账号 4 个接口。
+- **未接**：`GET /app/categories`、观看记录删除/清空、下载全部 8 个接口、`/app/me*`（属 K4）、互动（属 K3）。
+- 现状缺陷：
+  - 发现页分类**是本地按 sections 下标硬编码**（[discover_view.dart](file:///Users/jianghaifeng/Desktop/ReelShort/ReelShort/lib/pages/discover/discover_view.dart#L363)），不是 `GET /app/categories`；
+  - "我的-记录"只渲染**能在已加载首页/发现目录里匹配到**的剧（[mine_view.dart](file:///Users/jianghaifeng/Desktop/ReelShort/ReelShort/lib/pages/mine/mine_view.dart#L634-L716)），匹配不到就消失；
+  - 收藏列表嵌在"我的"页签里，不能单独刷新/取消收藏；
+  - 下载**完全没有**。
+
+### 二、本批范围（4 块，按顺序做）
+
+#### K2-A 分类（A3 剩余）
+
+- 接口：`GET /app/categories` → `[{ id: string, name: string }]`（J1：**id 是字符串**）。
+- UI：发现页分类条改为**服务端分类**；点分类展示该分类的剧。
+  - 内容来源只允许 `GET /app/discover/feed` 的 `sections[]` 中 `code == "category-{id}"` 的分区（后端已按分类生成，见 `AppCatalogService#discoverFeed`）。
+  - 某分类在 discover 里没有对应分区 → 显示空态，**不要自己拼请求/自造接口**。
+  - 保留现有 `hot` / `new` 分区的入口与样式。
+
+#### K2-B 观看记录页（A5 剩余）
+
+- 接口：
+  - `GET /app/watch/recent?limit=20` → `[{ dramaId, episodeId, positionMs, durationMs, finished, playCount, updatedAt }]`（全部 ID 为字符串）
+  - `DELETE /app/watch/progress/{dramaId}`、`DELETE /app/watch/progress`（清空）
+- **契约缺口（必须按下面方式处理，不许改后端）**：`recent` **不返回剧名/封面**。做法：
+  - 先去重 `dramaId`，再对每个 id 调 `GET /app/dramas/{id}` 补卡片；
+  - **并发上限 4**，结果按 dramaId 缓存（同页内不重复请求）；
+  - 单条详情失败**不能拖垮整页**：该条显示占位（剧名"加载失败"+重试），其余正常渲染；
+  - 在计划文档里记为「契约缺口：建议后续在 `ProgressRespVO` 补卡片字段（需 specs 负责人改契约）」。
+- UI：独立"观看记录"页（入口：我的 → 观看记录）
+  - 每条：封面、剧名、第 N 集、`positionMs/durationMs` 进度、更新时间；点击进详情并续看；
+  - 单条删除、清空（二次确认）；删除**乐观更新**，失败回滚并提示；
+  - 未登录 → 复用现有 `AuthGate` 登录引导（接口需要登录，见 `SecurityConfig`）；
+  - 三态：加载中 / 空（"还没有观看记录"）/ 失败（可重试）。
+
+#### K2-C 收藏列表页（A5 剩余）
+
+- 接口：`GET /app/favorites`（返回 `AppDramaCardVO[]`，**与首页卡片同结构**）、`DELETE /app/favorites/{dramaId}`、`POST /app/favorites/toggle`。
+- UI：独立"我的收藏"页（我的 → 收藏），复用首页卡片渲染：
+  - 取消收藏（按钮或长按/左滑，二选一但要能发现）→ **乐观更新 + 失败回滚**；
+  - 点击进详情；空/错/载三态；未登录 → `AuthGate`。
+- **契约缺口**：TC-RECORD-04 写"分页正确"，但 `GET /app/favorites` **没有分页参数**、返回全量数组 → 本批按全量实现，计划文档登记该缺口，**不许自造 `page/size`**。
+
+#### K2-D 下载授权与管理（A5 最后一块，**不做实际落盘**）
+
+- 接口（§1.6，全部需登录；设备号优先请求体、其次 `X-Device-Id`，现有 `ApiClient` 已带）：
+  | 方法 | 路径 | 本批用途 |
+  |---|---|---|
+  | GET | `/app/downloads/policy` | 配额/授权天数/wifiOnly/清晰度/已用/剩余/`expirePolicyText` |
+  | PUT | `/app/downloads/settings` | 仅 Wi-Fi、最高清晰度 |
+  | POST | `/app/downloads` | 申请授权（body `episodeId`，`quality` 可省=AUTO） |
+  | GET | `/app/downloads` | 我的下载授权列表 |
+  | GET | `/app/downloads/{episodeId}/url` | 续传前刷新短时效地址（本批只提供 API 方法） |
+  | POST | `/app/downloads/{episodeId}/progress` | 进度上报（本批只提供 API 方法） |
+  | DELETE | `/app/downloads/{episodeId}` | 删除单条 |
+  | DELETE | `/app/downloads` | 清空，返回条数 |
+- UI：
+  - 详情页/播放页加"下载"入口：调 `POST /app/downloads`；**付费/未解锁/配额满时直接展示后端 `message`**，不要自造判断（判定归服务端）；
+  - 我的 → 下载：策略卡（剩余配额、授权天数、`expirePolicyText`）、授权列表（剧名、集号、`status`、`taskStatus`、`progressPercent`、到期时间）、单条删除、清空、仅 Wi-Fi/清晰度设置；
+  - 状态枚举全部**后端返回值驱动**（`ACTIVE/EXPIRED/REVOKED`、`QUEUED/DOWNLOADING/PAUSED/COMPLETED/FAILED/CANCELED`），前端不新增枚举；
+  - 空/错/载三态 + 未登录 `AuthGate`。
+- **明确不做**（写进计划文档，避免误判"没做完"）：文件分片落盘、断点续传、离线播放、`licenseKey` 本地校验 —— 需要存储/权限/加密播放方案，另立批次。本批只交付"授权与状态管理"。
+
+### 三、UI 与规范约束（严格执行 specs）
+
+- **语言**：所有新增文案必须进 `lib/l10n/app_{en,zh,id}.arb` **三份齐全**并重新生成；禁止硬编码中文/英文。印尼语为首发语言。
+- **视觉**：沿用现有深色主题与 `AppColors`/组件风格（specs 里未提供 Stitch 出稿；若用户后续给出稿，再单独做视觉替换，本批不自行改主题）。
+- **三态**：每个新页面/列表都要有加载、空、失败（可重试）；失败文案走 `errorText` + l10n，禁止白屏/假装成功。
+- **分层**：新增 `category_api / download_api`（放 `lib/core/data/remote/`），页面只依赖 repository/controller 抽象；沿用 K1 的分层与依赖注入方式。
+- **ID**：19 位雪花 ID 一律按字符串解析（`json_numbers.dart`），**禁止 `as int`**；计数/时长同理按契约类型处理。
+- **不要动**：首页/发现已接 feed 逻辑（分类来源替换除外）、登录注册、播放/进度/收藏已有逻辑（除必要接线）、`ReelShortWeb`、`FruitServer` 后端。
+- 新文件首行 `// Author: fruit.com.cn`；测试命名 `should_<期望>_when_<条件>`。
+
+### 四、门禁（不达标不提交）
+
+1. `dart analyze lib test` **零告警**；`flutter test` **全过**（存量 33 个测试文件不得跑红）。
+2. 新增测试至少覆盖：分类→section 映射（含无分区空态）、记录页 N+1 详情请求去重/并发上限/单条失败降级、删除与清空回滚、收藏取消回滚、下载策略/授权列表渲染、未登录 AuthGate。
+3. **真机/设备侧验证由用户执行**（红线 7、10）：回执里给"用户可照做的步骤 + 每步预期结果"，**禁止用开发机 `curl` 冒充设备可达**；拿不到设备证据就标「未验证」。
+4. 在 `ReelShort` **`develop`** 提交并 `git push origin develop`；**不动 `main`**。
+
+### 五、节奏与留痕
+
+- 先写 `FruitServer/docs/plans/2026-10-17-K2.md`：范围、影响文件清单、上述 3 个契约缺口、风险。
+- 做完**停下写回执**（追加到 `docs/plans/PROGRESS.md` + 本条下），回执必须含：
+  - 哪些页面已走真数据、哪些仍是本地/未做；
+  - 用户可照做的验证步骤与每步预期；
+  - 测试与 analyze 的原始输出；
+  - 提交号。
+- 禅道：开工/完成各同步一次任务状态。
+
+### 六、PM 登记：specs 契约缺口（Codex 不要动，反馈给项目负责人）
+
+1. **搜索**：任务清单 A3 写了"搜索"、TC-CONTENT-05 有搜索用例，但 `api-phase1.md` **没有 `/app/search` 接口** → 本批**不做搜索**。
+2. `GET /app/favorites` 无分页参数，与 TC-RECORD-04"分页正确"不一致。
+3. `GET /app/watch/recent` 不返回剧名/封面，记录页需 N+1 详情请求（建议后端补卡片字段）。
+
+---
+
 ## [已处理] 2026-10-17 | 三库全量拉取 + `main` → `develop` 同步（Trae 执行，无代码改动）
 
 **用户指令（2026-10-17）**：「先拉最新全量代码，三个库全拉，相关规范已经备齐、接口文档完备、INBOX更新、环境地址清单在docs下21-环境地址清单.md 同步main 分支到开发分支」。