feat: 增强用户端配置管理功能
主要修改: 1. 在SystemConfigController中完善用户端配置获取和批量更新接口的实现。 2. 优化SystemConfigService，增强配置值验证逻辑，确保配置的准确性和有效性。 技术细节: - 新增的功能提升了用户端配置的管理灵活性，支持更高效的批量操作。
This commit is contained in:
zyh
216
docs/公告接口使用示例.md
Normal file
216
docs/公告接口使用示例.md
Normal file
@@ -0,0 +1,216 @@
|
||||
# 公告接口使用示例
|
||||
|
||||
## 接口概述
|
||||
|
||||
公告管理接口提供了完整的CRUD操作，包括创建、查询、更新和删除公告的功能。
|
||||
|
||||
**基础路径**: `/api/admin/announcement`
|
||||
|
||||
## 接口列表
|
||||
|
||||
### 1. 创建公告
|
||||
|
||||
**POST** `/api/admin/announcement`
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"title": "系统维护通知",
|
||||
"content": "系统将于今晚10点进行维护，预计维护时间2小时",
|
||||
"enabled": true,
|
||||
"jumpUrl": "https://example.com"
|
||||
}
|
||||
```
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "公告创建成功",
|
||||
"id": 1
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 获取公告列表（分页）
|
||||
|
||||
**GET** `/api/admin/announcement/list?page=1&size=20&enabled=true`
|
||||
|
||||
**参数**:
|
||||
- `page`: 页码（默认1）
|
||||
- `size`: 每页大小（默认20）
|
||||
- `enabled`: 按启用状态筛选（可选）
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"items": [
|
||||
{
|
||||
"id": 1,
|
||||
"title": "系统维护通知",
|
||||
"content": "系统将于今晚10点进行维护，预计维护时间2小时",
|
||||
"enabled": true,
|
||||
"jumpUrl": "https://example.com",
|
||||
"createdAt": "2023-12-01T10:00:00",
|
||||
"updatedAt": "2023-12-01T10:00:00"
|
||||
}
|
||||
],
|
||||
"total": 1,
|
||||
"page": 1,
|
||||
"size": 20
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 获取公告详情
|
||||
|
||||
**GET** `/api/admin/announcement/{id}`
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"title": "系统维护通知",
|
||||
"content": "系统将于今晚10点进行维护，预计维护时间2小时",
|
||||
"enabled": true,
|
||||
"jumpUrl": "https://example.com",
|
||||
"createdAt": "2023-12-01T10:00:00",
|
||||
"updatedAt": "2023-12-01T10:00:00"
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 更新公告
|
||||
|
||||
**PUT** `/api/admin/announcement/{id}`
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"title": "系统维护通知（更新）",
|
||||
"content": "系统维护已完成",
|
||||
"enabled": false,
|
||||
"jumpUrl": null
|
||||
}
|
||||
```
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "公告更新成功"
|
||||
}
|
||||
```
|
||||
|
||||
### 5. 删除公告
|
||||
|
||||
**DELETE** `/api/admin/announcement/{id}`
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "公告删除成功"
|
||||
}
|
||||
```
|
||||
|
||||
### 6. 更新公告启用状态
|
||||
|
||||
**PUT** `/api/admin/announcement/{id}/enabled?enabled=true`
|
||||
|
||||
**参数**:
|
||||
- `enabled`: 启用状态（true/false）
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "公告已启用"
|
||||
}
|
||||
```
|
||||
|
||||
### 7. 获取启用的公告
|
||||
|
||||
**GET** `/api/admin/announcement/enabled`
|
||||
|
||||
**响应**:
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 1,
|
||||
"title": "系统维护通知",
|
||||
"content": "系统将于今晚10点进行维护，预计维护时间2小时",
|
||||
"enabled": true,
|
||||
"jumpUrl": "https://example.com",
|
||||
"createdAt": "2023-12-01T10:00:00",
|
||||
"updatedAt": "2023-12-01T10:00:00"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## curl 示例
|
||||
|
||||
### 创建公告
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/admin/announcement \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
|
||||
-d '{
|
||||
"title": "系统维护通知",
|
||||
"content": "系统将于今晚10点进行维护，预计维护时间2小时",
|
||||
"enabled": true,
|
||||
"jumpUrl": "https://example.com"
|
||||
}'
|
||||
```
|
||||
|
||||
### 获取公告列表
|
||||
```bash
|
||||
curl -X GET "http://localhost:8080/api/admin/announcement/list?page=1&size=10&enabled=true" \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||||
```
|
||||
|
||||
### 更新公告状态
|
||||
```bash
|
||||
curl -X PUT "http://localhost:8080/api/admin/announcement/1/enabled?enabled=false" \
|
||||
-H "Authorization: Bearer YOUR_JWT_TOKEN"
|
||||
```
|
||||
|
||||
## 错误处理
|
||||
|
||||
### 常见错误响应
|
||||
|
||||
**400 Bad Request** - 参数错误:
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "公告标题不能为空"
|
||||
}
|
||||
```
|
||||
|
||||
**404 Not Found** - 公告不存在:
|
||||
```json
|
||||
{
|
||||
"timestamp": "2023-12-01T10:00:00.000+00:00",
|
||||
"status": 404,
|
||||
"error": "Not Found",
|
||||
"path": "/api/admin/announcement/999"
|
||||
}
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. 所有管理接口都需要JWT认证
|
||||
2. 公告标题和内容不能为空
|
||||
3. `enabled` 字段默认为 `false`
|
||||
4. `jumpUrl` 字段可选，用于设置点击公告后的跳转链接
|
||||
5. 获取启用公告的接口最多返回10条记录
|
||||
6. 所有时间字段使用 ISO 8601 格式
|
||||
|
||||
## 数据库表结构
|
||||
|
||||
公告数据存储在 `announcement` 表中，包含以下字段：
|
||||
|
||||
- `id` - 主键，自增
|
||||
- `title` - 公告标题
|
||||
- `content` - 公告内容
|
||||
- `enabled` - 启用状态
|
||||
- `jump_url` - 跳转链接
|
||||
- `created_at` - 创建时间
|
||||
- `updated_at` - 更新时间
|
||||
Reference in New Issue
Block a user