Yi.Framework/Yi.Ai.Vue3/系统公告API接口文档.md

系统公告 API 接口文档

概述

本文档定义了系统公告和活动功能所需的后端API接口。包括公告弹窗数据、活动详情、公告详情三个主要接口。

---

1. 获取系统公告和活动数据

接口信息

• 路径: GET /announcement/system
• 描述: 获取系统公告弹窗所需的所有数据，包括轮播图、活动列表、公告列表
• 权限: 无需登录即可访问

响应数据结构

{
  "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

响应数据结构

{
  "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

响应数据结构

{
  "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	否	浏览次数

---

错误响应

所有接口在出错时应返回统一的错误格式：

{
  "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 中，不需要后端接口支持。