115 lines
5.0 KiB
Markdown
115 lines
5.0 KiB
Markdown
# 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`，所有文件逐项暂存。
|