zhibo/Zhibo/zhibo-h/群组聊天模块快速参考.md

# 群组聊天模块快速参考

> **模块**: 模块11 - 群组聊天模块  
> **状态**: ✅ 已完成  
> **更新时间**: 2024年12月26日

---

## 📋 核心功能

### 群组管理
- ✅ 创建群组
- ✅ 更新群组信息
- ✅ 解散群组（逻辑删除）
- ✅ 获取群组列表
- ✅ 获取群组详情
- ✅ 更新群公告
- ✅ 设置全员禁言

### 成员管理
- ✅ 邀请成员加入
- ✅ 移除成员（逻辑删除）
- ✅ 退出群组（逻辑删除）
- ✅ 获取成员列表
- ✅ 设置管理员
- ✅ 禁言/取消禁言成员
- ✅ 更新群昵称

### 消息管理
- ✅ 发送群组消息
- ✅ 获取消息列表
- ✅ 撤回消息（2分钟内）
- ✅ 删除消息（逻辑删除）
- ✅ @提醒功能

---

## 🔑 API接口

### 群组管理接口

```http
# 创建群组
POST /api/front/groups/create
Content-Type: application/json
Authorization: Bearer {token}

{
  "groupName": "我的群组",
  "avatar": "https://example.com/avatar.jpg",
  "description": "群组描述"
}

# 更新群组信息
PUT /api/front/groups/{groupId}
Content-Type: application/json
Authorization: Bearer {token}

{
  "groupName": "新群组名称",
  "avatar": "https://example.com/new-avatar.jpg",
  "description": "新描述",
  "announcement": "群公告"
}

# 解散群组（逻辑删除）
DELETE /api/front/groups/{groupId}
Authorization: Bearer {token}

# 获取用户的群组列表
GET /api/front/groups/list
Authorization: Bearer {token}

# 获取群组详情
GET /api/front/groups/{groupId}
Authorization: Bearer {token}

# 更新群公告
PUT /api/front/groups/{groupId}/announcement
Content-Type: application/json
Authorization: Bearer {token}

{
  "announcement": "新的群公告内容"
}

# 设置全员禁言
PUT /api/front/groups/{groupId}/mute-all
Content-Type: application/json
Authorization: Bearer {token}

{
  "muteAll": true
}
```

### 成员管理接口

```http
# 邀请成员加入群组
POST /api/front/groups/{groupId}/members/invite
Content-Type: application/json
Authorization: Bearer {token}

{
  "userIds": [1001, 1002, 1003]
}

# 移除群成员（逻辑删除）
DELETE /api/front/groups/{groupId}/members/{userId}
Authorization: Bearer {token}

# 退出群组（逻辑删除）
POST /api/front/groups/{groupId}/quit
Authorization: Bearer {token}

# 获取群成员列表
GET /api/front/groups/{groupId}/members
Authorization: Bearer {token}

# 设置管理员
PUT /api/front/groups/{groupId}/members/{userId}/admin
Content-Type: application/json
Authorization: Bearer {token}

{
  "isAdmin": true
}

# 禁言成员
PUT /api/front/groups/{groupId}/members/{userId}/mute
Content-Type: application/json
Authorization: Bearer {token}

{
  "muteEndTime": 1703606400000
}

# 取消禁言
PUT /api/front/groups/{groupId}/members/{userId}/unmute
Authorization: Bearer {token}

# 更新群昵称
PUT /api/front/groups/{groupId}/members/nickname
Content-Type: application/json
Authorization: Bearer {token}

{
  "nickname": "我的群昵称"
}
```

### 消息管理接口

```http
# 发送群组消息
POST /api/front/groups/{groupId}/messages
Content-Type: application/json
Authorization: Bearer {token}

{
  "messageType": "text",
  "content": "消息内容",
  "mediaUrl": "",
  "atUserIds": [1001, 1002],
  "atAll": false
}

# 获取群组消息列表
GET /api/front/groups/{groupId}/messages?page=1&pageSize=20
Authorization: Bearer {token}

# 撤回群组消息
POST /api/front/groups/messages/{messageId}/recall
Authorization: Bearer {token}

# 删除群组消息（逻辑删除）
DELETE /api/front/groups/messages/{messageId}
Authorization: Bearer {token}
```

---

## 🗄️ 数据库表结构

### eb_group（群组表）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT | 群组ID（主键） |
| group_name | VARCHAR(50) | 群组名称 |
| avatar | VARCHAR(255) | 群组头像 |
| owner_id | INT | 群主ID |
| announcement | VARCHAR(500) | 群公告 |
| description | VARCHAR(200) | 群组描述 |
| max_members | INT | 最大成员数（默认200） |
| member_count | INT | 当前成员数 |
| allow_member_invite | TINYINT(1) | 是否允许成员邀请 |
| mute_all | TINYINT(1) | 是否全员禁言 |
| is_deleted | TINYINT(1) | 是否删除（逻辑删除） |
| create_time | DATETIME | 创建时间 |
| update_time | DATETIME | 更新时间 |
| ext_field1 | VARCHAR(50) | 扩展字段1：群组分类 |
| ext_field2 | VARCHAR(200) | 扩展字段2：群组标签 |
| ext_field3 | INT | 扩展字段3：群组等级 |
| ext_field4 | BIGINT | 扩展字段4：关联数据ID |
| ext_field5 | TEXT | 扩展字段5：JSON扩展数据 |

### eb_group_member（群成员表）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT | 成员ID（主键） |
| group_id | BIGINT | 群组ID |
| user_id | INT | 用户ID |
| nickname | VARCHAR(50) | 群昵称 |
| role | TINYINT | 成员角色（0-普通 1-管理员 2-群主） |
| is_muted | TINYINT(1) | 是否禁言 |
| mute_end_time | DATETIME | 禁言到期时间 |
| unread_count | INT | 未读消息数 |
| is_silent | TINYINT(1) | 是否静音 |
| is_deleted | TINYINT(1) | 是否删除（逻辑删除） |
| join_time | DATETIME | 加入时间 |
| update_time | DATETIME | 更新时间 |
| ext_field1 | VARCHAR(100) | 扩展字段1：成员标签 |
| ext_field2 | INT | 扩展字段2：成员等级 |
| ext_field3 | VARCHAR(200) | 扩展字段3：自定义备注 |
| ext_field4 | BIGINT | 扩展字段4：关联数据ID |
| ext_field5 | TEXT | 扩展字段5：JSON扩展数据 |

### eb_group_message（群消息表）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT | 消息ID（主键） |
| group_id | BIGINT | 群组ID |
| sender_id | INT | 发送者ID |
| message_type | VARCHAR(20) | 消息类型 |
| content | VARCHAR(2000) | 消息内容 |
| media_url | VARCHAR(500) | 媒体URL |
| at_user_ids | VARCHAR(500) | @的用户ID列表 |
| at_all | TINYINT(1) | 是否@全体成员 |
| is_recalled | TINYINT(1) | 是否已撤回 |
| recall_time | DATETIME | 撤回时间 |
| is_deleted | TINYINT(1) | 是否删除（逻辑删除） |
| create_time | DATETIME | 创建时间 |
| update_time | DATETIME | 更新时间 |
| ext_field1 | VARCHAR(50) | 扩展字段1：消息来源 |
| ext_field2 | BIGINT | 扩展字段2：引用消息ID |
| ext_field3 | VARCHAR(100) | 扩展字段3：消息标签 |
| ext_field4 | BIGINT | 扩展字段4：附件大小 |
| ext_field5 | TEXT | 扩展字段5：JSON扩展数据 |

---

## 🔐 权限说明

### 成员角色
- **群主（role=2）**：拥有所有权限
- **管理员（role=1）**：可以管理成员、禁言、修改群公告
- **普通成员（role=0）**：可以发送消息、邀请成员

### 权限矩阵

| 操作 | 群主 | 管理员 | 普通成员 |
|------|------|--------|---------|
| 创建群组 | ✅ | ✅ | ✅ |
| 更新群组信息 | ✅ | ✅ | ❌ |
| 解散群组 | ✅ | ❌ | ❌ |
| 更新群公告 | ✅ | ✅ | ❌ |
| 设置全员禁言 | ✅ | ✅ | ❌ |
| 邀请成员 | ✅ | ✅ | ✅ |
| 移除成员 | ✅ | ✅ | ❌ |
| 退出群组 | ❌ | ✅ | ✅ |
| 设置管理员 | ✅ | ❌ | ❌ |
| 禁言成员 | ✅ | ✅ | ❌ |
| 发送消息 | ✅ | ✅ | ✅ |
| 撤回消息 | ✅ | ✅ | ✅（仅自己） |

---

## 💡 使用示例

### 创建群组并邀请成员

```javascript
// 1. 创建群组
const createGroupResponse = await fetch('/api/front/groups/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + token
  },
  body: JSON.stringify({
    groupName: '技术交流群',
    avatar: 'https://example.com/group-avatar.jpg',
    description: '讨论技术问题的群组'
  })
});

const group = await createGroupResponse.json();
const groupId = group.data.id;

// 2. 邀请成员
await fetch(`/api/front/groups/${groupId}/members/invite`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + token
  },
  body: JSON.stringify({
    userIds: [1001, 1002, 1003]
  })
});
```

### 发送群组消息

```javascript
// 发送文本消息
await fetch(`/api/front/groups/${groupId}/messages`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + token
  },
  body: JSON.stringify({
    messageType: 'text',
    content: '大家好！',
    atUserIds: [],
    atAll: false
  })
});

// 发送@消息
await fetch(`/api/front/groups/${groupId}/messages`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + token
  },
  body: JSON.stringify({
    messageType: 'text',
    content: '@张三 @李四 请查看这个问题',
    atUserIds: [1001, 1002],
    atAll: false
  })
});

// 发送@全体成员消息
await fetch(`/api/front/groups/${groupId}/messages`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + token
  },
  body: JSON.stringify({
    messageType: 'text',
    content: '@全体成员 重要通知！',
    atUserIds: [],
    atAll: true
  })
});
```

### 管理员操作

```javascript
// 设置管理员
await fetch(`/api/front/groups/${groupId}/members/${userId}/admin`, {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + token
  },
  body: JSON.stringify({
    isAdmin: true
  })
});

// 禁言成员（禁言1小时）
const muteEndTime = Date.now() + 3600000;
await fetch(`/api/front/groups/${groupId}/members/${userId}/mute`, {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + token
  },
  body: JSON.stringify({
    muteEndTime: muteEndTime
  })
});

// 设置全员禁言
await fetch(`/api/front/groups/${groupId}/mute-all`, {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + token
  },
  body: JSON.stringify({
    muteAll: true
  })
});
```

---

## ⚠️ 注意事项

### 登录验证
- 所有接口都需要登录后才能访问
- 未登录会返回401 UNAUTHORIZED错误
- Token通过Authorization头传递

### 权限验证
- 权限验证在Service层进行
- 权限不足会抛出异常并返回错误信息
- 群主不能退出群组（需要先转让群主）

### 逻辑删除
- 解散群组、移除成员、退出群组、删除消息都使用逻辑删除
- 逻辑删除的数据不会真正从数据库中删除
- 可以通过is_deleted字段查询已删除的数据

### 消息撤回
- 只能撤回2分钟内的消息
- 只能撤回自己发送的消息
- 撤回后消息不会被删除，只是标记为已撤回

### 扩展字段
- 预留了5个扩展字段（ext_field1-5）
- 可以根据业务需求自定义使用
- 建议使用JSON格式存储复杂数据

---

## 🔧 技术实现

### JPA自动建表
```java
@Entity
@Table(name = "eb_group")
public class Group {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @TableLogic
    private Boolean isDeleted;
    
    @UpdateTimestamp
    private Date updateTime;
}
```

### 逻辑删除
```java
// MyBatis-Plus会自动处理逻辑删除
groupDao.deleteById(groupId); // 实际执行：UPDATE eb_group SET is_deleted=1 WHERE id=?
```

### 自动时间管理
```java
@CreationTimestamp  // 创建时自动设置
private Date createTime;

@UpdateTimestamp    // 更新时自动设置
private Date updateTime;
```

---

## 📚 相关文档

- [直播IM系统开发指南.md](./直播IM系统开发指南.md) - 完整的开发指南
- [群组聊天模块登录验证完善总结.md](./群组聊天模块登录验证完善总结.md) - 详细的完善总结
- [群组聊天和消息撤回模块完成总结.md](./群组聊天和消息撤回模块完成总结.md) - 模块完成总结

---

**最后更新**: 2024年12月26日  
**模块状态**: ✅ 已完成  
**代码质量**: ✅ 优秀