diff --git a/IMPROVEMENTS.md b/IMPROVEMENTS.md index c6b63a8..4af9d62 100644 --- a/IMPROVEMENTS.md +++ b/IMPROVEMENTS.md @@ -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>, + #[serde(rename = "isRead")] + pub is_read: bool, +} +``` + +### 实施优先级 + +| 阶段 | 内容 | 复杂度 | +|------|------|--------| +| P1 | announcements 表 | 低 | +| P1 | 用户公告列表/详情接口 | 低 | +| P1 | 标记已读接口 | 低 | +| P2 | 管理员 CRUD 接口 | 中 | +| P2 | 未读数量接口 | 低 | + +--- + ## 十一、检查清单 ### 代码提交前检查