IM 即时通讯系统 - 功能与 API 接口简版文档
📊 项目概述
IM 即时通讯系统是一个功能完整的即时通讯平台，支持用户之间的实时消息传递、群组聊天、好友管理等功能。本文档基于实际实现的功能，提供了简洁明了的功能说明和 API 接口规范。
🎯 系统功能概览
已完成功能
1. 基础架构
- ✅ WebSocket 连接管理 (预连接、强制下线)
- ✅ 模块化架构 (DDD 分层)
- ✅ FreeSql ORM 集成
- ✅ FreeIM WebSocket 框架集成
2. 消息系统
- ✅ 消息发送 (私聊、群聊、多种消息类型支持)
- ✅ 消息接收 (WebSocket 推送)
- ✅ 历史消息查询 (分页支持，可包含群聊已读回执信息)
- ✅ 消息撤回 (2 分钟内可撤回)
- ✅ 消息已读/未读管理 (私聊已读回执、群聊已读记录)
- ✅ 消息搜索 (多维度筛选和关键字高亮)
- ✅ 离线消息处理 (@提醒、消息拦截)
3. 群组管理
- ✅ 群组 CRUD 操作
- ✅ 群成员管理 (申请入群、审核、邀请、踢出)
- ✅ 群权限管理 (群主、管理员、成员角色)
- ✅ 群设置 (群昵称、消息免打扰等)
- ✅ 群禁言功能 (个人禁言、全员禁言)
- ✅ 群公告管理
4. 好友系统
- ✅ 好友关系管理 (添加、删除、备注、分组)
- ✅ 好友申请流程 (发送、接受、拒绝)
- ✅ 好友状态检查
5. 用户管理
- ✅ 用户搜索 (按用户名/昵称)
- ✅ 用户数据同步 (Identity → IM 事件驱动同步)
6. 在线状态管理
- ✅ 用户在线状态 (在线、离线、忙碌、离开、隐身)
- ✅ 心跳机制 (更新活跃时间)
- ✅ 状态变更推送
7. 会话管理
- ✅ 会话 CRUD 操作
- ✅ 会话置顶/取消置顶
8. 黑名单管理
- ✅ 添加/移除黑名单
- ✅ 双向检查机制
- ✅ 消息拦截
📡 API 接口规范
1. 聊天消息接口
路由前缀: /api/im/chat-messages
| 方法 | 路径 | 说明 | 状态 |
|---|---|---|---|
| POST | / | 发送消息 | ✅ |
| GET | /history | 获取历史消息(支持包含群聊已读回执信息) | ✅ |
| POST | /{id}/recall | 撤回消息 | ✅ |
| POST | /mark-read | 标记已读 | ✅ |
| GET | /unread-count | 获取未读数统计 | ✅ |
| GET | /{id}/read-receipts | 获取已读列表(群聊) | ✅ |
| POST | /search | 搜索消息 | ✅ |
| GET | /offline-messages | 获取离线消息列表 | ✅ |
| POST | /offline-messages/pull | 手动拉取离线消息 | ✅ |
| POST | /offline-messages/ack | 确认消息已接收 | ✅ |
| DELETE | /offline-messages/delivered | 清理已推送的离线消息 | ✅ |
| GET | /offline-messages/stats | 获取离线消息统计 | ✅ |
2. 好友管理接口
路由前缀: /api/im/friends
| 方法 | 路径 | 说明 | 状态 |
|---|---|---|---|
| POST | /request | 发送好友申请 | ✅ |
| POST | /accept/{id} | 接受好友申请 | ✅ |
| POST | /reject | 拒绝好友申请 | ✅ |
| DELETE | /{userId} | 删除好友 | ✅ |
| GET | / | 获取好友列表 | ✅ |
| GET | /requests | 获取好友申请列表 | ✅ |
| PUT | / | 更新好友信息(备注/分组) | ✅ |
| GET | /check/{userId} | 检查好友状态 | ✅ |
| GET | /check-status/{userId} | 检查好友状态 | ✅ |
| POST | /block/{userId} | 拉黑好友 | ✅ |
| POST | /unblock/{userId} | 取消拉黑 | ✅ |
| GET | /group/{groupName} | 按分组查询好友 | ✅ |
| GET | /groups | 获取所有分组名称 | ✅ |
3. 群组管理接口
路由前缀: /api/im/chat-groups
| 方法 | 路径 | 说明 | 状态 |
|---|---|---|---|
| GET | / | 获取群组列表 | ✅ |
| GET | /{id} | 获取群组详情 | ✅ |
| POST | / | 创建群组 | ✅ |
| PUT | /{id} | 更新群组 | ✅ |
| DELETE | /{id} | 删除群组(群主) | ✅ |
| POST | /join | 申请加入群组 | ✅ |
| POST | /audit | 审核入群申请 | ✅ |
| GET | /{id}/requests | 获取入群申请列表 | ✅ |
| GET | /{id}/members | 获取群成员列表 | ✅ |
| POST | /invite | 邀请入群 | ✅ |
| POST | /kick | 踢出成员 | ✅ |
| POST | /{id}/leave | 退出群组 | ✅ |
| POST | /set-admin | 设置/取消管理员 | ✅ |
| POST | /transfer-owner | 转让群主 | ✅ |
| PUT | /settings | 更新群设置 | ✅ |
| PUT | /nickname | 修改群昵称 | ✅ |
| POST | /mute | 消息免打扰 | ✅ |
| POST | /enter | 进入群聊频道(WebSocket) | ✅ |
| POST | /exit | 离开群聊频道(WebSocket) | ✅ |
| POST | /mute-member | 禁言成员 | ✅ |
| POST | /unmute-member | 解除禁言 | ✅ |
| POST | /all-mute | 全员禁言 | ✅ |
| POST | /search-members | 搜索群成员 | ✅ |
4. 在线状态接口
路由前缀: /api/im/user-presence
| 方法 | 路径 | 说明 | 状态 |
|---|---|---|---|
| GET | /{userId} | 获取用户在线状态 | ✅ |
| POST | / | 设置当前用户在线状态 | ✅ |
| POST | /batch | 批量获取用户在线状态 | ✅ |
| GET | /friends | 获取好友在线状态列表 | ✅ |
| POST | /heartbeat | 心跳更新(活跃时间) | ✅ |
5. 用户管理接口
路由前缀: /api/im/users
| 方法 | 路径 | 说明 | 状态 |
|---|---|---|---|
| GET | /{id} | 获取用户详情 | ✅ |
| GET | /search | 搜索用户 | ✅ |
6. 会话管理接口
路由前缀: /api/im/recent-contacts
| 方法 | 路径 | 说明 | 状态 |
|---|---|---|---|
| GET | / | 获取会话列表 | ✅ |
| GET | /{id} | 获取会话详情 | ✅ |
| POST | / | 创建会话 | ✅ |
| PUT | /{id} | 更新会话 | ✅ |
| DELETE | /{id} | 删除会话 | ✅ |
| POST | /set-top | 置顶/取消置顶会话 | ✅ |
7. 群公告接口
路由前缀: /api/im/chat-groups/{groupId}/announcements
| 方法 | 路径 | 说明 | 状态 |
|---|---|---|---|
| GET | / | 获取群公告列表 | ✅ |
| GET | /{id} | 获取公告详情 | ✅ |
| POST | / | 发布群公告 | ✅ |
| PUT | /{id} | 更新公告 | ✅ |
| DELETE | /{id} | 删除公告 | ✅ |
| PUT | /{id}/pin | 置顶/取消置顶公告 | ✅ |
8. 黑名单接口
路由前缀: /api/im/blacklist
| 方法 | 路径 | 说明 | 状态 |
|---|---|---|---|
| POST | / | 添加黑名单 | ✅ |
| DELETE | /{blockedUserId} | 移除黑名单 | ✅ |
| GET | / | 查询黑名单列表 | ✅ |
| GET | /check/{targetUserId} | 检查是否在黑名单中 | ✅ |
9. WebSocket 接口
路由前缀: /api/im/ws
| 方法 | 路径 | 说明 | 状态 |
|---|---|---|---|
| POST | /pre-connect | 获取websocket分区 | ✅ |
| GET | /offline | 强制下线 | ✅ |
🔐 安全机制
已实现的安全检查
- ✅ JWT 身份认证
- ✅ 好友关系验证(私聊)
- ✅ 黑名单双向检查
- ✅ 群成员验证
- ✅ 群禁言检查(个人/全员)
- ✅ 群角色权限(群主/管理员/成员)
- ✅ 消息撤回权限验证
📈 系统完成度统计
总计:
- ✅ 已实现: 80+个核心接口
- 📈 核心功能完成度: 约90%
最后更新: 2025年11月26日