Files
FruitServer/docs/plans/2026-10-21-K91-watch-history.md
T

5.0 KiB
Raw Blame History

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,所有文件逐项暂存。