docs(plans): K1 回执（客户端详情+播放+续看+收藏，含真数据/假数据清单）

docs/plans/PROGRESS.md

@@ -358,3 +358,57 @@ DELETE 1  # 创作者 J1PROBE
 ⚠️ 口径纠正：我第一版清理脚本用 `psql -t -A -c "delete … returning 1" | wc -l` 数"行数"，
 **数到的其实是 psql 的命令标签**（实测删 0 行时输出 `DELETE 0`，也是 1 行），所以那轮打印的
 "删除 1 行"是假数字。真正的证据是后面的**全库残留扫描**（零命中）与现存数据核对，已按此结论写回执。
+
+---
+
+## 2026-10-16 K1：客户端对接（详情 + 播放 + 进度续看 + 收藏）+ 三态 UI
+
+计划文件：`docs/plans/2026-10-16-K1.md`（先写计划再动手）。仓库：`ReelShort`（Flutter，develop）。
+
+### 动作 1：勘察更正
+条目说"客户端只调了 6 个接口、没有详情和票据"——实测**详情已接**（`CatalogApi.dramaDetail`），
+**票据半接**（`CatalogApi.playTicket` 存在但没页面调用）。这一点写进计划与回执。
+
+### 动作 2：分层实现（api → repository → logic → view）
+- 新增 `playback_api.dart` / `watch_api.dart` / `library_api.dart` + `watch_progress.dart` 模型
+- 新增 `PlaybackRepository`（票据 TTL 缓存，默认 10 分钟；时钟/TTL 可注入）、`FavoriteRepository`
+- `WatchHistoryRepository` 换成服务端模型（每剧一条续看记录），删掉 `demoProfileId` 与 SharedPreferences 实现
+- `FavoriteController` 乐观更新 + 失败回滚；`app.dart` 注入三个仓库与收藏控制器
+
+### 动作 3：门禁（最终数字）
+
+```
+$ dart analyze lib test
+No issues found!
+$ flutter test
+00:09 +188: All tests passed!
+```
+
+新增测试：`playback_ticket_expiry_test`（票据过期重取 + 签名 query 原样保留）、
+`progress_throttle_test`（10 秒节流 + 切集补报 + 播完 finished + 续看定位）、
+`watch_history_test`（重写为服务端模型）、`library/favorite_controller_test`（回滚/错误态/退出清空）、
+`integration/live_watch_flow_test`（真实后端端到端）。
+
+### 动作 4：真实后端联调（8081，原始输出）
+
+```
+① 首页 → dramaId=5
+② 详情 → episodes=3，第一集 id='7' playUrl=/files/episode/202610/cec39d8e….mp4?e=1792144372&s=8791826a…
+③ 票据 → episodeId='7' dramaId='5' accessType=FREE accessible=True
+        playUrl 与详情里的签名地址一致（客户端只补 host，不动 path/query）
+④ 上报进度（42s）→ {"dramaId":"5","episodeId":"7","positionMs":"42000","durationMs":"228000","playCount":1}
+⑤ 读回续看位置   → dramaId='5' episodeId='7' positionMs='42000' durationMs='228000'
+⑥ 最近观看       → 条数=1，dramaId='5' episodeId='7' positionMs='42000'
+⑦ 收藏 → toggle 返回 true → 收藏列表条数=1（首个 '5'）→ DELETE → 取消后条数=0
+```
+
+`flutter test test/integration/live_watch_flow_test.dart` → All tests passed（同一链路在客户端代码里跑通）。
+解读：`positionMs/durationMs/dramaId` 都是**字符串**（J1 的新口径），客户端用 `jsonToInt` 解析。
+
+### 动作 5：自测数据清理
+
+```
+已清理 2 个自测账号（k1.selftest.* / k1.receipt.*）+ 依赖行
+残留核对：app_user 1 行（PM 的 id=28）、app_user_credential 1 行、watch_progress 0、user_favorite 0
+```
+（第一次清理漏了 `app_user` 本体——它的主键列叫 `id` 不是 `user_id`，随后单独删掉并复核。）