feat: 新增用户端配置获取和批量更新接口
主要修改: 1. 在SystemConfigController中新增获取用户端配置的接口。 2. 实现批量更新系统配置的接口，支持根据配置键进行更新。 3. 增强SystemConfigService，添加用户端相关配置的获取方法及配置值验证逻辑。 技术细节: - 新增的接口提升了系统配置管理的灵活性，支持批量操作和用户端配置的动态获取。
This commit is contained in:
zyh
237
docs/系统配置接口使用示例.md
Normal file
237
docs/系统配置接口使用示例.md
Normal file
@@ -0,0 +1,237 @@
|
||||
# 系统配置接口使用示例
|
||||
|
||||
## 接口概览
|
||||
|
||||
系统配置接口提供了完整的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
|
||||
Reference in New Issue
Block a user