hl-api-changelog/changelogs/2026-07/13_feat_grassland_guide_delete.md

草原指南管理新增仅下架可删除能力

日期：2026-07-13

后端 Issue：HL #4959

后端 PR：HL #4960，目标分支 dev

当前状态：dev PR 已创建，本地编译及目标单测通过；待合入 dev 后部署 TEST，暂未合入 dev-v3

1. 变更范围

草原指南管理新增删除接口。业务规则固定为：只有已下架（OFFLINE）的视频可以删除。

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

2. 接口

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

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

请求示例：

DELETE /admin/grassland-guide/videos/2076195939797688322

3. 前端交互规则

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

4. 权限

新增按钮权限码：

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 权限时不展示入口。
• 删除内容后，素材库中的原视频和封面仍然存在。