233 lines
6.3 KiB
Markdown
233 lines
6.3 KiB
Markdown
# 系统公告 API 接口文档
|
||
|
||
## 概述
|
||
|
||
本文档定义了系统公告和活动功能所需的后端API接口。包括公告弹窗数据、活动详情、公告详情三个主要接口。
|
||
|
||
---
|
||
|
||
## 1. 获取系统公告和活动数据
|
||
|
||
### 接口信息
|
||
|
||
- **路径**: `GET /announcement/system`
|
||
- **描述**: 获取系统公告弹窗所需的所有数据，包括轮播图、活动列表、公告列表
|
||
- **权限**: 无需登录即可访问
|
||
|
||
### 响应数据结构
|
||
|
||
```typescript
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"carousels": [
|
||
{
|
||
"id": 1,
|
||
"imageUrl": "https://example.com/carousel/1.jpg",
|
||
"link": "https://example.com/activity/1",
|
||
"title": "新年活动"
|
||
}
|
||
],
|
||
"activities": [
|
||
{
|
||
"id": 1,
|
||
"title": "新年特惠活动",
|
||
"description": "参与活动即可获得丰厚奖励",
|
||
"content": "<p>活动详细内容HTML格式</p>",
|
||
"coverImage": "https://example.com/activity/cover1.jpg",
|
||
"startTime": "2025-01-01T00:00:00Z",
|
||
"endTime": "2025-01-31T23:59:59Z",
|
||
"status": "active",
|
||
"createdAt": "2025-01-01T00:00:00Z",
|
||
"updatedAt": "2025-01-02T00:00:00Z"
|
||
}
|
||
],
|
||
"announcements": [
|
||
{
|
||
"id": 1,
|
||
"title": "系统升级公告",
|
||
"content": "<p>系统将于今晚进行维护升级</p>",
|
||
"type": "latest",
|
||
"isImportant": true,
|
||
"publishTime": "2025-01-05T10:00:00Z",
|
||
"createdAt": "2025-01-05T09:00:00Z",
|
||
"updatedAt": "2025-01-05T10:00:00Z"
|
||
}
|
||
]
|
||
},
|
||
"message": "获取成功"
|
||
}
|
||
```
|
||
|
||
### 字段说明
|
||
|
||
#### carousels（轮播图）
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| id | number/string | 是 | 轮播图ID |
|
||
| imageUrl | string | 是 | 图片URL |
|
||
| link | string | 否 | 点击跳转链接 |
|
||
| title | string | 否 | 轮播图标题 |
|
||
|
||
#### activities（活动）
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| id | number/string | 是 | 活动ID |
|
||
| title | string | 是 | 活动标题 |
|
||
| description | string | 是 | 活动简介 |
|
||
| content | string | 是 | 活动详细内容（HTML格式） |
|
||
| coverImage | string | 否 | 封面图URL |
|
||
| startTime | string | 否 | 开始时间（ISO 8601格式） |
|
||
| endTime | string | 否 | 结束时间（ISO 8601格式） |
|
||
| status | string | 是 | 状态：active(进行中), inactive(未开始), expired(已结束) |
|
||
| createdAt | string | 是 | 创建时间（ISO 8601格式） |
|
||
| updatedAt | string | 否 | 更新时间（ISO 8601格式） |
|
||
|
||
#### announcements（公告）
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| id | number/string | 是 | 公告ID |
|
||
| title | string | 是 | 公告标题 |
|
||
| content | string | 是 | 公告内容（HTML格式） |
|
||
| type | string | 是 | 类型：latest(最新公告), history(历史公告) |
|
||
| isImportant | boolean | 否 | 是否重要公告（显示警告图标） |
|
||
| publishTime | string | 是 | 发布时间（ISO 8601格式） |
|
||
| createdAt | string | 是 | 创建时间（ISO 8601格式） |
|
||
| updatedAt | string | 否 | 更新时间（ISO 8601格式） |
|
||
|
||
---
|
||
|
||
## 2. 获取活动详情
|
||
|
||
### 接口信息
|
||
|
||
- **路径**: `GET /announcement/activity/{id}`
|
||
- **描述**: 获取单个活动的详细信息
|
||
- **权限**: 无需登录即可访问
|
||
|
||
### 请求参数
|
||
|
||
| 参数 | 位置 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|------|
|
||
| id | path | string/number | 是 | 活动ID |
|
||
|
||
### 响应数据结构
|
||
|
||
```typescript
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": 1,
|
||
"title": "新年特惠活动",
|
||
"description": "参与活动即可获得丰厚奖励",
|
||
"content": "<p>活动详细内容HTML格式...</p>",
|
||
"coverImage": "https://example.com/activity/cover1.jpg",
|
||
"startTime": "2025-01-01T00:00:00Z",
|
||
"endTime": "2025-01-31T23:59:59Z",
|
||
"status": "active",
|
||
"createdAt": "2025-01-01T00:00:00Z",
|
||
"updatedAt": "2025-01-02T00:00:00Z",
|
||
"views": 1234,
|
||
"participantCount": 567
|
||
},
|
||
"message": "获取成功"
|
||
}
|
||
```
|
||
|
||
### 额外字段说明
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| views | number | 否 | 浏览次数 |
|
||
| participantCount | number | 否 | 参与人数 |
|
||
|
||
---
|
||
|
||
## 3. 获取公告详情
|
||
|
||
### 接口信息
|
||
|
||
- **路径**: `GET /announcement/detail/{id}`
|
||
- **描述**: 获取单个公告的详细信息
|
||
- **权限**: 无需登录即可访问
|
||
|
||
### 请求参数
|
||
|
||
| 参数 | 位置 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|------|
|
||
| id | path | string/number | 是 | 公告ID |
|
||
|
||
### 响应数据结构
|
||
|
||
```typescript
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": 1,
|
||
"title": "系统升级公告",
|
||
"content": "<p>系统将于今晚进行维护升级，预计时间为晚上10点至次日凌晨2点...</p>",
|
||
"type": "latest",
|
||
"isImportant": true,
|
||
"publishTime": "2025-01-05T10:00:00Z",
|
||
"createdAt": "2025-01-05T09:00:00Z",
|
||
"updatedAt": "2025-01-05T10:00:00Z",
|
||
"views": 5678
|
||
},
|
||
"message": "获取成功"
|
||
}
|
||
```
|
||
|
||
### 额外字段说明
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| views | number | 否 | 浏览次数 |
|
||
|
||
---
|
||
|
||
## 错误响应
|
||
|
||
所有接口在出错时应返回统一的错误格式：
|
||
|
||
```typescript
|
||
{
|
||
"success": false,
|
||
"data": null,
|
||
"message": "错误描述信息",
|
||
"errorCode": "ERROR_CODE" // 可选的错误码
|
||
}
|
||
```
|
||
|
||
### 常见错误码
|
||
|
||
| 状态码 | 说明 |
|
||
|--------|------|
|
||
| 404 | 资源不存在 |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **时间格式**: 所有时间字段使用 ISO 8601 格式（如：`2025-01-05T10:00:00Z`）
|
||
2. **HTML内容**: content 字段包含HTML格式的内容，前端会进行渲染，请确保内容安全，防止XSS攻击
|
||
3. **图片URL**: 所有图片URL应该是完整的可访问地址
|
||
4. **状态管理**: 活动状态（active/inactive/expired）应该根据当前时间和活动时间自动判断
|
||
5. **公告分类**: 公告的 type 字段（latest/history）可以根据发布时间自动分类，或由管理员手动指定
|
||
6. **浏览统计**: views 字段建议在每次访问详情页时自动递增
|
||
|
||
---
|
||
|
||
## 前端状态管理
|
||
|
||
前端使用 Pinia 管理公告弹窗的显示状态：
|
||
|
||
- **今日关闭**: 24小时内不再显示
|
||
- **本周关闭**: 7天内不再显示
|
||
- **关闭公告**: 永久不再显示（除非用户清除浏览器缓存）
|
||
|
||
这些状态存储在浏览器的 localStorage 中，不需要后端接口支持。
|