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

> 日期：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)、[HL #4963](https://git.1814.love:8443/wx/HL/pulls/4963) 实现的是旧规则，已被本次业务口径纠正取代
>
> 纠正 PR：[HL #4967](https://git.1814.love:8443/wx/HL/pulls/4967) 已合入 `dev`；[HL #4968](https://git.1814.love:8443/wx/HL/pulls/4968) 已由 `dev` 合入 `dev-v3`
>
> 当前状态：TEST 双实例部署与真实接口验收通过；尚未合入 `main`、尚未部署正式环境

## 1. 变更范围

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

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

## 2. 接口

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

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

请求示例：

```http
DELETE /admin/grassland-guide/videos/2076195939797688322
```

## 3. 前端交互规则

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

## 4. 权限

新增按钮权限码：

```text
grassland-guide:delete
```

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

## 5. 错误处理

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

## 6. 数据语义

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

## 7. 联调清单

后端新规则与 TEST 验收已完成，前端联调清单如下：

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

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` 展示入口，并处理并发失败响应。