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

日期：2026-07-13

后端 Issue：HL #4959

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

纠正 PR：HL #4967 已合入 dev；HL #4968 已由 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 状态展示删除入口，并完成二次确认交互。
删除内容后，素材库中的原视频和封面仍然存在。

TEST 后端证据（2026-07-14）：

部署任务 f007ee1f 成功，资源服务 8082/8182 两实例均已更新、注册 Nacos 且健康。
实时 OpenAPI 摘要为“草稿或已下架状态允许”，DELETE 仅含路径参数 videoId，无 body、无 version。
验收内容：DRAFT 删除成功；OFFLINE 删除成功；PUBLISHED 返回 371008 且状态、版本、引用数、日志数完全不变；重复删除返回 371001。
DRAFT 发布/删除与 OFFLINE 重发/删除各执行一次真实并发竞争，两组均恰好一方成功，失败方返回 371002，最终状态与事务副作用正确。
5 条验收内容均已逻辑删除，素材引用和推荐关系均无残留，每条仅产生一条 DELETE 领域日志，fromStatus 仅为 DRAFT 或 OFFLINE。
真实 4K OSS 素材 2076658080942116865 的 fileId、OSS URL 与引用计数恢复基线，OSS HEAD 返回 200、文件大小 412400073 字节，未删除素材、文件或 OSS 对象。
/admin/menu/my 已返回 grassland-guide:delete，TEST 数据库已授权 OPERATOR、SUPER_ADMIN。

注意：前端不提交 version；并发控制由后端内部实现。前端只需按 DRAFT/OFFLINE 展示入口，并处理并发失败响应。

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