From 15237d42508b5ea5e65032e85fb96b9760aa3ce3 Mon Sep 17 00:00:00 2001
From: Milky0217 <m943790568@163.com>
Date: Fri, 17 Apr 2026 23:12:21 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E5=85=AC=E5=91=8A?=
 =?UTF-8?q?=E7=B3=BB=E7=BB=9F=E5=AE=9E=E7=8E=B0=E8=AE=A1=E5=88=92?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增十四、公告系统章节
- 数据库设计（announcements, user_announcement_reads）
- 用户接口（列表、详情、未读数量）
- 管理员接口（发布、编辑、删除）
- Rust 结构体示例
- 实施优先级
---
 IMPROVEMENTS.md | 144 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 144 insertions(+)

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