# 消息搜索模块快速参考

> **快速上手指南** | **版本**: v1.0 | **更新时间**: 2024年12月26日

---

## 📋 API接口速查

### 1. 搜索私聊消息

```http
GET /api/front/messages/search/private
```

**参数：**
- `keyword` (必填) - 搜索关键词
- `messageType` (可选) - text/image/voice/video/file
- `startTime` (可选) - 开始时间
- `endTime` (可选) - 结束时间
- `pageNum` (可选) - 页码，默认1
- `pageSize` (可选) - 每页数量，默认20

### 2. 搜索群组消息

```http
GET /api/front/messages/search/group
```

**参数：** 同上

### 3. 在会话中搜索

```http
GET /api/front/messages/search/conversation/{conversationId}
```

**参数：** 同搜索私聊消息

### 4. 在群组中搜索

```http
GET /api/front/messages/search/group/{groupId}
```

**参数：** 同搜索私聊消息

### 5. 获取搜索历史

```http
GET /api/front/messages/search/history?limit=10
```

### 6. 清除搜索历史

```http
DELETE /api/front/messages/search/history
```

---

## 🔧 核心类说明

### Controller层

**MessageSearchController**
- 路径: `crmeb-front/src/main/java/com/zbkj/front/controller/MessageSearchController.java`
- 功能: 提供搜索API接口

### Service层

**MessageSearchService**
- 路径: `crmeb-service/src/main/java/com/zbkj/service/service/MessageSearchService.java`
- 功能: 搜索服务接口定义

**MessageSearchServiceImpl**
- 路径: `crmeb-service/src/main/java/com/zbkj/service/service/impl/MessageSearchServiceImpl.java`
- 功能: 搜索服务实现

---

## 💡 使用示例

### 示例1：搜索私聊消息

```bash
curl -X GET "http://localhost:8080/api/front/messages/search/private?keyword=你好&pageNum=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### 示例2：搜索群组消息（带时间过滤）

```bash
curl -X GET "http://localhost:8080/api/front/messages/search/group?keyword=测试&startTime=2024-12-01%2000:00:00&endTime=2024-12-26%2023:59:59" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### 示例3：搜索图片消息

```bash
curl -X GET "http://localhost:8080/api/front/messages/search/private?keyword=&messageType=image" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

## 🎯 核心功能

### 搜索功能

- ✅ 私聊消息搜索（全局）
- ✅ 群组消息搜索（全局）
- ✅ 会话内搜索（精确）
- ✅ 群组内搜索（精确）
- ✅ 按关键词模糊查询
- ✅ 按消息类型过滤
- ✅ 按时间范围过滤
- ✅ 分页查询

### 搜索历史

- ✅ 自动保存搜索历史
- ✅ 获取搜索历史列表
- ✅ 清除搜索历史
- ✅ Redis存储（30天过期）
- ✅ 最多保存20条

### 权限验证

- ✅ 验证用户身份
- ✅ 验证会话权限
- ✅ 验证群组成员身份
- ✅ 排除已删除的消息
- ✅ 排除已撤回的消息

---

## 📊 技术特点

### 1. 标准三层架构

```
Controller → Service → DAO → Database
```

### 2. MyBatis-Plus查询

- 无需编写SQL语句
- 使用LambdaQueryWrapper构建查询
- 类型安全，避免拼写错误

### 3. Redis搜索历史

- 使用ZSet按时间排序
- 自动过期（30天）
- 限制数量（最多20条）

### 4. 性能优化

- 分页查询，避免大量数据加载
- 使用数据库索引加速查询
- Redis缓存搜索历史

---

## ⚠️ 注意事项

### 1. 权限控制

- 用户只能搜索自己相关的消息
- 非会话成员无法搜索会话消息
- 非群组成员无法搜索群组消息

### 2. 数据过滤

- 自动排除已删除的消息
- 自动排除已撤回的消息
- 支持按消息类型过滤

### 3. 搜索历史

- 自动保存搜索关键词
- 30天自动过期
- 最多保存20条

### 4. 性能考虑

- 使用LIKE模糊查询（适合单机部署）
- 未来可升级为Elasticsearch（支持更大规模）
- 建议添加数据库索引（conversation_id、group_id、create_time）

---

## 🔍 搜索逻辑

### 私聊消息搜索

1. 验证用户身份
2. 保存搜索历史
3. 构建查询条件（用户必须是发送者或接收者）
4. 关键词模糊匹配
5. 应用过滤条件（类型、时间）
6. 排除已删除和已撤回的消息
7. 分页查询并返回结果

### 群组消息搜索

1. 验证用户身份
2. 获取用户所在的所有群组
3. 保存搜索历史
4. 构建查询条件（只搜索用户所在的群组）
5. 关键词模糊匹配
6. 应用过滤条件（类型、时间）
7. 排除已删除和已撤回的消息
8. 分页查询并返回结果

---

## 🚀 快速测试

### 1. 测试搜索私聊消息

```bash
# 搜索包含"你好"的消息
curl -X GET "http://localhost:8080/api/front/messages/search/private?keyword=你好" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### 2. 测试搜索群组消息

```bash
# 搜索包含"测试"的群组消息
curl -X GET "http://localhost:8080/api/front/messages/search/group?keyword=测试" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### 3. 测试获取搜索历史

```bash
curl -X GET "http://localhost:8080/api/front/messages/search/history?limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### 4. 测试清除搜索历史

```bash
curl -X DELETE "http://localhost:8080/api/front/messages/search/history" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

## 📝 常见问题

### Q1: 搜索结果为空？

**可能原因：**
- 关键词不匹配
- 消息已被删除或撤回
- 用户不是会话或群组成员
- 时间范围过滤过于严格

**解决方法：**
- 检查关键词是否正确
- 检查时间范围是否合理
- 确认用户权限

### Q2: 搜索速度慢？

**可能原因：**
- 数据量过大
- 缺少数据库索引
- 查询条件过于宽泛

**解决方法：**
- 添加数据库索引
- 使用时间范围过滤
- 考虑升级为Elasticsearch

### Q3: 搜索历史不显示？

**可能原因：**
- Redis连接失败
- 搜索历史已过期
- 搜索历史已清除

**解决方法：**
- 检查Redis连接
- 重新搜索以保存历史
- 确认搜索历史未被清除

---

## 📚 相关文档

- **完成总结**: `消息搜索模块完成总结.md`
- **开发指南**: `直播IM系统开发指南.md`

---

**文档版本**: v1.0  
**最后更新**: 2024年12月26日  
**维护状态**: ✅ 已完成