feat(app): 收藏与观看历史支持分页

docs/plans/2026-10-22-app-library-paging.md

@@ -0,0 +1,24 @@
+# 客户端收藏与观看历史分页
+
+## 目标
+
+- `/app/favorites` 改为 `PageResult<AppDramaCardVO>`，默认第 1 页、每页 20，最大 100。
+- `/app/watch/recent` 默认返回 `PageResult<ProgressRespVO>`；请求带 `limit` 时保留一版旧
+  `List<ProgressRespVO>` 响应。
+- 观看历史补充短剧标题、封面、集号和总集数，剧/集均批量查询。
+
+## 实现步骤
+
+1. 收藏关系使用 `selectPage`，按 `created_at DESC, drama_id DESC` 稳定排序；
+   只统计已上线短剧收藏，再按当前页 ID 批量加载短剧。
+2. 观看进度使用 `selectPage`，按 `updated_at DESC, drama_id DESC` 稳定排序。
+3. 当前页的 dramaId / episodeId 去重排序后，分别执行一次 IN 查询并装配展示字段。
+4. Controller 归一化 pageIndex/pageSize；观看历史根据是否传 `limit` 分流新旧响应。
+5. 更新 API 契约 §1.5，补 service/controller 测试。
+
+## 风险与约束
+
+- `limit` 分支仅用于旧客户端兼容，新分页响应与旧 List 响应不能混用。
+- 已下线短剧不计入收藏 total，也不出现在收藏页。
+- 观看历史展示字段找不到对应剧或集时保持 null，不影响历史记录返回。
+- 不修改客户端、不改表结构、不启停服务、不操作真机。

docs/plans/PROGRESS.md

@@ -25135,3 +25135,73 @@ $ mvn test
 解读：14 个 reactor 模块全部通过；worker 真实 ffmpeg smoke 产出 HLS、封面、
 VTT 与 sprite，缩略图单格宽高断言为 160x90。
 
+## 2026-10-22 客户端收藏与观看历史分页
+
+- 分支：`feature/app-library-paging`
+- 基线：`develop` / `origin/develop` = `ec15950`
+- 隔离工作树：`/private/tmp/fruitserver-app-library-paging`
+- 计划：`docs/plans/2026-10-22-app-library-paging.md`
+
+### 实现
+
+- `/app/favorites` 增加 `pageIndex`（默认 1）和 `pageSize`（默认 20、上限 100），
+  返回 `PageResult<AppDramaCardVO>`。
+- 收藏关系使用 MyBatis-Plus `selectPage`，按 `created_at DESC, drama_id DESC` 排序；
+  使用已上线 drama 的 `IN` 子查询过滤后，再对当前页短剧做一次批量装配。
+- `/app/watch/recent` 默认返回 `PageResult<ProgressRespVO>`，`pageIndex/pageSize`
+  默认 1/20、上限 100；传 `limit` 时保留旧版 `List<ProgressRespVO>` 响应。
+- 观看进度使用 `selectPage`，按 `updated_at DESC, drama_id DESC` 排序。
+- `ProgressRespVO` 增加 `dramaTitle`、`dramaCover`、`episodeNumber`、`totalEpisodes`；
+  当前页 dramaId / episodeId 去重排序后分别执行一次批量查询，无逐条 N+1。
+- `docs/api-phase1.md §1.5` 已同步分页参数、默认值、上限、稳定排序、响应样例及
+  `limit` 兼容策略。
+
+### 编译
+
+```text
+$ mvn -pl fruitshorts-app-api -am -DskipTests compile
+[INFO] fruitshorts-module-playback ......................... SUCCESS
+[INFO] fruitshorts-app-api .................................. SUCCESS
+[INFO] BUILD SUCCESS
+[INFO] Total time:  9.888 s
+```
+
+解读：`IPage/Page`、新 VO 字段和 Controller 返回类型均通过编译。
+
+### 测试
+
+首次全量测试的两个失败均为测试直接展开 LambdaWrapper SQL 时缺少 MyBatis-Plus
+实体缓存，不是生产逻辑失败：
+
+```text
+MybatisPlusException: can not find lambda cache for this entity
+[UserFavorite]
+[WatchProgress]
+```
+
+按项目现有测试模式增加 `TableInfoHelper.initTableInfo(...)` 后，定向测试先通过：
+
+```text
+$ mvn -pl fruitshorts-app-api -am -Dtest=FavoriteServiceTest,WatchProgressServiceTest,AppLibraryPagingContractTest -Dsurefire.failIfNoSpecifiedTests=false test
+Tests run: 10, Failures: 0, Errors: 0, Skipped: 0
+[INFO] BUILD SUCCESS
+```
+
+最终 app-api 及改动依赖模块全量门禁：
+
+```text
+$ mvn -pl fruitshorts-app-api -am test
+[INFO] Tests run: 109, Failures: 0, Errors: 0, Skipped: 0
+[INFO] Reactor Summary for fruitshorts 1.0.0-SNAPSHOT:
+[INFO] fruitshorts-module-content ......................... SUCCESS
+[INFO] fruitshorts-module-playback ........................ SUCCESS
+[INFO] fruitshorts-app-api ................................ SUCCESS
+[INFO] BUILD SUCCESS
+[INFO] Total time:  10.918 s
+```
+
+解读：收藏默认 pageSize=20、第二页不重叠、total 正确；观看历史分页、
+dramaTitle/episodeNumber/totalEpisodes 非空、越界页空 list 且 total 保持、
+`limit` 旧 List 兼容均通过；服务层断言 `selectPage`、稳定排序和两批 IN 查询。
+未启停服务、未操作真机、未修改客户端。
+