feat: 首次推送到Gitea - 完整项目代码 + 安全加固 + 知识库

.trae/specs/modules/notifications.md

@@ -0,0 +1,131 @@
+# 通知系统模块
+
+## 概述
+通知系统提供实时消息推送、智能摘要合并和个性化偏好设置，确保用户不错过重要互动但也不被过度打扰。
+
+## 数据模型
+
+### Notification (通知)
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | Int @id | 主键 |
+| userId | Int | 用户ID |
+| type | NotifType | 通知类型 |
+| title | String | 标题 |
+| content | String? | 内容 |
+| link | String? | 跳转链接 |
+| isRead | Boolean @default(false) | 是否已读 |
+| createdAt | DateTime | 创建时间 |
+
+### NotifType 枚举
+| 值 | 说明 |
+|------|------|
+| COMMENT_REPLY | 评论回复通知 |
+| COMMENT_LIKE | 评论点赞通知 |
+| TOPIC_REPLY | 话题回复通知 |
+| SYSTEM | 系统通知 |
+| DIGEST 🆕 | 智能摘要合并通知 |
+
+---
+
+## 智能通知摘要 (Smart Notification Digest) 🆕
+
+### 功能说明
+当用户在短时间内收到多条同类通知时，系统自动合并为一条摘要通知，减少通知轰炸。
+
+### 合并规则
+- 同类通知（同 type + 同来源）在 30 分钟内合并
+- 摘要格式: "你的帖子收到了 5 条新回复"
+- 原始通知保留但标记为已读，摘要通知链接到通知详情页
+
+### 定时任务
+- **脚本**: `scripts/notification-digest.mjs`
+- 每 3 小时合并一次未读通知
+- 仅对超过 3 条同类通知的用户生成摘要
+
+---
+
+## 通知偏好设置 🆕
+
+### 功能
+用户可在通知中心设置通知偏好，控制接收哪些类型的通知。
+
+### API
+| 路由 | 方法 | 功能 |
+|------|------|------|
+| /api/user/notification-prefs | GET | 获取通知偏好 |
+| /api/user/notification-prefs | PUT | 更新通知偏好 |
+
+### 可配置项
+| 偏好键 | 说明 | 默认值 |
+|------|------|--------|
+| comment_reply | 评论回复通知 | true |
+| comment_like | 评论点赞通知 | true |
+| topic_reply | 话题回复通知 | true |
+| system | 系统通知 | true |
+| digest | 智能摘要通知 | true |
+| email_digest | 邮件摘要（未实现） | false |
+
+---
+
+## 通知中心页面 🆕
+
+### 路由
+- `/user/notifications` — 通知中心独立页面
+
+### 功能
+- 分类标签页: 全部 / 回复 / 点赞 / 系统 / 摘要
+- 批量标记已读
+- 单条跳转到目标内容
+- 未读数量徽章
+- 通知偏好设置入口
+
+### 组件
+- `NotificationCenter` (`src/components/forum/NotificationCenter.tsx`)
+
+---
+
+## API 接口
+
+### 通知核心 API
+| 路由 | 方法 | 功能 |
+|------|------|------|
+| /api/notifications | GET | 获取通知列表（含未读数） |
+| /api/notifications | PUT | 标记通知为已读（支持指定ids或全部已读） |
+| /api/notifications/unread-count | GET | 获取未读通知数量（轻量级） |
+
+### 通知偏好 API 🆕
+| 路由 | 方法 | 功能 |
+|------|------|------|
+| /api/user/notification-prefs | GET | 获取通知偏好设置 |
+| /api/user/notification-prefs | PUT | 更新通知偏好设置 |
+
+---
+
+## 自动触发规则
+
+以下操作自动生成通知：
+
+| 操作 | 通知对象 | 通知类型 |
+|------|----------|----------|
+| 回复评论 | 评论作者 | COMMENT_REPLY |
+| 点赞评论 | 评论作者 | COMMENT_LIKE |
+| 回复话题 | 话题作者 | TOPIC_REPLY |
+| 系统公告 | 所有用户 | SYSTEM |
+| 摘要合并 | 用户本人 | DIGEST |
+
+---
+
+## 前端组件
+
+| 组件 | 文件 | 说明 |
+|------|------|------|
+| NotificationBell | `src/components/forum/NotificationBell.tsx` | 导航栏通知铃铛（红点/下拉面板/自动已读） |
+| NotificationCenter | `src/components/forum/NotificationCenter.tsx` 🆕 | 通知中心页面（分类标签/批量操作/偏好入口） |
+
+### NotificationBell 交互
+- 未读时显示红色圆点徽章
+- 点击展开快捷通知面板（最近5条）
+- 下拉面板支持滚动加载更多
+- 点击通知跳转到目标页面并自动标记已读
+- "查看全部"链接跳转到通知中心