game_server/docs/系统配置接口使用示例.md

# 系统配置接口使用示例

## 接口概览

系统配置接口提供了完整的CRUD操作，支持系统参数的管理和配置。基础路径：`/api/admin/config`

## 1. 基础配置管理

### 获取配置列表
```http
GET /api/admin/config/list?page=1&size=20
```

响应示例：
```json
{
  "items": [
    {
      "id": 1,
      "configKey": "link.default_quantity",
      "configValue": "50",
      "configType": "INTEGER",
      "description": "链接生成默认奖励点数",
      "isSystem": true,
      "createdAt": "2025-08-25T14:19:33.974",
      "updatedAt": "2025-08-25T14:19:33.974"
    }
  ],
  "total": 12,
  "page": 1,
  "size": 20
}
```

### 根据键获取配置
```http
GET /api/admin/config/key/link.default_quantity
```

### 根据类型获取配置
```http
GET /api/admin/config/type/INTEGER
```

### 创建配置
```http
POST /api/admin/config
Content-Type: application/json

{
  "configKey": "new.config.key",
  "configValue": "new value",
  "configType": "STRING",
  "description": "新的配置项",
  "isSystem": false
}
```

### 更新配置
```http
PUT /api/admin/config/1
Content-Type: application/json

{
  "configKey": "link.default_quantity",
  "configValue": "100",
  "configType": "INTEGER",
  "description": "链接生成默认奖励点数",
  "isSystem": true
}
```

### 删除配置
```http
DELETE /api/admin/config/1
```

### 根据键删除配置
```http
DELETE /api/admin/config/key/test.config
```

## 2. 专门配置获取接口

### 获取链接默认配置
```http
GET /api/admin/config/link/defaults
```

响应示例：
```json
{
  "defaultQuantity": 50,
  "refreshInterval": 300,
  "qrExpireTime": 14400,
  "maxTimesPerBatch": 100,
  "minQuantity": 10,
  "maxQuantity": 1000
}
```

### 获取脚本配置
```http
GET /api/admin/config/script/config
```

响应示例：
```json
{
  "serverUrl": "http://36.138.184.60:12345",
  "qrPathTemplate": "/{machineId}/二维码.png"
}
```

### 获取用户端配置
```http
GET /api/admin/config/user/config
```

响应示例：
```json
{
  "qrExpireSeconds": 60,
  "refreshWaitSeconds": 10,
  "linkExpireHours": 24,
  "assetsBaseUrl": "http://36.138.184.60:12345"
}
```

## 3. 批量操作接口

### 批量更新配置
```http
POST /api/admin/config/batch
Content-Type: application/json

{
  "configs": [
    {
      "configKey": "link.default_quantity",
      "configValue": "80",
      "configType": "INTEGER",
      "description": "链接生成默认奖励点数"
    },
    {
      "configKey": "link.refresh_interval",
      "configValue": "600",
      "configType": "INTEGER",
      "description": "链接刷新间隔（秒）"
    }
  ]
}
```

响应示例：
```json
{
  "success": true,
  "message": "批量更新成功",
  "updatedCount": 2
}
```

### 根据键快速更新配置值
```http
PUT /api/admin/config/key/link.default_quantity
Content-Type: application/json

"100"
```

响应示例：
```json
{
  "success": true,
  "message": "更新成功"
}
```

## 4. 配置类型说明

支持的配置类型：
- `STRING`: 字符串类型
- `INTEGER`: 整数类型
- `BOOLEAN`: 布尔类型（true/false）
- `JSON`: JSON格式数据

## 5. 错误处理

### 配置不存在
```json
{
  "status": 404,
  "message": "配置不存在"
}
```

### 配置验证失败
```json
{
  "success": false,
  "message": "配置验证失败",
  "errors": [
    "配置键 link.default_quantity 的值格式不正确"
  ]
}
```

### 配置值格式错误
```json
{
  "success": false,
  "message": "配置值格式不正确，期望类型: INTEGER"
}
```

## 6. 当前系统配置项

根据数据库数据，系统现有以下配置项：

### 链接相关配置
- `link.default_quantity`: 链接生成默认奖励点数（默认：50）
- `link.refresh_interval`: 链接刷新间隔秒数（默认：300）
- `link.qr_expire_time`: 二维码过期时间秒数（默认：14400）
- `link.max_times_per_batch`: 每批次最大刷奖励次数（默认：100）
- `link.min_quantity`: 最小奖励点数（默认：10）
- `link.max_quantity`: 最大奖励点数（默认：1000）

### 脚本相关配置
- `script.server_url`: 脚本服务器地址
- `script.qr_path_template`: 二维码图片路径模板

### 用户端相关配置
- `user.qr_expire_seconds`: 用户端二维码有效期秒数（默认：60）
- `user.refresh_wait_seconds`: 用户端刷新等待时间秒数（默认：10）
- `user.link_expire_hours`: 用户端链接有效期小时数（默认：24）
- `user.assets_base_url`: 用户端静态资源基础URL