docs: 告知草原指南字段级操作记录接口

2026-07-14 14:44:47 +08:00 · 2026-07-14 14:44:47 +08:00 · a43f11f767
--- a/changelogs/2026-07/14_feat_grassland_guide_operation_logs.md
+++ b/changelogs/2026-07/14_feat_grassland_guide_operation_logs.md
@ -0,0 +1,128 @@
+# 草原指南字段级操作记录与分页接口
+
+> 日期：2026-07-14
+>
+> 后端 Issue：[HL #4977](https://git.1814.love:8443/wx/HL/issues/4977)
+>
+> 发布范围：先合入 `dev`，再同步 `dev-v3` 并部署 TEST；当前不合入 `main`、不部署正式环境
+
+## 1. 变更目的
+
+草原指南编辑页原“操作记录”只有创建时间和最后编辑时间，无法说明谁修改了什么。本次新增独立分页接口，响应结构参考产品日志时间线，提供：
+
+- 操作类型和中文摘要；
+- 操作所属页面区域；
+- 操作人 ID、名称快照和操作时间；
+- 本次真实变化的字段；
+- 字段中文名、旧值、新值和变更类型；
+- 富文本、正文图片和生效封面等长值的摘要与哈希。
+
+## 2. 接口
+
+```http
+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. 响应示例
+
+```json
+{
+  "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` 角色不展示字段级操作历史入口。