# AI-CS 智能客服系统 - 完整测试指南

> 📋 本文档用于全面测试已实现的功能和需求
> 
> 最后更新：2025-11-12

## 📑 目录

- [一、准备工作](#一准备工作)
- [二、启动后端](#二启动后端)
- [三、启动前端](#三启动前端)
- [四、访客端测试流程](#四访客端测试流程)
  - [测试 1：访问聊天页面](#测试-1访问聊天页面访客端)
  - [测试 2：发送第一条消息](#测试-2发送第一条消息)
  - [测试 3：发送多条消息](#测试-3发送多条消息)
  - [测试 4：接收客服消息（实时推送）](#测试-4接收客服消息实时推送)
  - [测试 5：已读状态同步](#测试-5已读状态同步)
  - [测试 6：刷新页面](#测试-6刷新页面)
  - [测试 7：打开新标签页](#测试-7打开新标签页验证-localstorage-共享)
  - [测试 8：测试错误处理](#测试-8测试错误处理)
- [五、客服端测试流程](#五客服端测试流程)
  - [测试 1：客服登录](#测试-1客服登录)
  - [测试 2：客服工作台（四栏布局）](#测试-2客服工作台四栏布局)
  - [测试 3：查看对话列表](#测试-3查看对话列表)
  - [测试 4：选择对话](#测试-4选择对话)
  - [测试 5：查看对话消息](#测试-5查看对话消息)
  - [测试 6：客服发送消息](#测试-6客服发送消息)
  - [测试 7：接收访客消息（实时推送）](#测试-7接收访客消息实时推送)
  - [测试 8：已读状态同步](#测试-8已读状态同步)
  - [测试 9：对话搜索功能](#测试-9对话搜索功能)
  - [测试 10：查看访客详情](#测试-10查看访客详情)
  - [测试 11：编辑联系信息](#测试-11编辑联系信息)
  - [测试 12：在线/离线状态显示](#测试-12在线离线状态显示)
  - [测试 13：刷新访客详情](#测试-13刷新访客详情)
  - [测试 14：返回对话列表](#测试-14返回对话列表)
  - [测试 15：退出登录](#测试-15退出登录)
  - [测试 16：登录状态检查](#测试-16登录状态检查)
- [六、调试技巧](#六调试技巧)
- [七、常见问题](#七常见问题)
- [八、完整测试检查清单](#八完整测试检查清单)
- [九、快速测试流程（核心功能验证）](#九快速测试流程核心功能验证)
- [十、高级测试场景](#十高级测试场景)
  - [场景 1：多个访客同时聊天](#场景-1多个访客同时聊天)
  - [场景 2：并发消息测试](#场景-2并发消息测试)
  - [场景 3：长时间连接测试](#场景-3长时间连接测试)
  - [场景 4：网络中断恢复测试](#场景-4网络中断恢复测试)
  - [场景 5：大量消息历史测试](#场景-5大量消息历史测试)
  - [场景 6：搜索性能测试](#场景-6搜索性能测试)
  - [场景 7：联系信息编辑并发测试](#场景-7联系信息编辑并发测试)
  - [场景 8：在线状态多访客测试](#场景-8在线状态多访客测试)
- [十一、测试结果记录](#十一测试结果记录)

---

## 一、准备工作

### ⚡ 快速开始（5分钟快速验证）

如果你想快速验证系统是否正常工作，可以按照以下步骤：

1. **启动后端**（1分钟）
   ```bash
   cd backend
   go run main.go
   ```
   看到 `🚀 服务器启动成功，监听 :8080` 表示启动成功

2. **启动前端**（1分钟）
   ```bash
   cd frontend
   npm run dev
   ```
   看到 `Ready` 表示启动成功

3. **测试访客端**（1分钟）
   - 访问 `http://localhost:3000/chat`
   - 发送消息："你好，这是测试消息"
   - 确认消息显示在右侧（蓝色气泡）

4. **测试客服端**（2分钟）
   - 访问 `http://localhost:3000/`，使用 admin/admin123 登录
   - 确认进入客服工作台（四栏布局）
   - 确认对话列表显示刚才的对话
   - 点击对话，确认消息显示在中间栏

**如果以上步骤都正常，说明系统基本功能正常！** ✅

详细测试请参考 [九、快速测试流程（核心功能验证）](#九快速测试流程核心功能验证)

---

### 1. 检查数据库配置
确保 `backend/.env` 文件存在并配置正确：

```env
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_NAME=CS
```

**注意**：
- `DB_PASSWORD` 改成你的 MySQL 密码
- `DB_NAME=CS` 是数据库名，如果不存在会自动创建（需要先手动创建数据库）

### 2. 创建数据库（如果还没有）
```sql
CREATE DATABASE CS CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

## 二、启动后端

### 步骤 1：进入后端目录
```bash
cd backend
```

### 步骤 2：安装依赖（如果还没安装）
```bash
go mod tidy
```

### 步骤 3：启动后端服务
```bash
go run main.go
```

**成功标志**：
- 看到类似这样的输出：
```
✅ 找到 .env 文件: D:\tools\AI-CS\backend\.env
✅ .env 文件加载成功
✅ 管理员账号已存在
[GIN-debug] POST   /login                    --> ...
[GIN-debug] POST   /logout                   --> ...
[GIN-debug] POST   /conversation/init        --> ...
[GIN-debug] GET    /conversations            --> ...
[GIN-debug] GET    /conversations/:id        --> ...
[GIN-debug] PUT    /conversations/:id/contact --> ...
[GIN-debug] GET    /conversations/search     --> ...
[GIN-debug] POST   /messages                 --> ...
[GIN-debug] GET    /messages                 --> ...
[GIN-debug] PUT    /messages/read            --> ...
[GIN-debug] GET    /ws                       --> ...
🚀 服务器启动成功，监听 :8080
📡 WebSocket 服务已启动，路径: /ws?conversation_id=<对话ID>
```

**如果出错**：
- 数据库连接失败：检查 `.env` 配置和 MySQL 是否启动
- 端口被占用：检查 8080 端口是否被其他程序占用

## 三、启动前端

### 步骤 1：打开新的终端窗口
**重要**：后端和前端要在不同的终端窗口运行！

### 步骤 2：进入前端目录
```bash
cd frontend
```

### 步骤 3：安装依赖（如果还没安装）
```bash
npm install
```

### 步骤 4：启动前端开发服务器
```bash
npm run dev
```

**成功标志**：
- 看到类似这样的输出：
```
  ▲ Next.js 15.5.3
  - Local:        http://localhost:3000
  - Ready in 2.3s
```

### 步骤 5：打开浏览器
访问：`http://localhost:3000`

## 四、测试流程

### ⚠️ 重要说明
**系统包含两个端**：
- **访客端** (`/chat`)：不需要登录，直接访问即可使用
- **客服端** (`/` → `/agent/dashboard`)：需要登录，使用管理员/客服账号

**测试时你需要分别测试两个端**！

**已实现的核心功能**：
- ✅ 客服工作台（四栏布局：导航栏、对话列表、聊天内容、访客详情）
- ✅ WebSocket 实时通信（消息实时推送、已读状态同步、在线状态更新）
- ✅ 对话搜索功能（支持搜索消息内容、对话ID、访客ID）
- ✅ 访客信息收集和显示（网站、来源、浏览器、操作系统、语言、IP地址）
- ✅ 联系信息编辑（邮箱、电话、备注）
- ✅ 在线/离线状态显示（实时更新）
- ✅ 已读状态同步（单对勾/双对勾）
- ✅ 系统消息显示（访客打开页面、来源信息等）
- ✅ 关键词高亮（搜索时高亮显示）
- ✅ 消息预览（对话列表显示最后一条消息）

## 四、访客端测试流程

### 测试 1：访问聊天页面（访客端）
1. 在浏览器打开 `http://localhost:3000/chat`
2. **预期结果**：
   - 看到顶部标题栏（渐变背景）
   - 显示"访客聊天"和会话ID、访客ID（自动生成）
   - 消息列表区域显示系统消息（如 "Visitor opened the page [URL]"）
     - 系统消息居中显示（灰色背景，圆角边框）
     - 显示当前页面URL（如果有）
   - 如果有来源页面，显示 "Visitor came from [referrer URL]"
     - 系统消息居中显示（灰色背景，圆角边框）
     - 显示来源页面URL
   - 底部有输入框和"发送"按钮
   - **不需要登录，直接可以使用！**
   - WebSocket 连接自动建立（查看浏览器控制台，应该看到 "✅ WebSocket 连接成功: 对话ID=X"）
   - 后端日志显示：`✅ WebSocket 连接已建立: 对话ID=X, 是访客=true`
   - 后端日志显示：`✅ 客户端已连接: 对话ID=X, 总连接数=1, 访客连接数=1`

### 测试 2：发送第一条消息
1. 在输入框输入："你好，这是第一条消息"
2. 点击"发送"按钮
3. **预期结果**：
   - 输入框清空
   - 消息立即出现在右侧（蓝色气泡，显示"我"）
   - 显示时间（如 "14:30"）
   - 显示已读状态（单对勾，表示已发送但未读）
   - 页面自动滚动到底部
   - 消息通过 WebSocket 实时推送到客服端

### 测试 3：发送多条消息
1. 连续发送 3-5 条消息
2. **预期结果**：
   - 每条消息都显示在右侧
   - 消息按时间顺序排列
   - 每次发送后自动滚动到底部
   - 每条消息显示已读状态（单对勾）

### 测试 4：接收客服消息（实时推送）
1. **打开两个浏览器标签页**：
   - 标签页1：访客端 (`http://localhost:3000/chat`)
   - 标签页2：客服端 (`http://localhost:3000/agent/dashboard`)，需要先登录
2. **在客服端发送消息**："您好，我是客服，有什么可以帮您的吗？"
3. **预期结果**（访客端）：
   - **无需刷新页面**，消息自动出现在左侧（白色气泡）
   - 消息显示时间
   - 自动滚动到底部（如果当前在底部）
   - 显示已读状态（单对勾，表示客服已读）
   - 这是通过 WebSocket 实时推送的！

### 测试 5：已读状态同步
1. **在客服端查看访客消息**（客服端会自动标记已读）
2. **预期结果**（访客端）：
   - **无需刷新页面**，已读状态从单对勾变为双对勾
   - 对勾颜色变为蓝色（表示已读）
   - 这是通过 WebSocket 实时推送 `messages_read` 事件实现的！

### 测试 6：刷新页面
1. 按 `F5` 刷新页面
2. **预期结果**：
   - 之前发送的消息还在（因为存到数据库了）
   - 自动拉取历史消息
   - 访客ID不变（因为存在 localStorage）
   - 系统消息显示（如 "Visitor opened the page"）
   - WebSocket 连接重新建立

### 测试 7：打开新标签页（验证 localStorage 共享）
1. 打开新的浏览器标签页，访问 `http://localhost:3000/chat`
2. **预期结果**：
   - **使用的是同一个访客ID**（因为 localStorage 在同一浏览器不同标签页之间共享）
   - **显示同一个对话**（因为 visitor_id 相同）
   - **能看到之前发送的消息**（因为是同一个对话）
   - 系统消息显示（如 "Visitor opened the page"）

**注意**：
- 同一浏览器不同标签页 → 共享 localStorage → 同一个访客ID → 同一个对话
- 如果要测试新访客，需要：
  - 使用不同的浏览器（Chrome、Edge、Firefox等）
  - 或者清除浏览器缓存/localStorage
  - 或者使用隐私/无痕模式

### 测试 8：测试错误处理
1. **停止后端**（在运行 `go run main.go` 的终端按 `Ctrl+C`）
2. 尝试发送消息
3. **预期结果**：
   - 弹出错误提示："发送消息失败，请稍后重试"
   - 按钮恢复正常（不再是"发送中..."）
   - WebSocket 连接断开（查看浏览器控制台，应该看到 "❌ WebSocket 连接关闭"）

---

## 五、客服端测试流程

### 测试 1：客服登录
1. 访问 `http://localhost:3000/`（根路径）
2. **预期结果**：
   - 看到客服登录页面
   - 有用户名和密码输入框
   - 有"登录"按钮
   - 显示默认管理员账号提示（用户名: admin，密码: admin123）

3. **输入登录信息**：
   - 用户名：`admin`
   - 密码：`admin123`
4. 点击"登录"按钮
5. **预期结果**：
   - 登录成功，自动跳转到 `/agent/dashboard`（客服工作台）
   - 浏览器 localStorage 中保存了 `agent_user_id`、`agent_username`、`agent_role`

### 测试 2：客服工作台（四栏布局）
1. 登录成功后，自动进入客服工作台
2. **预期结果**：
   - **最左侧导航栏**（固定宽度 64px）：显示导航图标
   - **左侧对话列表栏**（固定宽度 320px）：显示所有对话列表
   - **中间聊天内容栏**（自适应宽度）：显示当前选中对话的消息
   - **右侧访客详情栏**（固定宽度 320px）：显示当前选中对话的访客详情
   - 顶部显示当前登录的用户名和角色（如："admin (管理员)"）
   - 显示"退出"按钮

### 测试 3：查看对话列表
1. 在工作台左侧查看对话列表
2. **预期结果**：
   - 显示所有未关闭的对话列表（如果有访客发送过消息）
   - 每条对话显示：
     - 对话头像（圆形，基于 visitor_id 生成颜色）
     - 对话ID、访客ID
     - 在线/离线状态图标（绿色圆点 = 在线）
     - 状态标签（"进行中"或"已关闭"）
     - 最后一条消息预览（显示最后一条消息的前50个字符）
     - 未读消息数量（蓝色徽标，如果有未读消息）
     - 已读/未读状态图标（单/双对勾）
     - 最后更新时间（智能格式化：今天显示时间，更早显示日期+时间）
   - 对话按更新时间倒序排列（最新的在前）
   - 选中对话高亮显示（蓝色背景）

3. **如果没有对话**：
   - 需要先访问 `/chat` 页面（访客端）发送一些消息
   - 然后刷新客服端，就能看到对话了

### 测试 4：选择对话
1. 在对话列表中，点击任意一条对话
2. **预期结果**：
   - 对话高亮显示（蓝色背景）
   - **中间栏**自动加载该对话的消息
   - **右侧栏**自动加载该对话的访客详情
   - WebSocket 连接自动切换到该对话
   - 无需跳转页面，所有内容在同一页面更新

### 测试 5：查看对话消息
1. 选择一条对话后，查看中间栏的消息列表
2. **预期结果**：
   - 显示该对话的所有消息（包括系统消息）
   - **访客消息在左侧**（白色气泡）
   - **客服消息在右侧**（蓝色气泡）
   - 系统消息居中显示（灰色背景，如 "Visitor opened the page [URL]"）
   - 每条消息显示时间（智能格式化）
   - 客服消息显示已读/未读状态（单/双对勾）
   - 自动滚动到底部（如果是新对话）
   - 消息按时间顺序排列

### 测试 6：客服发送消息
1. 在中间栏输入框输入消息："您好，我是客服，有什么可以帮您的吗？"
2. 点击"发送"按钮
3. **预期结果**：
   - 输入框清空
   - 消息立即出现在右侧（蓝色气泡，客服消息）
   - 显示时间
   - 显示已读状态（单对勾，表示已发送但未读）
   - 页面自动滚动到底部
   - 消息通过 WebSocket 实时推送到访客端
   - 对话列表中的最后一条消息预览自动更新

### 测试 7：接收访客消息（实时推送）
1. **打开两个浏览器标签页**：
   - 标签页1：访客端 (`http://localhost:3000/chat`)
   - 标签页2：客服端 (`http://localhost:3000/agent/dashboard`)，需要先登录
2. **在访客端发送消息**："你好，我需要帮助"
3. **预期结果**（客服端）：
   - **无需刷新页面**，消息自动出现在左侧（白色气泡）
   - 消息显示时间
   - 自动滚动到底部（如果当前在底部）
   - 对话列表中的最后一条消息预览自动更新
   - 未读消息数量自动更新（蓝色徽标）
   - 这是通过 WebSocket 实时推送的！

### 测试 8：已读状态同步
1. **在客服端查看访客消息**（客服端会自动标记已读）
2. **预期结果**（访客端）：
   - **无需刷新页面**，已读状态从单对勾变为双对勾
   - 对勾颜色变为蓝色（表示已读）
   - 这是通过 WebSocket 实时推送 `messages_read` 事件实现的！
3. **预期结果**（客服端）：
   - 未读消息数量自动减少
   - 已读状态图标更新（双对勾）

### 测试 9：对话搜索功能
1. 在左侧对话列表顶部，找到搜索框（显示 "Q Search" 或搜索图标）
2. **输入搜索关键词**（例如：对话ID、访客ID、消息内容）
   - 例如：搜索 "你好"（如果消息中包含"你好"）
   - 例如：搜索对话ID "10"（如果对话ID为10）
   - 例如：搜索访客ID "176"（如果访客ID为176）
3. **预期结果**：
   - 实时搜索（300ms 防抖，输入后等待 300ms 才开始搜索）
   - 显示匹配的对话列表（只显示包含关键词的对话）
   - 搜索结果高亮显示（关键词黄色背景高亮，使用 `<mark>` 标签）
   - 点击搜索结果，自动定位到匹配消息
     - 如果匹配消息在历史记录中，自动滚动到匹配消息并居中显示
     - 如果匹配消息是最后一条，自动滚动到底部
     - 高亮显示持续 3 秒后自动清除
   - 清除搜索后，显示所有对话
   - 搜索框为空时，显示所有对话

### 测试 10：查看访客详情
1. 选择一条对话后，查看右侧栏的访客详情
2. **预期结果**：
   - 显示访客头像（圆形，基于 visitor_id 生成颜色）
   - 显示访客ID（例如："访客 #176"）
   - 显示在线/离线状态（绿色圆点 = 在线，灰色 = 离线）
   - 显示刷新按钮（圆形箭头图标）和更多选项图标（三个点）
   - **联系信息区域**：
     - 邮箱（可以编辑，显示"+ Add"或"编辑"按钮）
     - 电话（可以编辑，显示"+ Add"或"编辑"按钮）
     - 备注（可以编辑，显示"+ Add"或"编辑"按钮）
   - **技术信息区域**：
     - 网站（当前页面URL，如果有，显示为链接）
     - 来源（referrer，从哪个页面跳转过来，如果有，显示为链接）
     - 语言（浏览器语言设置，例如："zh-CN"）
     - 浏览器（浏览器信息，例如："Edge"、"Chrome"）
     - 操作系统（操作系统信息，例如："Windows"、"macOS"）
     - IP地址（后端获取，例如："127.0.0.1"）
     - 位置（暂未实现，显示"暂未收集"）
     - 最后活跃时间（智能格式化，例如："刚刚"、"5分钟前"、"今天 14:30"）

### 测试 11：编辑联系信息
1. 在右侧栏访客详情中，找到"联系信息"区域
2. **编辑邮箱**：
   - 点击"邮箱"右侧的"+ Add"或"编辑"按钮
   - 弹出编辑弹窗（输入框 + "保存"和"取消"按钮）
   - 输入邮箱地址（例如：`visitor@example.com`）
   - 点击"保存"按钮
   - **预期结果**：
     - 编辑弹窗关闭
     - 邮箱立即更新显示
     - 数据保存到后端（查看后端日志，应该看到 `PUT /conversations/:id/contact` 请求）
     - 刷新后数据还在
     - 如果保存失败，显示错误提示
3. **编辑电话**：
   - 点击"电话"右侧的"+ Add"或"编辑"按钮
   - 弹出编辑弹窗
   - 输入电话号码（例如：`13800138000`）
   - 点击"保存"按钮
   - **预期结果**：
     - 编辑弹窗关闭
     - 电话立即更新显示
     - 数据保存到后端
     - 刷新后数据还在
4. **编辑备注**：
   - 点击"备注"右侧的"+ Add"或"编辑"按钮
   - 弹出编辑弹窗（支持多行文本）
   - 输入备注内容（例如：`重要客户，需要重点关注`）
   - 点击"保存"按钮
   - **预期结果**：
     - 编辑弹窗关闭
     - 备注立即更新显示（支持换行显示）
     - 数据保存到后端
     - 刷新后数据还在
5. **取消编辑**：
   - 点击编辑按钮，弹出编辑弹窗
   - 修改内容（或不修改）
   - 点击"取消"按钮
   - **预期结果**：
     - 编辑弹窗关闭
     - 内容不更新（保持原值）
6. **清空联系信息**：
   - 点击编辑按钮，弹出编辑弹窗
   - 清空输入框内容
   - 点击"保存"按钮
   - **预期结果**：
     - 编辑弹窗关闭
     - 联系信息清空，显示"暂未填写"
     - 数据保存到后端（空值）
     - 刷新后数据还在（显示"暂未填写"）

### 测试 12：在线/离线状态显示
1. **访客在线时**：
   - 在访客端打开 `/chat` 页面
   - **预期结果**（客服端）：
     - 对话列表中显示绿色圆点（在线）
     - 右侧栏显示"● 在线"
     - 这是通过 WebSocket 实时更新的！
2. **访客离线时**：
   - 关闭访客端页面（或关闭浏览器标签页）
   - **预期结果**（客服端）：
     - 对话列表中绿色圆点消失（或变为灰色）
     - 右侧栏显示"● 离线"
     - 最后活跃时间更新
     - 这是通过 WebSocket 实时更新的！

### 测试 13：刷新访客详情
1. 在右侧栏访客详情顶部，找到刷新按钮（圆形箭头图标）
2. 点击刷新按钮
3. **预期结果**：
   - 访客详情重新加载
   - 显示最新的访客信息（包括联系信息、技术信息、最后活跃时间等）

### 测试 14：返回对话列表
1. 在工作台左侧对话列表中，点击其他对话
2. **预期结果**：
   - 对话切换，中间栏和右侧栏自动更新
   - WebSocket 连接自动切换
   - 无需跳转页面，所有内容在同一页面更新

### 测试 15：退出登录
1. 在工作台顶部，找到"退出"按钮
2. 点击"退出"按钮
3. **预期结果**：
   - localStorage 中的 `agent_user_id`、`agent_username`、`agent_role` 被清除
   - 自动跳转到登录页面 (`/`)

4. **验证登录状态**：
   - 尝试直接访问 `/agent/dashboard`
   - **预期结果**：自动跳转到登录页面（因为未登录）

### 测试 16：登录状态检查
1. **清除 localStorage**（在浏览器控制台执行）：
   ```javascript
   localStorage.clear()
   ```
2. 尝试直接访问 `/agent/dashboard`
3. **预期结果**：
   - 自动跳转到登录页面（因为未登录）

---

## 六、调试技巧

### 1. 打开浏览器开发者工具
按 `F12` 打开开发者工具

### 2. 查看控制台（Console）
- 如果有红色错误，说明代码有问题
- 如果有 `console.error` 输出，说明后端请求失败
- 查看 WebSocket 连接状态：
  - `✅ WebSocket 连接成功: 对话ID=X` → 连接成功
  - `❌ WebSocket 连接关闭: 对话ID=X` → 连接断开
  - `WebSocket 连接错误: {}` → 连接失败（可能是后端未启动）

### 3. 查看网络请求（Network）
- 点击"发送"后，查看是否有 `POST /messages` 请求
- 查看 WebSocket 连接：找到 `ws` 或 `wss` 类型的请求
- 查看请求状态：
  - `200` = 成功
  - `400` = 请求参数错误
  - `500` = 服务器错误
- 查看 WebSocket 消息：
  - 点击 WebSocket 连接，查看 "Messages" 标签
  - 应该看到 `new_message`、`messages_read`、`visitor_status_update` 等事件

### 4. 查看后端日志
在后端运行的终端窗口，查看日志输出：
- 如果看到 `✅ 客户端已连接: 对话ID=X, 总连接数=Y, 访客连接数=Z`，说明 WebSocket 连接成功
- 如果看到 `❌ 客户端已断开: 对话ID=X, 剩余访客连接数=Y`，说明 WebSocket 断开
- 如果看到 `✅ WebSocket 连接已建立: 对话ID=X, 是访客=true/false`，说明连接建立
- 如果看到 `更新访客在线状态失败: ...`，说明状态更新失败
- 如果有错误信息，说明后端处理有问题

## 七、常见问题

### 问题 1：后端启动失败
**错误**：`数据库连接失败`
**解决**：
- 检查 MySQL 是否启动
- 检查 `.env` 配置是否正确
- 检查数据库是否存在

### 问题 2：前端启动失败
**错误**：`npm install` 失败
**解决**：
- 检查 Node.js 版本（需要 18+）
- 删除 `node_modules` 文件夹，重新 `npm install`

### 问题 3：页面空白
**错误**：浏览器显示空白页
**解决**：
- 打开开发者工具（F12）查看错误
- 检查后端是否启动
- 检查前端是否启动在 3000 端口

### 问题 4：发送消息失败
**错误**：点击发送没反应
**解决**：
- 打开浏览器控制台（F12）查看错误
- 检查后端是否启动在 8080 端口
- 检查 `frontend/lib/config.ts` 中的 API 地址是否正确

### 问题 5：WebSocket 连接失败
**错误**：`WebSocket 连接错误: {}`
**解决**：
- 检查后端是否启动
- 检查后端是否监听 8080 端口
- 检查浏览器控制台错误信息
- 查看后端日志，确认 WebSocket 服务是否启动

### 问题 6：消息不实时推送
**错误**：发送消息后，对方看不到
**解决**：
- 检查 WebSocket 连接状态（查看浏览器控制台）
- 检查后端日志，确认 WebSocket 是否正常广播
- 检查后端是否正常处理 WebSocket 消息
- 确认双方都建立了 WebSocket 连接

### 问题 7：已读状态不同步
**错误**：已读状态不更新
**解决**：
- 检查 WebSocket 连接状态
- 检查后端是否正常推送 `messages_read` 事件
- 检查前端是否正常处理 `messages_read` 事件
- 查看浏览器控制台和后端日志

### 问题 8：在线状态不更新
**错误**：在线状态不实时更新
**解决**：
- 检查 WebSocket 连接状态
- 检查后端是否正常推送 `visitor_status_update` 事件
- 检查前端是否正常处理 `visitor_status_update` 事件
- 查看浏览器控制台和后端日志
- 确认访客端 WebSocket 连接是否正常（`is_visitor=true`）

### 问题 9：对话列表不显示
**错误**：对话列表为空
**解决**：
- 确认是否有访客发送过消息
- 检查后端是否正常返回对话列表
- 查看浏览器控制台错误信息
- 检查后端日志，确认数据库查询是否正常

### 问题 10：搜索功能不工作
**错误**：搜索无结果
**解决**：
- 检查搜索关键词是否正确
- 检查后端搜索接口是否正常
- 查看浏览器控制台错误信息
- 检查后端日志，确认搜索查询是否正常

## 八、完整测试检查清单

完成以下测试后，打勾：

### 一、基础功能测试

#### 访客端基础功能：
- [ ] 后端启动成功（显示监听 :8080 和 WebSocket 服务）
- [ ] 前端启动成功（显示 Ready）
- [ ] 访问 `/chat` 页面正常显示
- [ ] 自动生成/获取访客ID
- [ ] 自动初始化对话（获取对话ID）
- [ ] 显示系统消息（如 "Visitor opened the page [URL]"）
- [ ] WebSocket 连接自动建立（查看浏览器控制台）
- [ ] 发送第一条消息成功
- [ ] 消息显示在右侧（蓝色气泡）
- [ ] 显示已读状态（单对勾）
- [ ] 发送后自动滚动到底部
- [ ] 输入框清空，可以继续输入
- [ ] 时间显示正确（今天的只显示时间，更早的显示日期+时间）
- [ ] 可以连续发送多条消息
- [ ] 输入框为空时，发送按钮禁用
- [ ] 刷新页面后消息还在
- [ ] 访客信息自动收集（网站、来源、浏览器、操作系统、语言、IP地址）

#### 客服端基础功能：
- [ ] 访问 `/` 显示登录页面
- [ ] 使用 admin/admin123 可以成功登录
- [ ] 登录后跳转到 `/agent/dashboard`（客服工作台）
- [ ] 四栏布局正常显示（导航栏、对话列表、聊天内容、访客详情）
- [ ] 对话列表显示所有未关闭的对话
- [ ] 对话列表显示在线/离线状态图标（绿色圆点 = 在线）
- [ ] 对话列表显示最后一条消息预览
- [ ] 对话列表显示未读消息数量（蓝色徽标）
- [ ] 对话列表显示已读/未读状态图标（单/双对勾）
- [ ] 选择对话后，中间栏和右侧栏自动更新
- [ ] WebSocket 连接自动切换
- [ ] 客服消息显示在右侧（蓝色气泡）
- [ ] 访客消息显示在左侧（白色气泡）
- [ ] 系统消息居中显示（灰色背景）
- [ ] 客服可以发送消息
- [ ] 退出登录功能正常
- [ ] 未登录访问客服页面会跳转到登录页

### 二、实时通信测试

#### WebSocket 实时推送：
- [ ] 访客发送消息后，客服端实时收到（无需刷新）
- [ ] 客服发送消息后，访客端实时收到（无需刷新）
- [ ] 消息通过 WebSocket 实时推送
- [ ] WebSocket 连接自动重连（断开后自动重连）

#### 已读状态同步：
- [ ] 客服查看访客消息后，访客端实时更新已读状态（单对勾 → 双对勾）
- [ ] 访客查看客服消息后，客服端实时更新已读状态（单对勾 → 双对勾）
- [ ] 已读状态通过 WebSocket 实时推送
- [ ] 对勾颜色正确（已读 = 蓝色，未读 = 灰色）

#### 在线状态更新：
- [ ] 访客打开页面后，客服端实时显示在线状态（绿色圆点）
- [ ] 访客关闭页面后，客服端实时显示离线状态（灰色圆点或消失）
- [ ] 在线状态通过 WebSocket 实时推送
- [ ] 最后活跃时间实时更新

### 三、搜索功能测试

#### 对话搜索：
- [ ] 搜索框UI正常显示
- [ ] 输入搜索关键词后，实时搜索（300ms 防抖）
- [ ] 搜索结果正确显示（匹配的对话列表）
- [ ] 搜索结果高亮显示（关键词黄色背景高亮）
- [ ] 点击搜索结果，自动定位到匹配消息
- [ ] 历史消息居中显示，最后一条滚动到底部
- [ ] 清除搜索后，显示所有对话
- [ ] 支持搜索消息内容、对话ID、访客ID

### 四、访客信息测试

#### 访客信息收集：
- [ ] 访客端自动收集网站（当前页面URL）
- [ ] 访客端自动收集来源（referrer）
- [ ] 访客端自动收集浏览器信息
- [ ] 访客端自动收集操作系统信息
- [ ] 访客端自动收集语言信息
- [ ] 后端自动获取IP地址
- [ ] 客服端显示所有访客信息

#### 联系信息编辑：
- [ ] 编辑邮箱功能正常（新增、修改、清空）
- [ ] 编辑电话功能正常（新增、修改、清空）
- [ ] 编辑备注功能正常（新增、修改、清空）
- [ ] 联系信息保存到后端
- [ ] 刷新后联系信息还在
- [ ] 编辑弹窗正常显示和关闭

### 五、界面交互测试

#### 滚动行为：
- [ ] 消息列表内部滚动正常（不会滚动整个页面）
- [ ] 对话列表内部滚动正常（不会滚动整个页面）
- [ ] 访客详情内部滚动正常（不会滚动整个页面）
- [ ] 发送新消息后自动滚动到底部
- [ ] 长消息历史正常滚动

#### 响应式布局：
- [ ] 四栏布局正常显示
- [ ] 各栏宽度正确（导航栏 64px，对话列表 320px，访客详情 320px，聊天内容自适应）
- [ ] 各栏高度正确（顶部栏 h-16，内容区域自适应）
- [ ] 选中对话高亮显示（蓝色背景）

### 六、错误处理测试

#### 网络错误：
- [ ] 后端停止后，发送消息显示错误提示
- [ ] WebSocket 连接断开后，显示连接关闭提示
- [ ] 网络恢复后，WebSocket 自动重连
- [ ] 错误提示清晰明确

#### 数据验证：
- [ ] 输入框为空时，发送按钮禁用
- [ ] 输入框有内容时，发送按钮启用
- [ ] 编辑联系信息时，输入验证正常
- [ ] 清空联系信息时，数据正确保存

### 七、性能测试

#### 加载性能：
- [ ] 页面加载速度正常（< 2秒）
- [ ] 对话列表加载速度正常（< 1秒）
- [ ] 消息列表加载速度正常（< 1秒）
- [ ] 访客详情加载速度正常（< 1秒）

#### 实时性能：
- [ ] 消息实时推送延迟 < 100ms
- [ ] 已读状态同步延迟 < 100ms
- [ ] 在线状态更新延迟 < 100ms
- [ ] WebSocket 连接稳定（不断开）

### 八、兼容性测试

#### 浏览器兼容：
- [ ] Chrome 浏览器正常
- [ ] Edge 浏览器正常
- [ ] Firefox 浏览器正常
- [ ] Safari 浏览器正常（如果可用）

#### 数据持久化：
- [ ] 刷新页面后，消息还在
- [ ] 刷新页面后，访客ID不变
- [ ] 刷新页面后，登录状态保持
- [ ] 联系信息编辑后，刷新后数据还在

---

## 九、快速测试流程（核心功能验证）

> 💡 如果你时间有限，可以按照以下流程快速验证核心功能是否正常

### 快速测试步骤：

1. **启动系统**（5分钟）
   - [ ] 启动后端：`cd backend && go run main.go`
   - [ ] 启动前端：`cd frontend && npm run dev`
   - [ ] 访问 `http://localhost:3000`

2. **访客端测试**（5分钟）
   - [ ] 访问 `http://localhost:3000/chat`
   - [ ] 发送消息："你好，这是测试消息"
   - [ ] 确认消息显示在右侧（蓝色气泡）
   - [ ] 确认 WebSocket 连接建立（查看浏览器控制台）

3. **客服端测试**（5分钟）
   - [ ] 访问 `http://localhost:3000/`，使用 admin/admin123 登录
   - [ ] 确认进入客服工作台（四栏布局）
   - [ ] 确认对话列表显示刚才的对话
   - [ ] 点击对话，确认消息显示在中间栏
   - [ ] 发送消息："您好，我是客服"
   - [ ] 确认消息显示在右侧（蓝色气泡）

4. **实时通信测试**（5分钟）
   - [ ] 打开两个浏览器标签页（访客端和客服端）
   - [ ] 在访客端发送消息："测试实时推送"
   - [ ] 确认客服端实时收到消息（无需刷新）
   - [ ] 在客服端发送消息："测试实时推送回复"
   - [ ] 确认访客端实时收到消息（无需刷新）

5. **已读状态测试**（3分钟）
   - [ ] 在客服端查看访客消息
   - [ ] 确认访客端已读状态从单对勾变为双对勾（无需刷新）

6. **在线状态测试**（3分钟）
   - [ ] 确认客服端对话列表显示绿色圆点（在线）
   - [ ] 关闭访客端页面
   - [ ] 确认客服端绿色圆点消失（或变为灰色）

7. **搜索功能测试**（2分钟）
   - [ ] 在客服端搜索框输入关键词
   - [ ] 确认搜索结果高亮显示
   - [ ] 点击搜索结果，确认自动定位到匹配消息

8. **联系信息编辑测试**（3分钟）
   - [ ] 在客服端右侧栏，点击"邮箱"右侧的"编辑"按钮
   - [ ] 输入邮箱地址，点击"保存"
   - [ ] 确认邮箱立即更新显示

**如果以上测试都通过，说明核心功能正常！** ✅

---

## 十、高级测试场景

### 场景 1：多个访客同时聊天
1. **打开多个浏览器**（或使用隐私/无痕模式）
   - 浏览器1：访客A (`http://localhost:3000/chat`)
   - 浏览器2：访客B (`http://localhost:3000/chat`)
   - 浏览器3：客服端 (`http://localhost:3000/agent/dashboard`)
2. **测试流程**：
   - 访客A 发送消息："我是访客A"
   - 访客B 发送消息："我是访客B"
   - 客服端应该看到两个不同的对话
   - 客服可以选择不同的对话进行回复
   - 每个访客只能看到自己的对话

### 场景 2：并发消息测试
1. **打开两个浏览器标签页**（访客端和客服端）
2. **快速发送多条消息**：
   - 访客端连续发送 10 条消息
   - 客服端连续发送 10 条消息
3. **预期结果**：
   - 所有消息都实时推送
   - 消息顺序正确
   - 已读状态正确同步
   - 无消息丢失
   - 无重复消息

### 场景 3：长时间连接测试
1. **打开访客端和客服端**
2. **保持连接 30 分钟**
3. **预期结果**：
   - WebSocket 连接保持稳定（不断开）
   - 消息正常推送
   - 已读状态正常同步
   - 在线状态正常更新
   - 无内存泄漏

### 场景 4：网络中断恢复测试
1. **打开访客端和客服端**
2. **断开网络**（关闭 WiFi 或拔掉网线）
3. **等待 10 秒**
4. **恢复网络**
5. **预期结果**：
   - WebSocket 连接自动重连
   - 消息正常推送
   - 已读状态正常同步
   - 在线状态正常更新

### 场景 5：大量消息历史测试
1. **创建一个对话**
2. **发送 100+ 条消息**
3. **预期结果**：
   - 消息列表正常加载
   - 滚动性能正常（不卡顿）
   - 消息显示正确
   - 搜索功能正常（可以搜索历史消息）
   - 关键词高亮正常

### 场景 6：搜索性能测试
1. **创建多个对话**（10+ 个对话）
2. **每个对话发送多条消息**（10+ 条消息）
3. **测试搜索功能**：
   - 搜索消息内容
   - 搜索对话ID
   - 搜索访客ID
4. **预期结果**：
   - 搜索速度正常（< 500ms）
   - 搜索结果正确
   - 关键词高亮正常
   - 点击搜索结果自动定位正常

### 场景 7：联系信息编辑并发测试
1. **打开多个客服端**（使用不同的浏览器）
2. **同时编辑同一个访客的联系信息**：
   - 客服A 编辑邮箱
   - 客服B 编辑电话
3. **预期结果**：
   - 数据正确保存
   - 无数据冲突
   - 刷新后数据正确

### 场景 8：在线状态多访客测试
1. **打开多个访客端**（3+ 个访客）
2. **测试在线状态**：
   - 访客A 在线
   - 访客B 在线
   - 访客C 离线
3. **预期结果**（客服端）：
   - 对话列表正确显示在线/离线状态
   - 在线状态实时更新
   - 最后活跃时间正确更新

---

## 十一、测试结果记录

### 测试日期：__________

### 测试人员：__________

### 测试环境：
- 后端版本：__________
- 前端版本：__________
- 数据库版本：__________
- 浏览器版本：__________

### 测试结果：
- [ ] 所有测试通过
- [ ] 部分测试通过（请列出未通过的测试）
- [ ] 测试失败（请列出失败的测试）

### 问题记录：
1. __________
2. __________
3. __________

### 备注：
__________

---

**测试完成后，你就知道整个系统是否正常工作了！** 🎉

**如果所有测试都通过，恭喜你！系统已经可以正常使用了！** ✅