---
url: /docs/api-docs/v1/admin/release.md
---
# release — App 版本发布（5 action）

> 前缀：`/api/v1/admin/release/`
> 权限：`RELEASE_READ`（version-list/version-detail）· `RELEASE_WRITE`（set-rollout/force-upgrade/rollback）— 仅 **super + it**，operator 一律 403
> 代码：`src/app/admin/interface/api/release_mgmt.py` + `application/usecase/release_mgmt.py`

## 3.9.1 version-list —— 版本列表

`GET /api/v1/admin/release/version-list` · 权限 `RELEASE_READ`

**Query 参数**：

| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `page` | int | ⬜ | 1 | ≥1 |
| `page_size` | int | ⬜ | 20 | 1~100 |
| `platform` | string | ⬜ | — | 平台过滤 |
| `status` | string | ⬜ | — | 版本状态过滤 |

**响应 data**：`{ total, page, page_size, items: [VersionSummary] }`

`VersionSummary` 字段：

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` / `platform` | string | 版本 / 平台 |
| `version_code` / `version_name` | string | 版本号 / 展示名 |
| `status` | string | `draft` | `testing` | `gray` | `released` | `rolled_back` | `suspended` |
| `rollout_strategy` | string | null | 灰度策略 |
| `rollout_percentage` | int | null | 灰度百分比 |
| `device_count` | int | 覆盖设备数 |
| `created_at` | string | ISO |

**错误码**：`40201001` page/page\_size < 1。

## 3.9.2 version-detail —— 版本详情

`GET /api/v1/admin/release/version-detail/{version_id}` · 权限 `RELEASE_READ`

**响应 data**：

| 字段 | 类型 | 说明 |
|---|---|---|
| `version` | object | 全字段（含 `rolled_back_*`） |
| `rollout_status` | object | `{strategy, percentage, whitelist, blacklist, effective_at}` |
| `devices` | object | 设备覆盖统计 |

**错误码**：`40201701`（404）版本不存在。

## 3.9.3 set-rollout —— 设置灰度策略

`POST /api/v1/admin/release/set-rollout` · 权限 `RELEASE_WRITE`

**请求 body**：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `version_id` | string | ✅ | 目标版本 |
| `strategy` | string | ✅ | 灰度策略（如 percentage / whitelist） |
| `percentage` | int | null | ⬜ | 灰度百分比（0~100） |
| `lists` | string\[] | null | ⬜ | 白/黑名单 |

**响应 data**：`{ "success": true, "effective_at": "<ISO>" }`

**错误码**：`40201701`（404）· `40201702` 灰度策略冲突 · `40201704` 百分比越界（0-100）· `40201001` 参数非法。

## 3.9.4 force-upgrade —— 强制升级

`POST /api/v1/admin/release/force-upgrade` · 权限 `RELEASE_WRITE`

**请求 body**：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `from_version` | string | ✅ | 起始版本 |
| `to_version` | string | ✅ | 目标版本 |
| `message` | string | ✅ | 用户可见提示文案 |

**响应 data**：`{ "success": true, "rule": { ...下发规则 } }`

**错误码**：`40201701`（404）版本不存在 · `40201001` 参数非法。

## 3.9.5 rollback —— 版本回滚（⚠️ 高敏感）

`POST /api/v1/admin/release/rollback` · 权限 `RELEASE_WRITE` · **confirm\_text = `"ROLLBACK"`**

**请求 body**：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `version_id` | string | ✅ | 要回滚的版本 |
| `target_version` | string | ✅ | 回滚目标版本 |
| `reason` | string | ✅ | 回滚原因 |
| `confirm_text` | string | ✅ | **必须逐字为 `"ROLLBACK"`**，否则 `40201001`（400） |

**响应 data**：`{ "success": true, "rolled_back_at": "<ISO>" }`

**错误码**：

| code | 场景 |
|---|---|
| `40201701` | 版本不存在（404） |
| `40201702` | 灰度策略冲突（RELEASE\_ROLLOUT\_CONFLICT） |
| `40201703` | 回滚目标版本不存在 |
| `40201706` | 版本已回滚（重复回滚） |
| `40201001` | confirm\_text 不匹配 / 参数非法 |

**验收链路（§7.5）**：`rollback(confirm_text='ROLLBACK')` → 版本 rolled\_back → force-upgrade 下发规则 → audit 闭环。

***

**本域错误码汇总**：`40201701`-`40201706`（§6.9 release 区段）。通用失败见 [admin 总览](/api-docs/v1/admin/)。