740 lines
18 KiB
Markdown
740 lines
18 KiB
Markdown
# 系统配置管理 API 接口文档
|
||
|
||
## 基础信息
|
||
|
||
- **基础路径**: `/system_config`
|
||
- **认证方式**: 所有接口都需要在请求头中携带 `token`（通过 `mw.CheckAdmin` 中间件验证，需要管理员权限）
|
||
- **请求方法**: 所有接口均为 `POST`
|
||
|
||
## 响应格式说明
|
||
|
||
所有接口的响应格式统一为：
|
||
|
||
```json
|
||
{
|
||
"errCode": 0, // 错误码，0 表示成功
|
||
"errMsg": "", // 错误消息
|
||
"errDlt": "", // 错误详情
|
||
"data": {} // 响应数据
|
||
}
|
||
```
|
||
|
||
**注意**: 为了兼容 Ant Design Pro Table，前端在 `request` 函数中需要将响应格式转换为 ProTable 期望的格式：
|
||
|
||
```typescript
|
||
const request = async (params) => {
|
||
const response = await request('/system_config/list', {
|
||
method: 'POST',
|
||
data: params,
|
||
});
|
||
|
||
// 将 errCode 格式转换为 ProTable 期望的格式
|
||
return {
|
||
success: response.errCode === 0,
|
||
data: response.data?.list || [],
|
||
total: response.data?.total || 0,
|
||
};
|
||
};
|
||
```
|
||
|
||
## 公共数据结构
|
||
|
||
### SystemConfigInfo（系统配置信息）
|
||
|
||
```json
|
||
{
|
||
"key": "string", // 配置键（唯一标识）
|
||
"title": "string", // 配置标题
|
||
"value": "string", // 配置值（字符串形式存储，根据ValueType解析）
|
||
"valueType": 1, // 配置值类型：1-字符串，2-数字，3-布尔，4-JSON
|
||
"description": "string", // 配置描述
|
||
"enabled": true, // 是否启用（用于开关类配置）
|
||
"showInApp": false, // 是否在APP端展示（默认为false）
|
||
"createTime": 1234567890123, // 创建时间（毫秒时间戳）
|
||
"updateTime": 1234567890123 // 更新时间（毫秒时间戳）
|
||
}
|
||
```
|
||
|
||
### RequestPagination（分页信息）
|
||
|
||
```json
|
||
{
|
||
"pageNumber": 1, // 页码（从1开始）
|
||
"showNumber": 10 // 每页显示数量
|
||
}
|
||
```
|
||
|
||
### StringValue（可选字符串值）
|
||
|
||
```json
|
||
{
|
||
"value": "string" // 字符串值，如果为 null 或未设置则表示不更新该字段
|
||
}
|
||
```
|
||
|
||
### Int32Value（可选整数值）
|
||
|
||
```json
|
||
{
|
||
"value": 1 // 整数值，如果为 null 或未设置则表示不更新该字段
|
||
}
|
||
```
|
||
|
||
### BoolValue（可选布尔值）
|
||
|
||
```json
|
||
{
|
||
"value": true // 布尔值，如果为 null 或未设置则表示不更新该字段
|
||
}
|
||
```
|
||
|
||
## 配置值类型说明
|
||
|
||
- **1 - 字符串类型 (ConfigValueTypeString)**: 普通文本字符串
|
||
- **2 - 数字类型 (ConfigValueTypeNumber)**: 数值字符串，需要转换为数字使用
|
||
- **3 - 布尔类型 (ConfigValueTypeBool)**: 布尔值字符串（"true"/"false"），需要转换为布尔值使用
|
||
- **4 - JSON类型 (ConfigValueTypeJSON)**: JSON 格式字符串，需要解析为 JSON 对象使用
|
||
|
||
## 常用配置键
|
||
|
||
- `wallet.enabled`: 是否开启钱包功能（布尔类型）
|
||
- `register.phone.verify_code.enabled`: 手机号注册验证码功能是否开启（布尔类型）
|
||
|
||
---
|
||
|
||
## 1. 创建系统配置
|
||
|
||
**接口地址**: `POST /system_config/create`
|
||
|
||
**请求参数**:
|
||
|
||
```json
|
||
{
|
||
"key": "string", // 必填：配置键（唯一标识）
|
||
"title": "string", // 可选：配置标题
|
||
"value": "string|number|boolean|object", // 可选：配置值（支持多种类型，会根据 valueType 自动转换为字符串存储）
|
||
"valueType": 1, // 可选：配置值类型：1-字符串，2-数字，3-布尔，4-JSON（默认为1）
|
||
"description": "string", // 可选：配置描述
|
||
"enabled": true, // 可选：是否启用（默认为true）
|
||
"showInApp": false // 可选：是否在APP端展示（默认为false）
|
||
}
|
||
```
|
||
|
||
**注意**: `value` 字段支持多种类型传参，系统会根据 `valueType` 自动转换并验证：
|
||
- **字符串类型 (valueType=1)**: 可以传字符串，如 `"value": "hello"`
|
||
- **数字类型 (valueType=2)**: 可以传数字，如 `"value": 100` 或 `"value": 3.14`，会自动转换为字符串存储
|
||
- **布尔类型 (valueType=3)**: 可以传布尔值，如 `"value": true` 或 `"value": false`，会自动转换为 `"true"` 或 `"false"` 字符串存储
|
||
- **JSON类型 (valueType=4)**: 可以传 JSON 对象，如 `"value": {"key": "value"}`，会自动序列化为 JSON 字符串存储
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
**请求示例**:
|
||
|
||
**示例1: 布尔类型配置（推荐直接传布尔值）**
|
||
```json
|
||
{
|
||
"key": "wallet.enabled",
|
||
"title": "钱包功能开关",
|
||
"value": true, // ✅ 直接传布尔值，不需要传字符串 "true"
|
||
"valueType": 3,
|
||
"description": "控制是否开启钱包功能",
|
||
"enabled": true,
|
||
"showInApp": true // 在APP端展示此配置
|
||
}
|
||
```
|
||
|
||
**示例2: 数字类型配置（推荐直接传数字）**
|
||
```json
|
||
{
|
||
"key": "wallet.min_withdraw_amount",
|
||
"title": "最小提现金额",
|
||
"value": 100, // ✅ 直接传数字，会自动转换为字符串 "100" 存储
|
||
"valueType": 2,
|
||
"description": "用户提现的最小金额（单位：分）",
|
||
"enabled": true
|
||
}
|
||
```
|
||
|
||
**示例3: JSON类型配置（推荐直接传对象）**
|
||
```json
|
||
{
|
||
"key": "wallet.withdraw_config",
|
||
"title": "提现配置",
|
||
"value": { // ✅ 直接传 JSON 对象，会自动序列化为字符串存储
|
||
"dailyLimit": 10000,
|
||
"monthlyLimit": 100000,
|
||
"feeRate": 0.01
|
||
},
|
||
"valueType": 4,
|
||
"description": "提现相关配置（JSON格式）",
|
||
"enabled": true
|
||
}
|
||
```
|
||
|
||
**示例4: 字符串类型配置**
|
||
```json
|
||
{
|
||
"key": "wallet.welcome_message",
|
||
"title": "欢迎消息",
|
||
"value": "欢迎使用钱包功能", // ✅ 字符串类型直接传字符串
|
||
"valueType": 1,
|
||
"description": "钱包功能欢迎消息",
|
||
"enabled": true
|
||
}
|
||
```
|
||
|
||
**错误码**:
|
||
- `ErrArgs`: 配置键为空
|
||
- `ErrDuplicateKey`: 配置键已存在
|
||
|
||
---
|
||
|
||
## 2. 获取系统配置详情
|
||
|
||
**接口地址**: `POST /system_config/get`
|
||
|
||
**请求参数**:
|
||
|
||
```json
|
||
{
|
||
"key": "string" // 必填：配置键
|
||
}
|
||
```
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"config": { // 系统配置信息
|
||
"key": "string",
|
||
"title": "string",
|
||
"value": "string",
|
||
"valueType": 1,
|
||
"description": "string",
|
||
"enabled": true,
|
||
"createTime": 1234567890123,
|
||
"updateTime": 1234567890123
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**请求示例**:
|
||
|
||
```json
|
||
{
|
||
"key": "wallet.enabled"
|
||
}
|
||
```
|
||
|
||
**错误码**:
|
||
- `ErrNotFound`: 配置不存在
|
||
|
||
---
|
||
|
||
## 3. 获取所有系统配置（分页）
|
||
|
||
**接口地址**: `POST /system_config/list`
|
||
|
||
**请求参数**:
|
||
|
||
```json
|
||
{
|
||
"pagination": { // 必填：分页信息
|
||
"pageNumber": 1, // 页码（从1开始）
|
||
"showNumber": 10 // 每页显示数量
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"total": 100, // 总数
|
||
"list": [ // 配置列表（Ant Design Pro 标准格式）
|
||
{
|
||
"key": "string",
|
||
"title": "string",
|
||
"value": "string|number|boolean|object", // 根据 valueType 自动转换为对应类型
|
||
"valueType": 1,
|
||
"description": "string",
|
||
"enabled": true,
|
||
"createTime": 1234567890123,
|
||
"updateTime": 1234567890123
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**注意**: 返回的 `value` 字段会根据 `valueType` 自动转换为对应类型（详见"2. 获取系统配置详情"的说明）。
|
||
|
||
**请求示例**:
|
||
|
||
```json
|
||
{
|
||
"pagination": {
|
||
"pageNumber": 1,
|
||
"showNumber": 20
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 更新系统配置
|
||
|
||
**接口地址**: `POST /system_config/update`
|
||
|
||
**请求参数**:
|
||
|
||
```json
|
||
{
|
||
"key": "string", // 必填：配置键
|
||
"title": "string", // 可选：配置标题（如果为 null 则不更新）
|
||
"value": "string|number|boolean|object", // 可选：配置值（支持多种类型，会根据 valueType 自动转换）
|
||
"valueType": 1, // 可选：配置值类型（如果为 null 则不更新）
|
||
"description": "string", // 可选：配置描述（如果为 null 则不更新）
|
||
"enabled": true, // 可选：是否启用（如果为 null 则不更新）
|
||
"showInApp": false // 可选：是否在APP端展示（如果为 null 则不更新）
|
||
}
|
||
```
|
||
|
||
**注意**:
|
||
- `value` 字段支持多种类型传参，系统会根据当前的 `valueType`（或新设置的 `valueType`）自动转换并验证
|
||
- 如果同时更新 `value` 和 `valueType`，系统会验证新值是否符合新的类型要求
|
||
- 如果只更新 `valueType`，系统会验证当前值是否符合新的类型要求
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
**请求示例**:
|
||
|
||
**示例1: 更新布尔类型配置的值**
|
||
```json
|
||
{
|
||
"key": "wallet.enabled",
|
||
"value": false, // ✅ 直接传布尔值
|
||
"description": "已关闭钱包功能"
|
||
}
|
||
```
|
||
|
||
**示例2: 更新数字类型配置的值**
|
||
```json
|
||
{
|
||
"key": "wallet.min_withdraw_amount",
|
||
"value": 200 // ✅ 直接传数字
|
||
}
|
||
```
|
||
|
||
**示例3: 同时更新值和类型**
|
||
```json
|
||
{
|
||
"key": "wallet.min_amount",
|
||
"value": 150, // ✅ 新值
|
||
"valueType": 2 // 更新为数字类型
|
||
}
|
||
```
|
||
|
||
**注意**: 只有提供的字段才会被更新，未提供的字段保持不变。
|
||
|
||
**错误码**:
|
||
- `ErrNotFound`: 配置不存在
|
||
|
||
---
|
||
|
||
## 5. 更新系统配置值
|
||
|
||
**接口地址**: `POST /system_config/update_value`
|
||
|
||
**请求参数**:
|
||
|
||
```json
|
||
{
|
||
"key": "string", // 必填：配置键
|
||
"value": "string" // 必填：新的配置值
|
||
}
|
||
```
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
**请求示例**:
|
||
|
||
**示例1: 更新布尔类型配置**
|
||
```json
|
||
{
|
||
"key": "wallet.enabled",
|
||
"value": false // ✅ 直接传布尔值，不需要传字符串 "false"
|
||
}
|
||
```
|
||
|
||
**示例2: 更新数字类型配置**
|
||
```json
|
||
{
|
||
"key": "wallet.min_withdraw_amount",
|
||
"value": 200 // ✅ 直接传数字
|
||
}
|
||
```
|
||
|
||
**示例3: 更新 JSON 类型配置**
|
||
```json
|
||
{
|
||
"key": "wallet.withdraw_config",
|
||
"value": { // ✅ 直接传 JSON 对象
|
||
"dailyLimit": 20000,
|
||
"monthlyLimit": 200000
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码**:
|
||
- `ErrNotFound`: 配置不存在
|
||
|
||
---
|
||
|
||
## 6. 更新系统配置启用状态
|
||
|
||
**接口地址**: `POST /system_config/update_enabled`
|
||
|
||
**请求参数**:
|
||
|
||
```json
|
||
{
|
||
"key": "string", // 必填：配置键
|
||
"enabled": true // 必填：是否启用
|
||
}
|
||
```
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
**请求示例**:
|
||
|
||
```json
|
||
{
|
||
"key": "wallet.enabled",
|
||
"enabled": false
|
||
}
|
||
```
|
||
|
||
**错误码**:
|
||
- `ErrNotFound`: 配置不存在
|
||
|
||
---
|
||
|
||
## 7. 删除系统配置
|
||
|
||
**接口地址**: `POST /system_config/delete`
|
||
|
||
**请求参数**:
|
||
|
||
```json
|
||
{
|
||
"keys": ["string"] // 必填：配置键列表（支持批量删除）
|
||
}
|
||
```
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
**请求示例**:
|
||
|
||
```json
|
||
{
|
||
"keys": ["wallet.enabled", "register.phone.verify_code.enabled"]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 获取所有已启用的配置
|
||
|
||
**接口地址**: `POST /system_config/get_enabled`
|
||
|
||
**请求参数**:
|
||
|
||
```json
|
||
{}
|
||
```
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"list": [ // 已启用的配置列表（Ant Design Pro 标准格式）
|
||
{
|
||
"key": "string",
|
||
"title": "string",
|
||
"value": "string|number|boolean|object", // 根据 valueType 自动转换为对应类型
|
||
"valueType": 1,
|
||
"description": "string",
|
||
"enabled": true,
|
||
"createTime": 1234567890123,
|
||
"updateTime": 1234567890123
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**注意**: 返回的 `value` 字段会根据 `valueType` 自动转换为对应类型（详见"2. 获取系统配置详情"的说明）。
|
||
|
||
**请求示例**:
|
||
|
||
```json
|
||
{}
|
||
```
|
||
|
||
**说明**: 此接口用于获取所有已启用（enabled=true）的配置，通常用于前端展示或业务逻辑判断。
|
||
|
||
---
|
||
|
||
## 使用场景示例
|
||
|
||
### 场景1: 开启/关闭钱包功能
|
||
|
||
1. **创建钱包功能配置**（推荐直接传布尔值）:
|
||
```json
|
||
POST /system_config/create
|
||
{
|
||
"key": "wallet.enabled",
|
||
"title": "钱包功能开关",
|
||
"value": true, // ✅ 直接传布尔值，更直观
|
||
"valueType": 3,
|
||
"description": "控制是否开启钱包功能",
|
||
"enabled": true
|
||
}
|
||
```
|
||
|
||
2. **关闭钱包功能**（两种方式）:
|
||
|
||
方式1: 更新 enabled 字段
|
||
```json
|
||
POST /system_config/update_enabled
|
||
{
|
||
"key": "wallet.enabled",
|
||
"enabled": false
|
||
}
|
||
```
|
||
|
||
方式2: 更新 value 字段
|
||
```json
|
||
POST /system_config/update_value
|
||
{
|
||
"key": "wallet.enabled",
|
||
"value": false // ✅ 直接传布尔值
|
||
}
|
||
```
|
||
|
||
3. **业务代码中检查钱包功能是否开启**:
|
||
```go
|
||
config, err := db.GetSystemConfig(ctx, "wallet.enabled")
|
||
if err != nil || !config.Enabled {
|
||
return errors.New("钱包功能未开启")
|
||
}
|
||
```
|
||
|
||
### 场景2: 配置手机号注册验证码功能
|
||
|
||
1. **创建验证码功能配置**（推荐直接传布尔值）:
|
||
```json
|
||
POST /system_config/create
|
||
{
|
||
"key": "register.phone.verify_code.enabled",
|
||
"title": "手机号注册验证码功能",
|
||
"value": true, // ✅ 直接传布尔值
|
||
"valueType": 3,
|
||
"description": "控制手机号注册时是否需要验证码",
|
||
"enabled": true
|
||
}
|
||
```
|
||
|
||
### 场景3: 配置数字类型的参数（推荐直接传数字）
|
||
|
||
**创建配置**:
|
||
```json
|
||
POST /system_config/create
|
||
{
|
||
"key": "wallet.min_withdraw_amount",
|
||
"title": "最小提现金额",
|
||
"value": 100, // ✅ 直接传数字，会自动转换为字符串存储
|
||
"valueType": 2,
|
||
"description": "用户提现的最小金额（单位：分）",
|
||
"enabled": true
|
||
}
|
||
```
|
||
|
||
**获取配置**（返回时会自动转换为数字）:
|
||
```json
|
||
GET /system_config/get
|
||
{
|
||
"key": "wallet.min_withdraw_amount"
|
||
}
|
||
|
||
// 响应
|
||
{
|
||
"data": {
|
||
"config": {
|
||
"key": "wallet.min_withdraw_amount",
|
||
"value": 100, // ✅ 返回数字类型，不是字符串 "100"
|
||
"valueType": 2
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**后端使用**（如果直接使用数据库模型，需要手动转换）:
|
||
```go
|
||
config, _ := db.GetSystemConfig(ctx, "wallet.min_withdraw_amount")
|
||
minAmount, _ := strconv.ParseInt(config.Value, 10, 64)
|
||
```
|
||
|
||
### 场景4: 配置 JSON 类型的复杂参数（推荐直接传对象）
|
||
|
||
**创建配置**:
|
||
```json
|
||
POST /system_config/create
|
||
{
|
||
"key": "wallet.withdraw_config",
|
||
"title": "提现配置",
|
||
"value": { // ✅ 直接传 JSON 对象，会自动序列化为字符串存储
|
||
"dailyLimit": 10000,
|
||
"monthlyLimit": 100000,
|
||
"feeRate": 0.01
|
||
},
|
||
"valueType": 4,
|
||
"description": "提现相关配置（JSON格式）",
|
||
"enabled": true
|
||
}
|
||
```
|
||
|
||
**获取配置**（返回时会自动解析为对象）:
|
||
```json
|
||
GET /system_config/get
|
||
{
|
||
"key": "wallet.withdraw_config"
|
||
}
|
||
|
||
// 响应
|
||
{
|
||
"data": {
|
||
"config": {
|
||
"key": "wallet.withdraw_config",
|
||
"value": { // ✅ 返回 JSON 对象，不是字符串
|
||
"dailyLimit": 10000,
|
||
"monthlyLimit": 100000,
|
||
"feeRate": 0.01
|
||
},
|
||
"valueType": 4
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**后端使用**（如果直接使用数据库模型，需要手动解析）:
|
||
```go
|
||
config, _ := db.GetSystemConfig(ctx, "wallet.withdraw_config")
|
||
var withdrawConfig map[string]interface{}
|
||
json.Unmarshal([]byte(config.Value), &withdrawConfig)
|
||
```
|
||
|
||
---
|
||
|
||
## 错误码说明
|
||
|
||
- `ErrArgs`: 参数错误（如必填字段为空）
|
||
- `ErrNotFound`: 资源不存在（如配置键不存在）
|
||
- `ErrDuplicateKey`: 重复键（如创建配置时键已存在）
|
||
- `ErrNoPermission`: 无权限（非管理员用户）
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **配置键唯一性**: 配置键（key）在整个系统中必须唯一，不能重复。
|
||
|
||
2. **配置值类型转换**:
|
||
- **传参时**: `value` 字段支持多种类型（字符串、数字、布尔、JSON对象），系统会根据 `valueType` 自动转换为字符串存储
|
||
- **返回时**: `value` 字段会根据 `valueType` 自动转换为对应类型返回（数字返回数字，布尔返回布尔，JSON返回对象）
|
||
- **数据库存储**: 所有值都以字符串形式存储在数据库中
|
||
- **后端使用**: 如果直接使用数据库模型，需要根据 `valueType` 手动转换：
|
||
- 字符串类型：直接使用
|
||
- 数字类型：使用 `strconv.ParseInt` 或 `strconv.ParseFloat` 转换
|
||
- 布尔类型：使用 `strconv.ParseBool` 转换
|
||
- JSON类型：使用 `json.Unmarshal` 解析
|
||
|
||
3. **类型验证**: 系统会在创建和更新时自动验证 `value` 是否符合 `valueType` 的要求：
|
||
- 数字类型：必须是有效的数字
|
||
- 布尔类型：必须是 `true` 或 `false`
|
||
- JSON类型：必须是有效的 JSON
|
||
|
||
4. **可选字段更新**: 在 `UpdateSystemConfig` 接口中，如果字段为 `null` 或未设置，则不会更新该字段。
|
||
|
||
5. **启用状态**: `enabled` 字段用于控制配置是否生效。即使配置存在，如果 `enabled` 为 `false`，业务代码也应该认为该功能未开启。
|
||
|
||
6. **APP端展示**: `showInApp` 字段用于控制配置是否在APP端展示。只有 `showInApp` 为 `true` 的配置才会在APP端显示给用户。此字段默认为 `false`。
|
||
|
||
7. **推荐用法**:
|
||
- 创建/更新布尔类型配置时，推荐直接传布尔值：`"value": true` 而不是 `"value": "true"`
|
||
- 创建/更新数字类型配置时，推荐直接传数字：`"value": 100` 而不是 `"value": "100"`
|
||
- 创建/更新 JSON 类型配置时，推荐直接传对象：`"value": {"key": "value"}` 而不是 `"value": "{\"key\":\"value\"}"`
|
||
|
||
5. **管理员权限**: 所有接口都需要管理员权限，普通用户无法访问。
|
||
|
||
6. **请求头**: 所有请求都需要在请求头中携带 `token` 和 `operationid`。
|