docs: 新增公告系统实现计划

- 新增十四、公告系统章节
- 数据库设计(announcements, user_announcement_reads)
- 用户接口(列表、详情、未读数量)
- 管理员接口(发布、编辑、删除)
- Rust 结构体示例
- 实施优先级
This commit is contained in:
2026-04-17 23:12:21 +08:00
parent 2aeef3e9bf
commit 15237d4250

View File

@@ -1274,6 +1274,150 @@ async onRedeemCode() {
---
## 十四、公告系统
### 功能概述
公告系统用于向用户发送系统公告,支持管理员发布、编辑、删除公告,用户查看公告列表和详情。
### 数据库设计
#### announcements 表
```sql
CREATE TABLE announcements (
id SERIAL PRIMARY KEY,
title VARCHAR(255) NOT NULL, -- 公告标题
content TEXT NOT NULL, -- 公告内容
priority VARCHAR(20) DEFAULT 'normal', -- high/normal/low
status VARCHAR(20) DEFAULT 'published',-- draft/published/archived
published_at TIMESTAMPTZ, -- 发布时间
created_by INTEGER REFERENCES users(id),
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX idx_announcements_published ON announcements(published_at DESC);
```
#### user_announcement_reads 表
```sql
CREATE TABLE user_announcement_reads (
id SERIAL PRIMARY KEY,
user_id INTEGER REFERENCES users(id),
announcement_id INTEGER REFERENCES announcements(id),
read_at TIMESTAMPTZ DEFAULT NOW(),
UNIQUE(user_id, announcement_id)
);
CREATE INDEX idx_reads_user ON user_announcement_reads(user_id);
```
### 后端接口
#### 用户接口
```json
// GET /api/announcements
// 公告列表(分页)
Response: {
"success": true,
"data": {
"list": [
{
"id": 1,
"title": "系统维护通知",
"priority": "high",
"publishedAt": "2026-04-17T10:00:00Z",
"isRead": false
}
],
"total": 10,
"page": 1,
"pageSize": 20
}
}
// GET /api/announcements/{id}
// 公告详情
Response: {
"success": true,
"data": {
"id": 1,
"title": "系统维护通知",
"content": "将于今晚10点进行系统维护...",
"priority": "high",
"publishedAt": "2026-04-17T10:00:00Z",
"isRead": true
}
}
// GET /api/announcements/unread-count
// 未读数量
Response: {
"success": true,
"data": { "count": 3 }
}
```
#### 管理员接口
```json
// POST /api/admin/announcements
// 发布公告
Request: {
"title": "系统维护通知",
"content": "将于今晚10点进行系统维护...",
"priority": "high"
}
// PUT /api/admin/announcements/{id}
// 更新公告
Request: {
"title": "系统维护通知(已更新)",
"content": "新内容...",
"priority": "normal"
}
// DELETE /api/admin/announcements/{id}
// 删除公告
```
### Rust 结构体示例
```rust
#[derive(Serialize, Deserialize)]
pub struct Announcement {
#[serde(rename = "id")]
pub id: i32,
#[serde(rename = "title")]
pub title: String,
#[serde(rename = "content")]
pub content: String,
#[serde(rename = "priority")]
pub priority: String,
#[serde(rename = "status")]
pub status: String,
#[serde(rename = "publishedAt")]
pub published_at: Option<DateTime<Utc>>,
#[serde(rename = "isRead")]
pub is_read: bool,
}
```
### 实施优先级
| 阶段 | 内容 | 复杂度 |
|------|------|--------|
| P1 | announcements 表 | 低 |
| P1 | 用户公告列表/详情接口 | 低 |
| P1 | 标记已读接口 | 低 |
| P2 | 管理员 CRUD 接口 | 中 |
| P2 | 未读数量接口 | 低 |
---
## 十一、检查清单
### 代码提交前检查