1
This commit is contained in:
张成
281
_doc/聊天列表功能说明.md
Normal file
281
_doc/聊天列表功能说明.md
Normal file
@@ -0,0 +1,281 @@
|
||||
# 聊天列表功能说明
|
||||
|
||||
## 功能概述
|
||||
|
||||
聊天列表模块实现了管理后台的实时聊天功能,包括:
|
||||
- 会话列表展示
|
||||
- 实时消息收发
|
||||
- 消息历史记录
|
||||
- 轮询机制接收新消息
|
||||
|
||||
## 功能特性
|
||||
|
||||
### 1. 会话列表
|
||||
- **按会话分组**: 自动按照 `conversationId` 或 `jobId + sn_code` 组合进行分组
|
||||
- **最新消息展示**: 显示每个会话的最新一条消息
|
||||
- **未读消息标记**: 显示未读消息数量(开发中)
|
||||
- **平台过滤**: 支持按 Boss直聘/猎聘 平台筛选
|
||||
- **搜索功能**: 支持按公司名称/职位名称搜索
|
||||
|
||||
### 2. 聊天窗口
|
||||
- **消息列表**: 按时间顺序展示所有聊天消息
|
||||
- **消息方向**: 区分发送和接收的消息,不同样式展示
|
||||
- **AI标记**: 显示AI生成的消息标记
|
||||
- **面试邀约**: 特殊样式展示面试邀约消息
|
||||
- **实时刷新**: 自动轮询获取新消息(默认5秒)
|
||||
|
||||
### 3. 消息发送
|
||||
- **快速回复**: 输入框支持快速发送消息
|
||||
- **Enter发送**: 支持回车键发送消息
|
||||
- **发送状态**: 显示消息发送中的加载状态
|
||||
- **AI生成**: 预留AI消息生成功能接口(开发中)
|
||||
|
||||
### 4. 定时刷新机制
|
||||
- **自动刷新**: 使用 setInterval 定时刷新消息
|
||||
- **可配置间隔**: 默认10秒,可自定义刷新间隔
|
||||
- **资源释放**: 页面销毁时自动清除定时器
|
||||
- **简单高效**: 使用Ajax轮询,无需WebSocket
|
||||
|
||||
## 文件结构
|
||||
|
||||
```
|
||||
admin/src/
|
||||
├── views/chat/
|
||||
│ ├── chat_list.vue # 聊天列表页面(新增)
|
||||
│ └── chat_records.vue # 聊天记录管理页面(原有)
|
||||
├── api/operation/
|
||||
│ └── chat_records_server.js # 聊天API服务
|
||||
└── router/
|
||||
└── component-map.js # 路由组件映射
|
||||
|
||||
api/
|
||||
├── controller_admin/
|
||||
│ └── chat_records.js # 聊天记录后端控制器(已扩展)
|
||||
└── model/
|
||||
└── chat_records.js # 聊天记录数据模型
|
||||
```
|
||||
|
||||
## API 接口
|
||||
|
||||
### 前端API服务 (chat_records_server.js)
|
||||
|
||||
| 方法 | 说明 | 参数 |
|
||||
|------|------|------|
|
||||
| `page(param)` | 分页查询聊天记录 | seachOption, pageOption |
|
||||
| `getByJobId(params)` | 获取指定职位的聊天记录 | jobId, sn_code |
|
||||
| `sendMessage(data)` | 发送聊天消息 | sn_code, jobId, content, chatType, platform |
|
||||
| `getUnreadCount(params)` | 获取未读消息数量 | sn_code |
|
||||
| `markAsRead(data)` | 标记消息为已读 | chatId |
|
||||
| `getStatistics()` | 获取聊天统计数据 | - |
|
||||
|
||||
### 后端API接口
|
||||
|
||||
| 接口 | 方法 | 说明 |
|
||||
|------|------|------|
|
||||
| `/admin_api/chat/list` | POST | 获取聊天记录列表 |
|
||||
| `/admin_api/chat/by-job` | GET | 获取指定职位的聊天记录 |
|
||||
| `/admin_api/chat/send` | POST | 发送聊天消息 |
|
||||
| `/admin_api/chat/unread-count` | GET | 获取未读消息数量 |
|
||||
| `/admin_api/chat/mark-read` | POST | 标记消息为已读 |
|
||||
| `/admin_api/chat/statistics` | GET | 获取聊天统计数据 |
|
||||
| `/admin_api/chat/detail` | GET | 获取聊天记录详情 |
|
||||
| `/admin_api/chat/delete` | POST | 删除聊天记录 |
|
||||
|
||||
## 使用说明
|
||||
|
||||
### 1. 访问聊天列表页面
|
||||
|
||||
在后台菜单中添加聊天列表页面的路由配置:
|
||||
|
||||
```javascript
|
||||
{
|
||||
name: '聊天列表',
|
||||
path: '/chat/chat_list',
|
||||
component: 'chat/chat_list'
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 查看会话列表
|
||||
|
||||
- 左侧显示所有会话列表
|
||||
- 每个会话显示公司名称、职位名称、最新消息和时间
|
||||
- 点击会话可在右侧查看完整的聊天记录
|
||||
|
||||
### 3. 发送消息
|
||||
|
||||
1. 在左侧选择一个会话
|
||||
2. 在右侧聊天窗口底部的输入框中输入消息
|
||||
3. 点击"发送"按钮或按回车键发送
|
||||
4. 消息发送成功后会自动刷新聊天记录
|
||||
|
||||
### 4. 筛选和搜索
|
||||
|
||||
- **平台筛选**: 在顶部选择 Boss直聘 或 猎聘 进行筛选
|
||||
- **关键词搜索**: 在搜索框输入公司名称或职位名称进行搜索
|
||||
- 筛选和搜索会实时更新会话列表
|
||||
|
||||
## 数据模型
|
||||
|
||||
### 聊天记录模型 (chat_records)
|
||||
|
||||
主要字段:
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | INTEGER | 主键ID |
|
||||
| sn_code | STRING | 设备SN码 |
|
||||
| platform | STRING | 平台(boss/liepin) |
|
||||
| jobId | STRING | 职位ID |
|
||||
| companyName | STRING | 公司名称 |
|
||||
| jobTitle | STRING | 职位名称 |
|
||||
| hrName | STRING | HR姓名 |
|
||||
| content | TEXT | 消息内容 |
|
||||
| direction | STRING | 消息方向(sent/received) |
|
||||
| chatType | STRING | 聊天类型(greeting/reply/interview) |
|
||||
| sendStatus | STRING | 发送状态(pending/sent/failed) |
|
||||
| sendTime | DATE | 发送时间 |
|
||||
| receiveTime | DATE | 接收时间 |
|
||||
| hasReply | BOOLEAN | 是否有回复 |
|
||||
| conversationId | STRING | 会话ID |
|
||||
| isAiGenerated | BOOLEAN | 是否AI生成 |
|
||||
| isInterviewInvitation | BOOLEAN | 是否面试邀约 |
|
||||
|
||||
## 技术实现
|
||||
|
||||
### 1. 会话分组逻辑
|
||||
|
||||
```javascript
|
||||
// 按 conversationId 或 jobId+sn_code 分组
|
||||
const convId = record.conversationId || `${record.jobId}_${record.sn_code}`
|
||||
```
|
||||
|
||||
### 2. 定时刷新机制
|
||||
|
||||
```javascript
|
||||
// 启动定时刷新
|
||||
startAutoRefresh() {
|
||||
this.refreshTimer = setInterval(() => {
|
||||
// 如果有选中的会话,刷新消息
|
||||
if (this.activeConversation) {
|
||||
this.loadChatMessages()
|
||||
}
|
||||
// 刷新会话列表
|
||||
this.loadConversations()
|
||||
}, this.refreshInterval) // 默认10秒
|
||||
}
|
||||
|
||||
// 停止定时刷新
|
||||
stopAutoRefresh() {
|
||||
if (this.refreshTimer) {
|
||||
clearInterval(this.refreshTimer)
|
||||
this.refreshTimer = null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 消息发送流程
|
||||
|
||||
1. 前端调用 `chatRecordsServer.sendMessage()`
|
||||
2. 后端创建聊天记录,状态为 `pending`
|
||||
3. 后端通过MQTT发送消息到设备(待实现)
|
||||
4. 更新聊天记录状态为 `sent`
|
||||
5. 前端刷新消息列表
|
||||
|
||||
## 待开发功能
|
||||
|
||||
### 1. 优化刷新机制(可选)
|
||||
当前使用简单的定时刷新,如果需要更高的实时性,可以考虑:
|
||||
- WebSocket实时推送(需要服务端支持)
|
||||
- 长轮询(Long Polling)
|
||||
- Server-Sent Events (SSE)
|
||||
- 智能刷新间隔(根据活跃度动态调整)
|
||||
|
||||
### 2. AI消息生成
|
||||
集成AI服务生成智能回复:
|
||||
- 根据聊天上下文生成合适的回复
|
||||
- 支持不同的回复风格
|
||||
- 提高回复效率
|
||||
|
||||
### 3. 富文本消息
|
||||
支持更丰富的消息类型:
|
||||
- 图片消息
|
||||
- 文件消息
|
||||
- 表情包
|
||||
- Markdown格式
|
||||
|
||||
### 4. 消息状态管理
|
||||
完善消息状态:
|
||||
- 已读/未读状态
|
||||
- 消息撤回
|
||||
- 消息编辑
|
||||
- 消息引用回复
|
||||
|
||||
### 5. 会话管理
|
||||
增强会话管理功能:
|
||||
- 会话置顶
|
||||
- 会话静音
|
||||
- 会话归档
|
||||
- 会话标签
|
||||
|
||||
## 注意事项
|
||||
|
||||
### 1. MQTT集成
|
||||
当前消息发送功能需要集成MQTT客户端才能真正发送到设备。在 `chat_records.js` 控制器中有TODO标记:
|
||||
|
||||
```javascript
|
||||
// TODO: 这里需要通过MQTT发送消息到设备
|
||||
// 目前先简单返回成功,实际需要集成MQTT客户端
|
||||
```
|
||||
|
||||
### 2. 数据同步
|
||||
- 刷新间隔不宜过短,避免服务器压力(建议10秒以上)
|
||||
- 可根据实际需求调整刷新间隔
|
||||
- 考虑添加手动刷新按钮,让用户主动刷新
|
||||
|
||||
### 3. 性能优化
|
||||
- 会话列表分页加载
|
||||
- 消息列表虚拟滚动
|
||||
- 图片懒加载
|
||||
- 消息缓存机制
|
||||
|
||||
### 4. 安全性
|
||||
- 消息内容过滤和验证
|
||||
- 防止XSS攻击
|
||||
- 消息发送频率限制
|
||||
- 敏感信息加密
|
||||
|
||||
## 测试建议
|
||||
|
||||
### 1. 功能测试
|
||||
- 测试会话列表加载
|
||||
- 测试消息发送和接收
|
||||
- 测试筛选和搜索功能
|
||||
- 测试定时刷新机制
|
||||
|
||||
### 2. 边界测试
|
||||
- 测试空会话列表
|
||||
- 测试空消息列表
|
||||
- 测试网络异常情况
|
||||
- 测试大量消息加载
|
||||
|
||||
### 3. 性能测试
|
||||
- 测试大量会话的加载速度
|
||||
- 测试长时间运行的内存占用
|
||||
- 测试频繁切换会话的响应速度
|
||||
|
||||
## 更新日志
|
||||
|
||||
### v1.0.0 (2025-01-XX)
|
||||
- ✅ 创建聊天列表页面
|
||||
- ✅ 实现会话分组和展示
|
||||
- ✅ 实现消息发送功能
|
||||
- ✅ 实现定时刷新接收新消息(Ajax轮询)
|
||||
- ✅ 添加后端API接口
|
||||
- ✅ 支持平台筛选和搜索
|
||||
|
||||
### 计划中
|
||||
- ⏳ AI消息生成
|
||||
- ⏳ 富文本消息支持
|
||||
- ⏳ 完善消息状态管理
|
||||
- ⏳ 增强会话管理功能
|
||||
- ⏳ 优化刷新机制(WebSocket/长轮询等)
|
||||
Reference in New Issue
Block a user