# 系统公告 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 中，不需要后端接口支持。