# IM 即时通讯模块解锁指南

## 一、模块概述

IM（Instant Messaging）即时通讯模块提供企业内部的即时通讯能力，支持私聊、群聊、好友管理等核心功能。

### 1.1 功能清单

| 功能 | 说明 |
|------|------|
| 好友管理 | 添加好友、删除好友、好友申请审核 |
| 私聊消息 | 一对一聊天、消息撤回、已读回执 |
| 群聊管理 | 创建群、解散群、群成员管理、群公告 |
| 群聊消息 | 群内聊天、消息撤回、回执确认 |
| 会话管理 | 会话列表、未读计数、历史消息 |
| 在线状态 | 用户在线/离线状态显示 |

### 1.2 数据库表清单

| 表名 | 说明 |
|------|------|
| im_friend | 好友关系表 |
| im_friend_request | 好友申请表 |
| im_group | 群组表 |
| im_group_member | 群成员表 |
| im_private_message | 私聊消息表 |
| im_group_message | 群聊消息表 |
| im_group_message_receipt | 群消息回执表 |
| im_conversation | 会话表 |
| im_user_online | 用户在线状态表 |
| im_group_request | 群申请表 |
| im_message_file | 消息文件表 |

---

## 二、解锁步骤

### 2.1 创建模块目录结构

```bash
mkdir -p yudao-module-im/yudao-module-im-api/src/main/java/cn/iocoder/yudao/module/im/api
mkdir -p yudao-module-im/yudao-module-im-biz/src/main/java/cn/iocoder/yudao/module/im/{controller,service,dal}
mkdir -p yudao-module-im/yudao-module-im-biz/src/main/java/cn/iocoder/yudao/module/im/controller/admin/{friend,group,message}
mkdir -p yudao-module-im/yudao-module-im-biz/src/main/java/cn/iocoder/yudao/module/im/service/{friend,group,message}
mkdir -p yudao-module-im/yudao-module-im-biz/src/main/java/cn/iocoder/yudao/module/im/dal/{dataobject,mysql}
mkdir -p yudao-module-im/yudao-module-im-biz/src/main/java/cn/iocoder/yudao/module/im/dal/dataobject/{friend,group,message}
mkdir -p yudao-module-im/yudao-module-im-biz/src/main/java/cn/iocoder/yudao/module/im/dal/mysql/{friend,group,message}
```

### 2.2 创建 pom.xml

**yudao-module-im-api/pom.xml:**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <groupId>cn.iocoder.boot</groupId>
        <artifactId>yudao-module-im</artifactId>
        <version>${revision}</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>
    <artifactId>yudao-module-im-api</artifactId>
    <packaging>jar</packaging>

    <name>${project.artifactId}</name>
    <description>IM 即时通讯模块 API</description>

    <dependencies>
        <dependency>
            <groupId>cn.iocoder.boot</groupId>
            <artifactId>yudao-framework-common</artifactId>
        </dependency>
    </dependencies>
</project>
```

**yudao-module-im-biz/pom.xml:**

```xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <parent>
        <groupId>cn.iocoder.boot</groupId>
        <artifactId>yudao-module-im</artifactId>
        <version>${revision}</version>
    </parent>
    <modelVersion>4.0.0</modelVersion>
    <artifactId>yudao-module-im-biz</artifactId>
    <packaging>jar</packaging>

    <name>${project.artifactId}</name>
    <description>IM 即时通讯模块业务实现</description>

    <dependencies>
        <dependency>
            <groupId>cn.iocoder.boot</groupId>
            <artifactId>yudao-module-im-api</artifactId>
            <version>${revision}</version>
        </dependency>

        <dependency>
            <groupId>cn.iocoder.boot</groupId>
            <artifactId>yudao-module-system-api</artifactId>
            <version>${revision}</version>
        </dependency>

        <!-- Web 相关 -->
        <dependency>
            <groupId>cn.iocoder.boot</groupId>
            <artifactId>yudao-spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>cn.iocoder.boot</groupId>
            <artifactId>yudao-spring-boot-starter-security</artifactId>
        </dependency>

        <!-- DB 相关 -->
        <dependency>
            <groupId>cn.iocoder.boot</groupId>
            <artifactId>yudao-spring-boot-starter-mybatis</artifactId>
        </dependency>

        <dependency>
            <groupId>cn.iocoder.boot</groupId>
            <artifactId>yudao-spring-boot-starter-redis</artifactId>
        </dependency>

        <!-- WebSocket -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-websocket</artifactId>
        </dependency>

        <!-- Test 测试相关 -->
        <dependency>
            <groupId>cn.iocoder.boot</groupId>
            <artifactId>yudao-spring-boot-starter-test</artifactId>
        </dependency>
    </dependencies>
</project>
```

### 2.3 执行数据库 SQL

```bash
# 执行 IM 模块表结构 SQL
mysql -u root -p mom_pro < docs/im_module.sql
```

### 2.4 在 yudao-server/pom.xml 中添加依赖

```xml
<!-- IM 即时通讯模块 -->
<dependency>
    <groupId>cn.iocoder.boot</groupId>
    <artifactId>yudao-module-im-biz</artifactId>
    <version>${revision}</version>
</dependency>
```

---

## 三、核心实体类示例

### 3.1 ImFriendDO.java

```java
package cn.iocoder.yudao.module.im.dal.dataobject.friend;

import cn.iocoder.yudao.framework.mybatis.core.dataobject.BaseDO;
import com.baomidou.mybatisplus.annotation.KeySequence;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.*;

/**
 * 好友关系 DO
 */
@TableName("im_friend")
@KeySequence("im_friend_seq")
@Data
@EqualsAndHashCode(callSuper = true)
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class ImFriendDO extends BaseDO {

    @TableId
    private Long id;

    /** 用户编号 */
    private Long userId;

    /** 好友用户编号 */
    private Long friendUserId;

    /** 好友备注 */
    private String remark;

    /** 好友状态（0正常 1已删除） */
    private Integer status;

}
```

### 3.2 ImGroupDO.java

```java
package cn.iocoder.yudao.module.im.dal.dataobject.group;

import cn.iocoder.yudao.framework.mybatis.core.dataobject.BaseDO;
import com.baomidou.mybatisplus.annotation.KeySequence;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.*;

/**
 * 群组 DO
 */
@TableName("im_group")
@KeySequence("im_group_seq")
@Data
@EqualsAndHashCode(callSuper = true)
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class ImGroupDO extends BaseDO {

    @TableId
    private Long id;

    /** 群名称 */
    private String name;

    /** 群头像 */
    private String avatar;

    /** 群主用户编号 */
    private Long ownerUserId;

    /** 群公告 */
    private String notice;

    /** 群状态（0正常 1已解散） */
    private Integer status;

}
```

### 3.3 ImPrivateMessageDO.java

```java
package cn.iocoder.yudao.module.im.dal.dataobject.message;

import cn.iocoder.yudao.framework.mybatis.core.dataobject.BaseDO;
import com.baomidou.mybatisplus.annotation.KeySequence;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.*;

import java.time.LocalDateTime;

/**
 * 私聊消息 DO
 */
@TableName("im_private_message")
@KeySequence("im_private_message_seq")
@Data
@EqualsAndHashCode(callSuper = true)
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class ImPrivateMessageDO extends BaseDO {

    @TableId
    private Long id;

    /** 发送人编号 */
    private Long fromUserId;

    /** 接收人编号 */
    private Long toUserId;

    /** 消息内容 */
    private String content;

    /** 消息类型 */
    private Integer messageType;

    /** 消息状态（0未读 2已撤回 3已读） */
    private Integer status;

    /** 发送时间 */
    private LocalDateTime sendTime;

    /** 已读时间 */
    private LocalDateTime readTime;

}
```

---

## 四、业务流程说明

### 4.1 好友添加流程

```
┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  发送好友   │ -> │  对方收到   │ -> │  同意/拒绝  │ -> │  建立好友   │
│  申请       │    │  申请通知   │    │  申请       │    │  关系       │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
       │                  │                  │
       v                  v                  v
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│ im_friend_  │    │ WebSocket   │    │ im_friend   │
│ request     │    │ 推送通知    │    │ 表新增      │
│ 表新增      │    │             │    │             │
└─────────────┘    └─────────────┘    └─────────────┘
```

### 4.2 私聊消息流程

```
┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  发送消息   │ -> │  WebSocket  │ -> │  接收消息   │ -> │  已读回执   │
│             │    │  推送       │    │             │    │             │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
       │                  │                  │                  │
       v                  v                  v                  v
┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│ im_private_ │    │ 实时推送    │    │ 消息入库    │    │ 更新已读    │
│ message     │    │ 给接收人    │    │ 状态未读    │    │ 状态        │
│ 入库        │    │             │    │             │    │             │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
```

### 4.3 群聊管理流程

```
┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  创建群聊   │ -> │  添加成员   │ -> │  群内聊天   │ -> │  解散群聊   │
│             │    │             │    │             │    │             │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
       │                  │                  │                  │
       v                  v                  v                  v
┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│ im_group    │    │ im_group_   │    │ im_group_   │    │ 更新群状态  │
│ 表新增      │    │ member      │    │ message     │    │ 为已解散    │
│             │    │ 表新增      │    │ 入库        │    │             │
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
```

---

## 五、菜单配置

需要在 system_menu 表中添加 IM 模块的菜单：

```sql
-- IM 模块一级菜单
INSERT INTO `system_menu` (`id`, `name`, `permission`, `type`, `sort`, `parent_id`, `path`, `icon`, `component`, `status`, `visible`, `creator`, `create_time`, `updater`, `update_time`, `deleted`)
VALUES (2100, '即时通讯', '', 1, 30, 0, '/im', 'message', NULL, 0, b'1', 'admin', NOW(), 'admin', NOW(), b'0');

-- 好友管理
INSERT INTO `system_menu` (`id`, `name`, `permission`, `type`, `sort`, `parent_id`, `path`, `icon`, `component`, `status`, `visible`, `creator`, `create_time`, `updater`, `update_time`, `deleted`)
VALUES (2101, '好友管理', '', 2, 1, 2100, 'friend', '', 'im/friend/index', 0, b'1', 'admin', NOW(), 'admin', NOW(), b'0');

-- 群聊管理
INSERT INTO `system_menu` (`id`, `name`, `permission`, `type`, `sort`, `parent_id`, `path`, `icon`, `component`, `status`, `visible`, `creator`, `create_time`, `updater`, `update_time`, `deleted`)
VALUES (2102, '群聊管理', '', 2, 2, 2100, 'group', '', 'im/group/index', 0, b'1', 'admin', NOW(), 'admin', NOW(), b'0');

-- 消息管理
INSERT INTO `system_menu` (`id`, `name`, `permission`, `type`, `sort`, `parent_id`, `path`, `icon`, `component`, `status`, `visible`, `creator`, `create_time`, `updater`, `update_time`, `deleted`)
VALUES (2103, '消息管理', '', 2, 3, 2100, 'message', '', 'im/message/index', 0, b'1', 'admin', NOW(), 'admin', NOW(), b'0');
```

---

## 六、注意事项

1. **WebSocket 配置**: IM 模块依赖 WebSocket 实现实时通讯，需要配置 WebSocket 端点
2. **Redis 消息队列**: 建议使用 Redis Pub/Sub 实现消息广播
3. **离线消息存储**: 用户离线时的消息需要持久化，上线后推送
4. **消息安全**: 消息内容需要考虑敏感词过滤、 XSS 防护
5. **性能优化**: 高并发场景建议使用消息队列削峰填谷

---

**文档版本**: v1.0
**创建日期**: 2026-06-29
**适用项目**: mom-pro2-after
**表数量**: 11 张