fix: 系统公告弹窗前端

2025-11-05 23:12:23 +08:00
parent 09fb43ee14
commit 17337b8d78
21 changed files with 2729 additions and 17 deletions
--- a/Yi.Ai.Vue3/系统公告API接口文档.md
+++ b/Yi.Ai.Vue3/系统公告API接口文档.md
@@ -0,0 +1,232 @@
+# 系统公告 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 中，不需要后端接口支持。