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 总览。