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

日期：2026-07-13

后端 Issue：HL #4959

后端 PR：HL #4960，已合入 dev；随后通过 HL #4963 由 dev 合入 dev-v3

当前状态：已合入 dev 和 dev-v3，TEST 双实例部署及真实接口验收通过；尚未合入 main、尚未部署正式环境

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 项目标单测；TEST 已完成接口验收，管理端 UI 仍需前端联调：

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

TEST 证据：验收内容 ID 2076674584685240321 已完成 DRAFT → PUBLISHED → OFFLINE → 删除 全状态流转；删除前尝试删除被引用素材返回 371009，删除内容后素材 2076658080942116865 仍保留且状态为 OSS_MP4_READY_V1。

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