# 聊天列表功能说明

## 功能概述

聊天列表模块实现了管理后台的实时聊天功能,包括:
- 会话列表展示
- 实时消息收发
- 消息历史记录
- 轮询机制接收新消息

## 功能特性

### 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/长轮询等)