diff --git a/src/business/notice/README.md b/src/business/notice/README.md new file mode 100644 index 0000000..9cc2c91 --- /dev/null +++ b/src/business/notice/README.md @@ -0,0 +1,186 @@ +# 通知系统 (Notice System) + +## 功能概述 + +这是一个完整的通知系统,支持实时通知推送、定时通知、通知状态管理等功能。 + +## 主要特性 + +- ✅ 实时WebSocket通知推送 +- ✅ 定时通知发送 +- ✅ 通知状态管理(待发送、已发送、已读、失败) +- ✅ 支持单用户通知和广播通知 +- ✅ 通知类型分类(系统、用户、广播) +- ✅ 未读通知计数 +- ✅ RESTful API接口 + +## API接口 + +### 1. 创建通知 +``` +POST /api/notices +``` + +### 2. 获取通知列表 +``` +GET /api/notices +GET /api/notices?all=true # 管理员获取所有通知 +``` + +### 3. 获取未读通知数量 +``` +GET /api/notices/unread-count +``` + +### 4. 获取通知详情 +``` +GET /api/notices/:id +``` + +### 5. 标记通知为已读 +``` +PATCH /api/notices/:id/read +``` + +### 6. 发送系统通知 +``` +POST /api/notices/system +``` + +### 7. 发送广播通知 +``` +POST /api/notices/broadcast +``` + +## WebSocket连接 + +### 连接地址 +``` +ws://localhost:3000/ws/notice +``` + +### 认证 +连接后需要发送认证消息: +```json +{ + "event": "authenticate", + "data": { "userId": 123 } +} +``` + +### 接收通知 +客户端会收到以下格式的通知: +```json +{ + "type": "notice", + "data": { + "id": 1, + "title": "通知标题", + "content": "通知内容", + "type": "system", + "status": "sent", + "createdAt": "2024-01-01T00:00:00.000Z" + } +} +``` + +## 使用示例 + +### 前端JavaScript示例 +```javascript +// 建立WebSocket连接 +const ws = new WebSocket('ws://localhost:3000/ws/notice'); + +// 连接成功后认证 +ws.onopen = () => { + ws.send(JSON.stringify({ + event: 'authenticate', + data: { userId: 123 } + })); +}; + +// 接收通知 +ws.onmessage = (event) => { + const message = JSON.parse(event.data); + if (message.type === 'notice') { + console.log('收到新通知:', message.data); + // 在UI中显示通知 + showNotification(message.data); + } +}; + +// 获取通知列表 +async function getNotices() { + const response = await fetch('/api/notices', { + headers: { + 'Authorization': `Bearer ${token}` + } + }); + return response.json(); +} + +// 标记通知为已读 +async function markAsRead(noticeId) { + await fetch(`/api/notices/${noticeId}/read`, { + method: 'PATCH', + headers: { + 'Authorization': `Bearer ${token}` + } + }); +} +``` + +### 后端使用示例 +```typescript +// 注入NoticeService +constructor(private readonly noticeService: NoticeService) {} + +// 发送系统通知 +await this.noticeService.sendSystemNotice( + '系统维护通知', + '系统将于今晚22:00进行维护', + userId +); + +// 发送广播通知 +await this.noticeService.sendBroadcast( + '新功能上线', + '我们上线了新的通知功能!' +); + +// 创建定时通知 +await this.noticeService.create({ + title: '会议提醒', + content: '您有一个会议将在30分钟后开始', + userId: 123, + scheduledAt: new Date(Date.now() + 30 * 60 * 1000).toISOString() +}); +``` + +## 数据库表结构 + +通知表包含以下字段: +- `id`: 主键 +- `title`: 通知标题 +- `content`: 通知内容 +- `type`: 通知类型(system/user/broadcast) +- `status`: 通知状态(pending/sent/read/failed) +- `userId`: 接收者ID(null表示广播) +- `senderId`: 发送者ID +- `scheduledAt`: 计划发送时间 +- `sentAt`: 实际发送时间 +- `readAt`: 阅读时间 +- `metadata`: 额外数据(JSON格式) +- `createdAt`: 创建时间 +- `updatedAt`: 更新时间 + +## 定时任务 + +系统每分钟自动检查并发送到期的定时通知。 + +## 注意事项 + +1. 需要在主模块中导入 `NoticeModule` +2. 确保数据库中存在 `notices` 表 +3. WebSocket连接需要用户认证 +4. 定时通知依赖 `@nestjs/schedule` 包 \ No newline at end of file