game_server/docs/公告接口使用示例.md

# 公告接口使用示例

## 接口概述

公告管理接口提供了完整的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": "公告标题不能为空"
}
```

**400 Bad Request** - 字段长度超限:
```json
{
    "timestamp": "2023-12-01T10:00:00.000+00:00",
    "status": 400,
    "error": "Bad Request",
    "message": "Validation failed",
    "errors": [
        {
            "field": "jumpUrl",
            "message": "跳转链接长度不能超过5000个字符"
        }
    ]
}
```

**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. `jumpUrl` 字段最大长度为 **5000个字符**，超过此限制将返回验证错误
6. 获取启用公告的接口最多返回10条记录
7. 所有时间字段使用 ISO 8601 格式

## 数据库表结构

公告数据存储在 `announcement` 表中，包含以下字段：

- `id` - 主键，自增
- `title` - 公告标题 (VARCHAR(100))
- `content` - 公告内容 (TEXT)
- `enabled` - 启用状态 (TINYINT(1))
- `jump_url` - 跳转链接 (VARCHAR(5000))，可选
- `belong_id` - 归属ID (INT)，关联用户ID
- `created_at` - 创建时间 (DATETIME(3))
- `updated_at` - 更新时间 (DATETIME(3))