docs: 告知前端草原指南删除接口

changelogs/2026-07/13_feat_grassland_guide_delete.md

@@ -0,0 +1,74 @@
+# 草原指南管理新增仅下架可删除能力
+
+> 日期：2026-07-13
+>
+> 后端 Issue：[HL #4959](https://git.1814.love:8443/wx/HL/issues/4959)
+>
+> 后端 PR：[HL #4960](https://git.1814.love:8443/wx/HL/pulls/4960)，目标分支 `dev`
+>
+> 当前状态：`dev` PR 已创建，本地编译及目标单测通过；待合入 `dev` 后部署 TEST，暂未合入 `dev-v3`
+
+## 1. 变更范围
+
+草原指南管理新增删除接口。业务规则固定为：**只有已下架（`OFFLINE`）的视频可以删除**。
+
+本文件只说明删除能力，不包含 MP4 上传兼容校验、视频时长提取等媒体变更；媒体变更会使用另一份独立 changelog 告知。
+
+## 2. 接口
+
+`DELETE /admin/grassland-guide/videos/{videoId}`
+
+- 只提交路径参数 `videoId`。
+- 不发送请求体，也不提交 `version`。
+- 成功响应为平台统一成功包络，`data` 为空。
+- 后端内部使用状态和乐观锁控制并发，前端不维护版本号。
+
+请求示例：
+
+```http
+DELETE /admin/grassland-guide/videos/2076195939797688322
+```
+
+## 3. 前端交互规则
+
+- 仅当列表或详情的 `status` 为 `OFFLINE` 时展示“删除”按钮。
+- `DRAFT`、`PUBLISHED` 均不展示删除按钮。
+- 点击删除前展示二次确认；确认后调用删除接口。
+- 删除成功后刷新当前列表；若正在详情页，应返回列表。
+- 不要因为界面已判断状态就忽略后端错误，仍需处理并发变更结果。
+
+## 4. 权限
+
+新增按钮权限码：
+
+```text
+grassland-guide:delete
+```
+
+默认授权 `SUPER_ADMIN`、`OPERATOR`。前端同时依据按钮权限和业务状态决定是否展示删除入口。
+
+## 5. 错误处理
+
+| 业务码 | 含义 | 前端处理建议 |
+|---|---|---|
+| `371001` | 视频不存在或已经删除 | 提示内容不存在，并刷新列表 |
+| `371002` | 删除过程中数据被其他管理员修改 | 提示刷新后重试 |
+| `371008` | 当前状态不允许删除 | 提示“只有已下架内容可以删除”，并刷新当前数据 |
+
+## 6. 数据语义
+
+- 删除的是草原指南内容记录，不会删除对应的素材、文件或 OSS 对象。
+- 删除后该内容不再出现在管理端列表、详情和小程序接口中。
+- 后端会解除该内容对视频、封面和正文图片素材的引用。
+- 删除后不能通过重复调用接口恢复；如需再次使用素材，应重新创建草原指南内容。
+
+## 7. 联调清单
+
+后端在 `origin/dev` 基线上已完成 15 模块编译和 24 项目标单测；以下仍需管理端/测试环境联调确认：
+
+- [ ] `OFFLINE` 视频删除成功，列表和详情均不再返回。
+- [ ] `DRAFT`、`PUBLISHED` 视频没有删除入口，直接调用接口返回 `371008`。
+- [ ] 删除请求没有 body，也没有 `version`。
+- [ ] 重复删除返回 `371001`。
+- [ ] 无 `grassland-guide:delete` 权限时不展示入口。
+- [ ] 删除内容后，素材库中的原视频和封面仍然存在。