# 通知和公告

## 相关源文件

- [](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java)
- [](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/vo/AchievementVO.java)
- [](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/vo/AiAvatarVO.java)
- [](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/vo/AnnouncementVO.java)

## 目的和范围

本文档提供了 SmartClass 后端公告系统的全面概述。该系统使管理员能够创建、管理和发布重要公告给平台用户。它还跟踪用户是否已阅读公告，并管理公告的生命周期，包括发布时间表、可见性状态和查看指标。

公告系统提供了一种集中方式，向用户传达重要更新、维护通知、新功能或其他关键信息。本文档仅关注全系统范围的公告；有关用户间消息传递或课程特定通知的信息，请参阅文档的其他部分。

## 系统概述

公告系统允许管理员创建和管理具有特定显示周期、优先级和状态跟踪的公告。用户可以查看活动公告，系统会自动跟踪每个用户已阅读哪些公告。

来源：[src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java32-289](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java#L32-L289)

## 公告数据模型

系统中的公告结构化设计以提供全面的信息给用户，同时使管理员能够控制其可见性和生命周期。

来源：[src/main/java/com/ubanillx/smartclass/model/vo/AnnouncementVO.java1-70](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/vo/AnnouncementVO.java#L1-L70)

### 关键属性

| 属性           | 描述              | 使用       |
| ------------ | --------------- | -------- |
| `title`      | 公告标题            | 在列表中显著显示 |
| `content`    | 详细公告文本          | 支持富格式    |
| `priority`   | 数字优先级（越高越重要）    | 控制排序顺序   |
| `status`     | 0-草稿，1-已发布，2-下线 | 控制可见性    |
| `startTime`  | 公告可见时间          | 用于定时公告   |
| `endTime`    | 公告过期时间          | 用于临时公告   |
| `coverImage` | 公告图形的URL        | 视觉展示     |
| `viewCount`  | 查看次数            | 用于分析     |

来源：[src/main/java/com/ubanillx/smartclass/model/vo/AnnouncementVO.java14-58](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/vo/AnnouncementVO.java#L14-L58)

## 用户交互流程

以下图表展示了用户如何与系统中的公告进行交互：

"数据库""公告服务""公告控制器""客户端应用"用户"数据库""公告服务""公告控制器""客户端应用"用户alt[未读过]alt[用户已登录][用户未登录]打开应用程序GET /announcement/list/validlistValidAnnouncements()查询有效公告返回公告返回包含hasRead标志的AnnouncementVO列表显示公告显示公告查看公告详情GET /announcement/get/vo?id=XgetAnnouncementVO()查询公告返回公告检查用户是否已阅读此公告hasRead状态增加viewCount标记为此用户已读增加viewCount仅返回增强型AnnouncementVO显示带有阅读状态的详情显示公告详情

来源：[src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java120-151](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java#L120-L151) [src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java220-242](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java#L220-L242)

## 管理员管理流程

管理员对公告生命周期有完全控制权，如下图所示：

"数据库""公告服务""公告控制器""管理界面"管理员"数据库""公告服务""公告控制器""管理界面"管理员创建新公告POST /announcement/addaddAnnouncement()插入新公告确认创建返回新ID确认创建显示成功消息更新公告POST /announcement/updateupdateById()更新公告确认更新返回结果确认更新显示成功消息删除公告POST /announcement/deleteremoveById()删除公告确认删除返回结果确认删除显示成功消息查看所有公告POST /announcement/list/pagepage()分页查询公告返回公告返回Page<Announcement>显示公告列表显示公告表格

来源：[src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java52-65](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java#L52-L65) [src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java74-87](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java#L74-L87) [src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java96-111](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java#L96-L111) [src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java159-172](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java#L159-L172)

## API 端点

下表详细列出了公告系统的可用API端点：

| 端点 | 方法 | 描述 | 认证 |
| --- | --- | --- | --- |
| `/announcement/add` | POST | 创建新公告 | 仅管理员 |
| `/announcement/delete` | POST | 删除公告 | 仅管理员 |
| `/announcement/update` | POST | 更新公告 | 仅管理员 |
| `/announcement/get/vo` | GET | 按ID获取公告 | 公共 |
| `/announcement/list/page` | POST | 获取所有公告的分页列表 | 仅管理员 |
| `/announcement/list/page/vo` | POST | 获取带用户阅读状态的公告分页列表 | 用户 |
| `/announcement/list/valid` | GET | 获取当前有效的公告 | 公共 |
| `/announcement/read/{id}` | POST | 标记公告为已读 | 用户 |
| `/announcement/has-read/{id}` | GET | 检查用户是否已阅读公告 | 用户 |

来源：[src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java52-288](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java#L52-L288)

## 公告生命周期管理

系统中的公告遵循特定的生命周期，如下图所示：

来源：[src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java52-152](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java#L52-L152) [src/main/java/com/ubanillx/smartclass/model/vo/AnnouncementVO.java35-47](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/vo/AnnouncementVO.java#L35-L47)

# 实现细节

## 控制器实现

`AnnouncementController` 负责处理所有与公告相关的 HTTP 请求。它包括创建、更新、删除和检索公告的方法，以及管理阅读状态的功能。

关键操作包括：

- 创建公告（仅限管理员）
- 更新公告（仅限管理员）
- 删除公告（仅限管理员）
- 检索公告详情
- 分页列出公告
- 列出有效（已发布且在有效期内）的公告
- 标记公告为已读
- 检查阅读状态

控制器使用 `@AuthCheck` 注解来确保管理员专属的操作得到适当保护。

来源：[src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java32-289](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java#L32-L289)

## 查看计数与阅读状态跟踪

系统自动跟踪查看次数和个人用户的阅读状态：

1. 当用户查看公告时：
    
    - 如果他们已登录且之前未读过：
        - 增加查看次数
        - 将该公告标记为该用户的已读
    - 如果他们已登录但已经读过：
        - 不进行更改
    - 如果他们未登录：
        - 仅增加查看次数
        
2. 阅读状态包含在已登录用户的公告列表中，允许 UI 突出显示未读公告。

来源：[src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java120-151](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java#L120-L151) [src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java252-288](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java#L252-L288)

## 与其他系统的集成

公告系统设计为相对独立，但它与用户系统集成以进行身份验证和阅读状态跟踪。公告可用于通知用户 SmartClass 平台其他区域的更改或新功能。

来源：[src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java40-41](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java#L40-L41) [src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java133-148](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java#L133-L148)

## 系统使用的最佳实践

### 对于管理员

1. **优先级**：使用优先级字段确保最重要的公告首先显示。
2. **调度**：利用开始和结束时间提前安排公告并自动使其过期。
3. **状态管理**：使用状态字段管理公告的生命周期：
    - 草稿 (0)：用于准备中的公告
    - 已发布 (1)：用于活动且可见的公告
    - 下线 (2)：用于不再相关的公告

### 对于开发者

1. **阅读状态**：始终检查并更新已登录用户的阅读状态，以提供更好的用户体验。
2. **查看计数**：使用查看计数进行分析，了解哪些公告受到最多关注。
3. **查询优化**：在为用户列出公告时，使用 `listValidAnnouncements` 端点仅检索相关公告。

来源：[src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java220-242](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AnnouncementController.java#L220-L242) [src/main/java/com/ubanillx/smartclass/model/vo/AnnouncementVO.java14-67](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/vo/AnnouncementVO.java#L14-L67)