# 在线客服系统实施计划书

## 1. 系统架构方案

### 1.1 通讯协议选择
*   **技术栈**: 采用 **WebSocket** 作为核心通讯协议，后端推荐使用 SpringBoot + Netty 或 Spring WebSocket。
*   **连接管理**: 
    *   **心跳检测**: 客户端每 30 秒发送心跳包，确保连接存活。
    *   **断线重连**: 客户端检测到连接断开时，自动发起指数退避算法的重连请求。
    *   **身份鉴权**: 在建立连接的初次握手（Handshake）阶段通过 URL 参数或 Header 传递 JWT Token。

### 1.2 消息协议定义 (JSON 结构)
所有消息采用统一的 JSON 格式传输示例：
```json
{
  "msgId": "uuid-12345",
  "fromUser": "guest_001",    // 发送者ID
  "toUser": "waiter_001",      // 接收者ID
  "clientType": "mini_app",   // 来源：mini_app (小程序), pc_web (平台)
  "msgType": "job_card",      // 消息类型：text, order_card, job_card, assess_card
  "content": "",              // 文本内容
  "payload": {                // 卡片扩展数据
    "id": "j001",
    "title": "审计员",
    "salary": "13K-23K",
    "company": "华财仁合"
  }
}
```

### 1.3 业务逻辑流转
1.  **客户接入**: 小程序用户发起咨询，系统根据“坐席配置”中的负责模块和在线状态，采用**轮询**或**最少连接数**算法分配给在线客服。
2.  **消息存储**: 所有实时消息通过 Redis 进行中转（高性能消费），并异步持久化到 MySQL `chat_history` 表。
3.  **状态同步**: 坐席的“在线/忙碌/下线”状态实时同步，用户端显示“客服正在输入中...”。

---

## 2. 项目目录结构说明

文件夹 `online-service` 下包含以下内容：
1.  **`docs/`**: 存放架构规划与对接文档（即本文件）。
2.  **`pc-web-preview/`**: **PC 端管理后台预览项目**。基于 Vite + Vue3 + Element Plus 搭建，包含完整的坐席配置与聊天工作台页面。
3.  **`mini-app-ref/`**: **小程序端参考代码**。包含聊天 UI 组件 (`chat.vue`) 和 WebSocket 通讯封装 (`socket.js`)。

> [!TIP]
> 原 `pc-frontend` 目录已作为核心视图组件移动至 `pc-web-preview/src/views` 中，为了保持项目整洁已将其删除。

---

## 3. 运行说明 (HBuilderX)

要在 HBuilderX 中查看 PC 端后台预览效果：
1.  **导入项目**: 点击 `文件` -> `导入` -> `从本地目录导入`，选择 `online-service/pc-web-preview`。
2.  **启动开发服务器**: 
    - 打开项目下的 `package.json`。
    - 将鼠标悬停在 `"dev": "vite"` 脚本上方，点击出现的绿色运行图标。
    - 或者在项目上右键选择“使用命令行窗口打开”，输入 `npm run dev`。
3.  **浏览器访问**: 服务器启动后，在浏览器访问 `http://localhost:3000` 即可查看。

---

## 4. 后台对接说明 (集成至若依)

如果您需要将预览页面迁移到正式的 **RuoYi Vue3** 项目中，请参考以下步骤：

### 4.1 视图文件迁移
将 `pc-web-preview/src/views/` 下的两个文件拷贝至若依项目的对应位置：
- `ChatWorkbench.vue` -> `src/views/customer/chat/index.vue`
- `SeatConfig.vue` -> `src/views/customer/config/index.vue`

### 4.2 路由与权限配置
1.  在若依后台管理系统中，进入 `系统管理` -> `菜单管理`。
2.  新建菜单“在线客服”，组件路径填写 `customer/chat/index`。
3.  新建菜单“坐席配置”，组件路径填写 `customer/config/index`。

### 4.3 接口逻辑替换
- 预览代码中的 `sessionList`、`messageList` 等均为静态 `ref` 数据。
- 对接时，需在 `onMounted` 钩子中调用业务接口获取真实历史记录。
- 发送逻辑 `handleSend` 需增加对 `WebSocket` 发送方法的调用。

---

## 5. 小程序对接说明

1.  **UI 接入**: 将 `mini-app-ref/chat.vue` 的模板架构引入您的小程序咨询页面。
2.  **通讯链路**: 
    - 在 `App.vue` 或 聊天页面初始化时，调用 `socket.js` 的 `connect(token)` 方法。
    - 使用 `ChatSocket.onMessage(data => { ... })` 监听来自后台的消息，并实时将其 `push` 进页面的消息数组中。