sj-miniprogram/online-service/docs/implementation_plan.md

在线客服系统实施计划书

1. 系统架构方案

1.1 通讯协议选择

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

1.2 消息协议定义 (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 进页面的消息数组中。