itom-group/chat-deploy

Fork 0

Files

kim.dev.6789 b7f8db7d08 复制项目

2026-01-14 22:35:45 +08:00

18 KiB

Raw Blame History

系统配置管理 API 接口文档

基础信息

基础路径: /system_config
认证方式: 所有接口都需要在请求头中携带 token（通过 mw.CheckAdmin 中间件验证，需要管理员权限）
请求方法: 所有接口均为 POST

响应格式说明

所有接口的响应格式统一为：

{
  "errCode": 0,        // 错误码，0 表示成功
  "errMsg": "",        // 错误消息
  "errDlt": "",        // 错误详情
  "data": {}           // 响应数据
}

注意: 为了兼容 Ant Design Pro Table，前端在 request 函数中需要将响应格式转换为 ProTable 期望的格式：

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（系统配置信息）

{
  "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（分页信息）

{
  "pageNumber": 1,    // 页码（从1开始）
  "showNumber": 10    // 每页显示数量
}

StringValue（可选字符串值）

{
  "value": "string"   // 字符串值，如果为 null 或未设置则表示不更新该字段
}

Int32Value（可选整数值）

{
  "value": 1          // 整数值，如果为 null 或未设置则表示不更新该字段
}

BoolValue（可选布尔值）

{
  "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

请求参数:

{
  "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 字符串存储

响应参数:

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {}
}

请求示例:

示例1: 布尔类型配置（推荐直接传布尔值）

{
  "key": "wallet.enabled",
  "title": "钱包功能开关",
  "value": true,                      // ✅ 直接传布尔值，不需要传字符串 "true"
  "valueType": 3,
  "description": "控制是否开启钱包功能",
  "enabled": true,
  "showInApp": true                   // 在APP端展示此配置
}

示例2: 数字类型配置（推荐直接传数字）

{
  "key": "wallet.min_withdraw_amount",
  "title": "最小提现金额",
  "value": 100,                        // ✅ 直接传数字，会自动转换为字符串 "100" 存储
  "valueType": 2,
  "description": "用户提现的最小金额（单位：分）",
  "enabled": true
}

示例3: JSON类型配置（推荐直接传对象）

{
  "key": "wallet.withdraw_config",
  "title": "提现配置",
  "value": {                           // ✅ 直接传 JSON 对象，会自动序列化为字符串存储
    "dailyLimit": 10000,
    "monthlyLimit": 100000,
    "feeRate": 0.01
  },
  "valueType": 4,
  "description": "提现相关配置（JSON格式）",
  "enabled": true
}

示例4: 字符串类型配置

{
  "key": "wallet.welcome_message",
  "title": "欢迎消息",
  "value": "欢迎使用钱包功能",          // ✅ 字符串类型直接传字符串
  "valueType": 1,
  "description": "钱包功能欢迎消息",
  "enabled": true
}

错误码:

ErrArgs: 配置键为空
ErrDuplicateKey: 配置键已存在

2. 获取系统配置详情

接口地址: POST /system_config/get

请求参数:

{
  "key": "string"                     // 必填：配置键
}

响应参数:

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "config": {                       // 系统配置信息
      "key": "string",
      "title": "string",
      "value": "string",
      "valueType": 1,
      "description": "string",
      "enabled": true,
      "createTime": 1234567890123,
      "updateTime": 1234567890123
    }
  }
}

请求示例:

{
  "key": "wallet.enabled"
}

错误码:

ErrNotFound: 配置不存在

3. 获取所有系统配置（分页）

接口地址: POST /system_config/list

请求参数:

{
  "pagination": {                    // 必填：分页信息
    "pageNumber": 1,                 // 页码（从1开始）
    "showNumber": 10                 // 每页显示数量
  }
}

响应参数:

{
  "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. 获取系统配置详情"的说明）。

请求示例:

{
  "pagination": {
    "pageNumber": 1,
    "showNumber": 20
  }
}

4. 更新系统配置

接口地址: POST /system_config/update

请求参数:

{
  "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，系统会验证当前值是否符合新的类型要求

响应参数:

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {}
}

请求示例:

示例1: 更新布尔类型配置的值

{
  "key": "wallet.enabled",
  "value": false,                     // ✅ 直接传布尔值
  "description": "已关闭钱包功能"
}

示例2: 更新数字类型配置的值

{
  "key": "wallet.min_withdraw_amount",
  "value": 200                        // ✅ 直接传数字
}

示例3: 同时更新值和类型

{
  "key": "wallet.min_amount",
  "value": 150,                       // ✅ 新值
  "valueType": 2                      // 更新为数字类型
}

注意: 只有提供的字段才会被更新，未提供的字段保持不变。

错误码:

ErrNotFound: 配置不存在

5. 更新系统配置值

接口地址: POST /system_config/update_value

请求参数:

{
  "key": "string",                    // 必填：配置键
  "value": "string"                   // 必填：新的配置值
}

响应参数:

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {}
}

请求示例:

示例1: 更新布尔类型配置

{
  "key": "wallet.enabled",
  "value": false                      // ✅ 直接传布尔值，不需要传字符串 "false"
}

示例2: 更新数字类型配置

{
  "key": "wallet.min_withdraw_amount",
  "value": 200                        // ✅ 直接传数字
}

示例3: 更新 JSON 类型配置

{
  "key": "wallet.withdraw_config",
  "value": {                          // ✅ 直接传 JSON 对象
    "dailyLimit": 20000,
    "monthlyLimit": 200000
  }
}

错误码:

ErrNotFound: 配置不存在

6. 更新系统配置启用状态

接口地址: POST /system_config/update_enabled

请求参数:

{
  "key": "string",                    // 必填：配置键
  "enabled": true                     // 必填：是否启用
}

响应参数:

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {}
}

请求示例:

{
  "key": "wallet.enabled",
  "enabled": false
}

错误码:

ErrNotFound: 配置不存在

7. 删除系统配置

接口地址: POST /system_config/delete

请求参数:

{
  "keys": ["string"]                  // 必填：配置键列表（支持批量删除）
}

响应参数:

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {}
}

请求示例:

{
  "keys": ["wallet.enabled", "register.phone.verify_code.enabled"]
}

8. 获取所有已启用的配置

接口地址: POST /system_config/get_enabled

请求参数:

{}

响应参数:

{
  "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. 获取系统配置详情"的说明）。

请求示例:

{}

说明: 此接口用于获取所有已启用（enabled=true）的配置，通常用于前端展示或业务逻辑判断。

使用场景示例

场景1: 开启/关闭钱包功能

创建钱包功能配置（推荐直接传布尔值）:

POST /system_config/create
{
  "key": "wallet.enabled",
  "title": "钱包功能开关",
  "value": true,                     // ✅ 直接传布尔值，更直观
  "valueType": 3,
  "description": "控制是否开启钱包功能",
  "enabled": true
}

关闭钱包功能（两种方式）:

方式1: 更新 enabled 字段

POST /system_config/update_enabled
{
  "key": "wallet.enabled",
  "enabled": false
}

方式2: 更新 value 字段

POST /system_config/update_value
{
  "key": "wallet.enabled",
  "value": false                     // ✅ 直接传布尔值
}

业务代码中检查钱包功能是否开启:

config, err := db.GetSystemConfig(ctx, "wallet.enabled")
if err != nil || !config.Enabled {
    return errors.New("钱包功能未开启")
}

场景2: 配置手机号注册验证码功能

创建验证码功能配置（推荐直接传布尔值）:

POST /system_config/create
{
  "key": "register.phone.verify_code.enabled",
  "title": "手机号注册验证码功能",
  "value": true,                     // ✅ 直接传布尔值
  "valueType": 3,
  "description": "控制手机号注册时是否需要验证码",
  "enabled": true
}

场景3: 配置数字类型的参数（推荐直接传数字）

创建配置:

POST /system_config/create
{
  "key": "wallet.min_withdraw_amount",
  "title": "最小提现金额",
  "value": 100,                       // ✅ 直接传数字，会自动转换为字符串存储
  "valueType": 2,
  "description": "用户提现的最小金额（单位：分）",
  "enabled": true
}

获取配置（返回时会自动转换为数字）:

GET /system_config/get
{
  "key": "wallet.min_withdraw_amount"
}

// 响应
{
  "data": {
    "config": {
      "key": "wallet.min_withdraw_amount",
      "value": 100,                   // ✅ 返回数字类型，不是字符串 "100"
      "valueType": 2
    }
  }
}

后端使用（如果直接使用数据库模型，需要手动转换）:

config, _ := db.GetSystemConfig(ctx, "wallet.min_withdraw_amount")
minAmount, _ := strconv.ParseInt(config.Value, 10, 64)

场景4: 配置 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
}

获取配置（返回时会自动解析为对象）:

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
    }
  }
}

后端使用（如果直接使用数据库模型，需要手动解析）:

config, _ := db.GetSystemConfig(ctx, "wallet.withdraw_config")
var withdrawConfig map[string]interface{}
json.Unmarshal([]byte(config.Value), &withdrawConfig)

错误码说明

ErrArgs: 参数错误（如必填字段为空）
ErrNotFound: 资源不存在（如配置键不存在）
ErrDuplicateKey: 重复键（如创建配置时键已存在）
ErrNoPermission: 无权限（非管理员用户）

注意事项

配置键唯一性: 配置键（key）在整个系统中必须唯一，不能重复。
配置值类型转换:
- 传参时: value 字段支持多种类型（字符串、数字、布尔、JSON对象），系统会根据 valueType 自动转换为字符串存储
- 返回时: value 字段会根据 valueType 自动转换为对应类型返回（数字返回数字，布尔返回布尔，JSON返回对象）
- 数据库存储: 所有值都以字符串形式存储在数据库中
- 后端使用: 如果直接使用数据库模型，需要根据 valueType 手动转换：
  - 字符串类型：直接使用
  - 数字类型：使用 strconv.ParseInt 或 strconv.ParseFloat 转换
  - 布尔类型：使用 strconv.ParseBool 转换
  - JSON类型：使用 json.Unmarshal 解析
类型验证: 系统会在创建和更新时自动验证 value 是否符合 valueType 的要求：
- 数字类型：必须是有效的数字
- 布尔类型：必须是 true 或 false
- JSON类型：必须是有效的 JSON
可选字段更新: 在 UpdateSystemConfig 接口中，如果字段为 null 或未设置，则不会更新该字段。
启用状态: enabled 字段用于控制配置是否生效。即使配置存在，如果 enabled 为 false，业务代码也应该认为该功能未开启。
APP端展示: showInApp 字段用于控制配置是否在APP端展示。只有 showInApp 为 true 的配置才会在APP端显示给用户。此字段默认为 false。
推荐用法:
- 创建/更新布尔类型配置时，推荐直接传布尔值："value": true 而不是 "value": "true"
- 创建/更新数字类型配置时，推荐直接传数字："value": 100 而不是 "value": "100"
- 创建/更新 JSON 类型配置时，推荐直接传对象："value": {"key": "value"} 而不是 "value": "{\"key\":\"value\"}"
管理员权限: 所有接口都需要管理员权限，普通用户无法访问。
请求头: 所有请求都需要在请求头中携带 token 和 operationid。

18 KiB Raw Blame History Unescape Escape

系统配置管理 API 接口文档

基础信息

响应格式说明

公共数据结构

SystemConfigInfo（系统配置信息）

RequestPagination（分页信息）

StringValue（可选字符串值）

Int32Value（可选整数值）

BoolValue（可选布尔值）

配置值类型说明

常用配置键

1. 创建系统配置

2. 获取系统配置详情

3. 获取所有系统配置（分页）

4. 更新系统配置

5. 更新系统配置值

6. 更新系统配置启用状态

7. 删除系统配置

8. 获取所有已启用的配置

使用场景示例

场景1: 开启/关闭钱包功能

场景2: 配置手机号注册验证码功能

场景3: 配置数字类型的参数（推荐直接传数字）

场景4: 配置 JSON 类型的复杂参数（推荐直接传对象）

错误码说明

注意事项

18 KiB

Raw Blame History