channel — 支付/分发渠道（5 action）

前缀：/api/v1/admin/channel/ 权限：CHANNEL_READ（list/detail）· CHANNEL_WRITE（set-config/switch/close — close 高敏感）— 仅 super + it，operator 一律 403 代码：src/app/admin/interface/api/channel_mgmt.py + application/usecase/channel_mgmt.py

3.10.1 list —— 渠道列表

GET /api/v1/admin/channel/list · 权限 CHANNEL_READ

Query 参数：

字段	类型	必填	默认	说明
page	int	⬜	1	≥1
page_size	int	⬜	20	1~100
type	string	⬜	—	渠道类型（非法值 → 40201001）
status	string	⬜	—	渠道状态（非法值 → 40201001）

响应 data：{ total, page, page_size, items: [ChannelSummary] }

ChannelSummary 字段：

字段	类型	说明
id / name	string	渠道 / 名称
type	string	渠道类型
status	string	active | inactive | closed
request_count	int	请求计数（流量指向观测）
created_at	string	ISO

错误码：40201001 page/page_size < 1 / type/status 非法。

3.10.2 detail —— 渠道详情

GET /api/v1/admin/channel/detail/{channel_id} · 权限 CHANNEL_READ

响应 data：

字段	类型	说明
channel	object	全字段（含 migration_strategy）
integration_config	object	接入配置
stats	object	业务统计

错误码：40201721（404）渠道不存在。

3.10.3 set-config —— 更新渠道配置

POST /api/v1/admin/channel/set-config · 权限 CHANNEL_WRITE

请求 body：

字段	类型	必填	说明
channel_id	string	✅	目标渠道
config_key	string	✅	配置键
config_value	any	⬜	配置值

响应 data：{ "success": true }

错误码：40201721（404）· 40201723 渠道已关闭（不可再改配置）· 40201001 参数非法。

3.10.4 switch —— 渠道切换（流量迁移）

POST /api/v1/admin/channel/switch · 权限 CHANNEL_WRITE

请求 body：

字段	类型	必填	默认	说明
from_channel_id	string	✅	—	源渠道（切为 inactive）
to_channel_id	string	✅	—	目标渠道（切为 active）
migration_strategy	string	⬜	immediate	迁移策略

响应 data：{ "success": true, "migration_status": "<status>" }

错误码：

code	场景
40201721	渠道不存在（404）
40201722	切换失败（同渠 / 源渠道不可用）
40201723	渠道已关闭
40201001	参数非法

验收链路（§7.5）：switch 旧渠道（active→inactive）→ 新渠道（→active）→ list 流量指向断言 + audit。

3.10.5 close —— 关闭渠道（⚠️ 高敏感）

POST /api/v1/admin/channel/close · 权限 CHANNEL_WRITE · confirm_text = "CLOSE"

请求 body：

字段	类型	必填	说明
channel_id	string	✅	目标渠道
reason	string	✅	关闭原因
effective_at	string | null	⬜	生效时间（ISO；缺省立即）
confirm_text	string	✅	必须逐字为 "CLOSE"，否则 40201001（400）

响应 data：{ "success": true }

错误码：40201721（404）· 40201723 重复关闭 · 40201001 confirm_text 不匹配 / 参数非法。

---

本域错误码汇总：40201721-40201723（§6.9 channel 区段）。通用失败见 admin 总览。