---
url: /docs/api-docs/v1/admin/config.md
---
# config — 系统/业务/灰度/告警配置（12 action）

> 前缀：`/api/v1/admin/config/`
> 权限：四组 `GET → CONFIG_READ` · `PATCH → CONFIG_WRITE`；**dictionary 四动词全部 `CONFIG_WRITE`**（含 GET — §3.11.5 权限列字面，与 [misc/data-dictionary](/api-docs/v1/admin/misc) 的 MISC\_READ 只读入口分离）— 仅 **super + it**，operator 一律 403
> 代码：`src/app/admin/interface/api/config_mgmt.py` + `application/usecase/config_mgmt.py`

## 3.11.1 ~ 3.11.4 四组配置（system / business / rollout / alert）

### GET /api/v1/admin/config/{group} —— 读取配置组

`group` ∈ `system` | `business` | `rollout` | `alert` · 权限 `CONFIG_READ`

**响应 data**：

| 字段 | 类型 | 说明 |
|---|---|---|
| `group` | string | 配置组名 |
| `items` | array | 配置项数组 `[{key, value, ...}]`（rollout 组为 `[{key, strategy, percentage, ...}]`） |

**错误码**：`40201001` 非法配置组。

### PATCH /api/v1/admin/config/{group} —— 修改配置组

`group` 同上 · 权限 `CONFIG_WRITE`

**请求 body**：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `items` | array | ✅ | 待改配置项（system/business：`[{key, value}]`；rollout：`[{key, strategy, percentage?}]`） |
| `rules` | array | null | ⬜ | **alert 组专用**：`[{id, metric, threshold, channel}]`（整组替换） |

**响应 data**：`{ "success": true, "updated": <n> }`

**错误码**：

| code | 场景 |
|---|---|
| `40201741` | 配置键不存在（PATCH 只改存量键 — 新键走字典/发版流程） |
| `40201742` | 配置值非法 |
| `40201001` | 非法配置组 / items 缺失 |

## 3.11.5 dictionary —— 数据字典 CRUD（4 action）

⚠️ 四动词全部 `CONFIG_WRITE`。幂等键 = `(type, code)`。

### GET /api/v1/admin/config/dictionary

**Query**：`type`（可选 — 过滤字典类型）

**响应 data**：`{ "total": <n>, "items": [{type, code, label, value, sort}] }`

### POST /api/v1/admin/config/dictionary —— 新建

**请求 body**：

| 字段 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `type` | string | ✅ | — | 字典类型 |
| `code` | string | ✅ | — | 条目编码（type 内唯一） |
| `label` | string | ✅ | — | 展示名 |
| `value` | string | ✅ | — | 值 |
| `sort` | int | ⬜ | 0 | 排序 |

**响应 data**：`{ "success": true, "item": { ... } }`

**错误码**：`40201744` 条目已存在（幂等键冲突）· `40201001` 参数非法。

### PATCH /api/v1/admin/config/dictionary —— 更新

请求 body 同 POST 五字段（定位 + 新值）。

**响应 data**：`{ "success": true, "item": { ... } }`

**错误码**：`40201743` 条目不存在 · `40201001` 参数非法。

### DELETE /api/v1/admin/config/dictionary

**Query（必填）**：`type` · `code`

**响应 data**：`{ "success": true, "item": null }`

**错误码**：`40201743` 条目不存在。

***

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