# K91 后台观看记录独立菜单、评论分集展示与全部状态筛选

## 目标

- FruitServer 新增跨用户观看记录分页接口，并给后台评论补充短剧名、集号与集标题。
- ReelShortWeb 新增「观看记录」独立页面，评论/举报状态筛选默认展示全部。
- 迁移脚本只提交文件，不执行数据库变更；不改 specs 仓库和 Flutter 客户端。

## 分支

- FruitServer：`feat/k91-watch-history`，从 `origin/develop` 创建。
- ReelShortWeb：`feat/k91-watch-history-page`，从 `origin/develop` 创建。

## A. FruitServer

### A1 观看记录分页

1. 新增 `WatchHistoryQueryReqVO`，字段：
   `pageIndex/pageSize/keyword/userId/dramaTitle/dramaId/episodeId/source/finished/startTime/endTime`。
2. 新增 `AdminWatchHistoryVO`，返回用户、短剧、分集、进度、完成、来源、设备与观看时间。
3. 新增 `WatchHistoryAdminService`，直接注入：
   - `WatchHistoryMapper`
   - `AppUserMapper`
   - `DramaMapper`
   - `DramaEpisodeMapper`
4. 查询流程：
   - `keyword` 先批量命中 `app_user.uid/nickname` 的 id；无命中直接空页。
   - `dramaTitle` 先批量命中 `drama.title` 的 id；无命中直接空页。
   - 精确 id 条件与模糊命中集合取交集。
   - `finished` 在 SQL 层表达，允许区间两侧都落在 `duration_ms = 0` 等边界。
   - 按 `watched_at DESC, id DESC` 排序。
   - 对结果页的用户、剧、集各做一次批量查询后装配，禁止逐行查询。
5. 新增 `WatchHistoryAdminController`，权限点 `watch-history:list`，保留旧用户详情观看流水接口。

### A2 评论后台分集信息

1. `CommentRespVO` 增加 `dramaTitle/episodeNo/episodeTitle`。
2. 仅 `CommentService.adminPage` 对当前页批量补剧、集信息。
3. `toRespList` 的 C 端路径保持不增加查询。

### A3 SQL 与契约

1. 新增幂等迁移 `sql/migrate-k91-watch-history-menu.sql`：
   - 权限点 `1105 watch-history:list`
   - 菜单使用 id `34`，挂 parent `15`
   - `component=views/userManagement/WatchHistoryView`
   - 超管角色权限与菜单关联
2. 同步 `sql/data-phase1.sql`。
3. 更新 `docs/api-phase1.md` §2.3、§2.5。

### A4 测试

- `WatchHistoryAdminServiceTest` 覆盖：
  - 默认分页与排序
  - keyword 用户命中
  - dramaTitle 剧名命中
  - finished 真/假 SQL 条件
  - 时间范围
  - 命中集合为空直接空页
  - pageSize 上限收敛为 100
- `CommentServiceTest` 覆盖后台页批量补齐剧名、集号、集标题。
- 门禁：`mvn test` 全模块通过。

## B. ReelShortWeb

### B1 类型/API

- 扩展 `WatchHistoryItem`：`userId/uid/nickname/episodeTitle`。
- 扩展 `CommentItem`：`dramaTitle/episodeNo/episodeTitle`。
- `appUser.ts` 新增 `pageWatchHistoryApi(params)`。

### B2 观看记录页面

- 新建 `src/views/userManagement/WatchHistoryView.vue`：
  - 用户、短剧名称、来源、完成状态、时间范围筛选。
  - 观看时间、用户、短剧、分集、进度、完成、来源、设备列。
  - 10/20/50 分页。
  - 复用 App 用户页的 `panel/console-toolbar/pagination/app-user-*` 视觉与格式化函数。

### B3 评论/举报全部状态

- 评论与举报状态首项增加 `{ value: '', label: '全部状态', tag: 'info' }`。
- 两个筛选默认值改为空串，请求时空串转 `undefined`。
- 评论表以「短剧 / 分集」替换短剧 ID 单列：
  - 显示剧名与集号/集标题。
  - 缺少剧名时回退短剧 id。
  - 缺少集号时回退分集 id；历史 `episodeId=0` 显示未关联分集。
  - 原始短剧 id / 分集 id 通过 tooltip 保留。

### B4 门禁

- `pnpm ts:check`
- `pnpm build:dev`

## 风险与待确认

1. `watch_history` 是月分区表，现有索引为 `(user_id, watched_at)` 与
   `(drama_id, watched_at)`，没有跨用户的全局 `watched_at` 索引。本次按要求实现跨用户时间排序，
   不擅自新增索引；数据量增长后由 PM 评估是否增加全局观看时间索引。
2. 用户/剧名模糊检索先取 id 集合，符合“命中为空不退化成全表”的要求；
   超大关键词命中集合的批大小由后续实际数据量评估，本次不擅自加截断以免漏结果。
3. 历史评论的 `episode_id=0` 不回填；后台显示“未关联分集”，原始 id 仍保留在 tooltip。
4. 迁移脚本只写文件，不执行数据库；菜单落库由 PM 按发布流程执行。
5. 任务书建议菜单 id `26`，但当前 `data-phase1.sql` 已将 `26` 用作“创作者中心”目录，
   `27-30` 为其子菜单。为避免覆盖线上已有菜单树，本次使用下一个空闲 id `34`；
   父级、路由、组件与权限点均不变。

## 提交与合并

- FruitServer 提交：`feat(admin): 新增观看记录分页与评论分集信息`
- ReelShortWeb 提交：`feat(admin): 观看记录独立菜单与治理状态全部筛选`
- 两仓库均 `--no-ff` 合回 `develop` 并 push。
- 作者与提交者：`Zhou Weidong <502333560@qq.com>`。
- 禁止 `git add -A`，所有文件逐项暂存。