# 系统配置管理 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`。