草原指南字段级操作记录与分页接口

日期：2026-07-14

后端 Issue：HL #4977

发布范围：先合入 dev，再同步 dev-v3 并部署 TEST；当前不合入 main、不部署正式环境

1. 变更目的

草原指南编辑页原“操作记录”只有创建时间和最后编辑时间，无法说明谁修改了什么。本次新增独立分页接口，响应结构参考产品日志时间线，提供：

操作类型和中文摘要；
操作所属页面区域；
操作人 ID、名称快照和操作时间；
本次真实变化的字段；
字段中文名、旧值、新值和变更类型；
富文本、正文图片和生效封面等长值的摘要与哈希。

2. 接口

GET /admin/grassland-guide/videos/{videoId}/operation-logs?page=1&pageSize=20

查询参数：

参数	必填	默认值	规则
`videoId`	是	-	草原指南视频 ID
`page`	否	`1`	最小 `1`
`pageSize`	否	`20`	`1-100`

分页顺序固定为 createTime DESC, id DESC，前端按 records 追加加载即可。只有 SUPER_ADMIN、OPERATOR 可以查询字段级历史值。

3. 响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "records": [
      {
        "id": "2077195939797688322",
        "videoId": "2076195939797688322",
        "action": "UPDATE",
        "actionLabel": "编辑",
        "step": "BASIC",
        "stepLabel": "基础信息",
        "detail": "编辑基础信息",
        "changedFields": ["title", "summary"],
        "fromStatus": "PUBLISHED",
        "toStatus": "PUBLISHED",
        "operatorId": "10001",
        "operatorName": "yangchunsheng",
        "createTime": "2026-07-14 13:56:19",
        "changes": [
          {
            "field": "title",
            "fieldLabel": "视频标题",
            "oldValue": "草原指南验收",
            "newValue": "草原指南验收｜草原蜱虫怎么预防和处理",
            "changeType": "MODIFY",
            "oldHash": null,
            "newHash": null
          }
        ]
      }
    ],
    "total": 12,
    "page": 1,
    "pageSize": 20
  },
  "success": true
}

4. 字段枚举

action：

值	`actionLabel`	含义
`CREATE`	新建	创建草稿
`UPDATE`	编辑	更新内容或展示配置
`PUBLISH`	上线	首次发布或重新发布
`OFFLINE`	下线	已发布内容下线
`DELETE`	删除	删除草稿或已下架内容

step：

值	含义
`BASIC`	基础信息
`CONTENT`	图文正文
`PUBLISH_SETTING`	发布设置
`DISPLAY_SETTING`	展示设置
`MULTIPLE`	一次操作涉及多个区域，使用 `stepLabel` 展示具体区域

changeType：ADD、MODIFY、DELETE。

5. 前端接入规则

编辑页打开时请求第一页，滚动到底部后按 page + 1 加载；不要一次拉取全部日志。
时间线标题可使用 actionLabel + stepLabel，说明文本直接使用 detail。
字段差异直接渲染 changes[].fieldLabel/oldValue/newValue，不要自行把字段英文名转换为中文。
所有 id、videoId、operatorId 都按字符串处理。
fromStatus、toStatus 可为空；状态没有变化的编辑操作也可能两者相同。
历史日志只有 changedFields，changes 会返回空数组；页面应展示动作、操作人和时间，不要报错。
富文本正文不返回整篇 HTML；oldValue/newValue 是去标签后的摘要，oldHash/newHash 用于判断完整内容是否不同。
正文图片返回“共 N 张”；生效封面返回脱敏摘要，例如 封面#1a2b3c4d，不会下发完整 OSS 地址。
后端只记录真实变化字段；无变化字段不会出现在 changes 中。

6. 与既有接口的关系

草原指南列表、详情、创建、编辑、发布、下架和删除接口路径均不变。
详情中的 createdAt/updatedAt/createdBy/updatedBy 保持兼容，但不再承担完整操作历史展示。
本接口不返回、也不接收 version；前端继续不维护版本号。
本文件只说明操作记录，不合并到素材上传、MP4 校验或删除功能的 changelog。

7. 联调清单

首次进入加载第一页，向下滚动可稳定分页且不重复。
编辑标题、简介、正文、展示设置后可显示对应旧值和新值。
发布、重新发布、下线和删除显示正确动作及状态变化。
历史日志 changes=[] 时页面正常降级。
非 SUPER_ADMIN、OPERATOR 角色不展示字段级操作历史入口。

4.6 KiB 原始文件 Blame 文件历史 Unescape Escape