草原指南管理删除能力（草稿/下架可删）

日期：2026-07-13

后端 Issue：HL #4959

历史 PR：HL #4960、HL #4963 实现的是旧规则，已被本次业务口径纠正取代

当前状态：后端正在按纠正后的规则重新实现并回归；完成后先合入 dev，再由 dev 合入 dev-v3 部署 TEST；不合入 main、不部署正式环境

1. 变更范围

草原指南管理提供删除接口。业务规则固定为：未上线内容可以删除，其中草稿（DRAFT）和已下架（OFFLINE）允许删除；已上线（PUBLISHED）不允许删除。

本文件只说明删除能力，不包含 MP4 上传兼容校验、视频时长提取等媒体变更；媒体变更会使用另一份独立 changelog 告知。

2. 接口

DELETE /admin/grassland-guide/videos/{videoId}

只提交路径参数 videoId。
不发送请求体，也不提交 version。
成功响应为平台统一成功包络，data 为空。
后端内部使用状态和乐观锁控制并发，前端不维护版本号。

请求示例：

DELETE /admin/grassland-guide/videos/2076195939797688322

3. 前端交互规则

当列表或详情的 status 为 DRAFT 或 OFFLINE 时展示“删除”按钮。
PUBLISHED 不展示删除按钮。
点击删除前展示二次确认；确认后调用删除接口。
删除成功后刷新当前列表；若正在详情页，应返回列表。
不要因为界面已判断状态就忽略后端错误，仍需处理并发变更结果。

4. 权限

新增按钮权限码：

grassland-guide:delete

默认授权 SUPER_ADMIN、OPERATOR。前端同时依据按钮权限和业务状态决定是否展示删除入口。

5. 错误处理

业务码	含义	前端处理建议
`371001`	视频不存在或已经删除	提示内容不存在，并刷新列表
`371002`	删除过程中数据被其他管理员修改	提示刷新后重试
`371008`	已上线内容不允许删除	提示“已上线内容不能删除”，并刷新当前数据

6. 数据语义

删除的是草原指南内容记录，不会删除对应的素材、文件或 OSS 对象。
删除后该内容不再出现在管理端列表、详情和小程序接口中。
后端会解除该内容对视频、封面和正文图片素材的引用。
删除后不能通过重复调用接口恢复；如需再次使用素材，应重新创建草原指南内容。

7. 联调清单

后端完成新规则回归及 TEST 验收后更新本节证据。前端联调清单如下：

DRAFT、OFFLINE 视频删除成功，管理端详情和小程序详情、列表均不再返回。
PUBLISHED 直接调用删除接口返回 371008，数据和引用关系不变。
删除请求没有 body，也没有 version。
重复删除返回 371001。
无 grassland-guide:delete 权限时不展示入口。
管理端仅在 DRAFT、OFFLINE 状态展示删除入口，并完成二次确认交互。
删除内容后，素材库中的原视频和封面仍然存在。

注意：前端不提交 version；并发控制由后端内部实现。历史 TEST 证据基于旧规则，不作为本次纠正后的验收结论。

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