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

docs/api-phase1.md

@@ -290,16 +290,97 @@ app.register.max-per-device-per-day
 | --- | --- | --- |
 | POST | `/app/watch/progress` | 上报进度（建议每 10s 一次，切集时补一次） |
 | GET | `/app/watch/progress?dramaId=` | 某剧续看位置 |
-| GET | `/app/watch/recent?limit=20` | 最近观看 |
+| GET | `/app/watch/recent` | 最近观看分页；`pageIndex` 默认 1，`pageSize` 默认 20、上限 100 |
+| GET | `/app/watch/recent?limit=20` | 旧版最近观看 List 响应，仅保留一版兼容 |
 | DELETE | `/app/watch/progress/{dramaId}` | 删除某剧记录 |
 | DELETE | `/app/watch/progress` | 清空记录 |
 | POST | `/app/favorites/toggle` | 收藏/取消收藏，返回切换后状态 |
-| GET | `/app/favorites` | 收藏列表（卡片结构与首页一致） |
+| GET | `/app/favorites` | 收藏分页；`pageIndex` 默认 1，`pageSize` 默认 20、上限 100 |
 | DELETE | `/app/favorites/{dramaId}` | 取消收藏 |
 
 进度合并规则：同一集内只前进不后退；换集直接采纳新集；`finished` 只在接近片尾或客户端显式上报时置位。
 这样用户换设备不会看到进度倒退。
 
+#### 收藏分页
+
+`GET /app/favorites?pageIndex=1&pageSize=20`
+
+请求参数：
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| `pageIndex` | int | 否 | 1 | 页码，小于 1 按 1 处理 |
+| `pageSize` | int | 否 | 20 | 每页数量，上限 100，小于 1 按 1 处理 |
+
+响应 `data` 为 `PageResult<AppDramaCardVO>`：
+
+```json
+{
+  "total": "23",
+  "list": [
+    {
+      "id": "12",
+      "title": "替嫁新娘：总裁的掌心宠",
+      "cover": "/files/drama_cover/12.jpg",
+      "preview": {}
+    }
+  ]
+}
+```
+
+排序固定为收藏时间倒序 `created_at DESC`，收藏时间相同时按 `drama_id DESC`。
+仅统计和返回仍处于已上线状态的短剧。
+
+#### 最近观看分页
+
+`GET /app/watch/recent?pageIndex=1&pageSize=20`
+
+请求参数：
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| `pageIndex` | int | 否 | 1 | 页码，小于 1 按 1 处理 |
+| `pageSize` | int | 否 | 20 | 每页数量，上限 100，小于 1 按 1 处理 |
+| `limit` | int | 否 | 无 | 兼容旧版；只要传该参数就返回 List，不再返回 PageResult |
+
+分页响应 `data` 为 `PageResult<ProgressRespVO>`：
+
+```json
+{
+  "total": "18",
+  "list": [
+    {
+      "dramaId": "12",
+      "episodeId": "88",
+      "dramaTitle": "替嫁新娘：总裁的掌心宠",
+      "dramaCover": "/files/drama_cover/12.jpg",
+      "episodeNumber": 6,
+      "totalEpisodes": 68,
+      "positionMs": "80000",
+      "durationMs": "120000",
+      "finished": false,
+      "playCount": 3,
+      "updatedAt": "2026-10-22 10:00:00"
+    }
+  ]
+}
+```
+
+排序固定为 `updated_at DESC, drama_id DESC`。每页记录通过批量 IN 查询装配短剧和分集，
+不逐条访问数据库。
+
+`ProgressRespVO` 展示字段：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `dramaTitle` | string / null | 短剧标题 |
+| `dramaCover` | string / null | 短剧封面 |
+| `episodeNumber` | int / null | 当前续看集号 `ep_no` |
+| `totalEpisodes` | int / null | 短剧总集数 |
+
+旧兼容请求 `GET /app/watch/recent?limit=20` 的 `data` 仍为 `List<ProgressRespVO>`，
+行为在本版本保留；新客户端应使用分页响应。
+
 ### 1.6 离线下载（已实现）
 
 服务端只发**授权**与**短时效地址**，分片由客户端直接向 CDN 拉取 ——