Home Explore Help
Sign In
yonge
/
CRMEB
1
0
Fork 0
Files Issues 0 Pull Requests 0 Wiki
Tree: e9954ecc2f
Branches Tags
CRMEB
/
help
/
dev-docs
/
phpapi
/
客服系统开发文档.md

客服系统开发文档.md 16 KB
History Raw

客服系统开发文档

1. 文档概述

1.1 文档目的

本文档旨在详细说明CRMEB系统中客服系统模块的设计架构、核心功能、代码实现及开发规范，为系统开发人员提供完整的开发参考。

1.2 适用范围

本文档适用于CRMEB系统开发人员、维护人员及二次开发人员，用于指导客服系统模块的开发、扩展和维护工作。

1.3 术语定义

术语 解释
客服系统 用于商家与用户进行实时沟通的系统
WebSocket 一种在单个TCP连接上进行全双工通信的协议
会话转接 将当前聊天会话转交给其他客服处理
客服话术 客服常用的回复模板
全局话术 所有客服均可使用的话术
个人话术 仅当前客服可使用的话术
游客模式 未登录用户发起聊天的模式

2. 核心功能模块

2.1 客服账号管理

  • 客服登录：支持账号密码登录和微信扫码登录
  • 权限控制：不同角色客服拥有不同权限
  • 在线状态管理：显示客服在线/离线状态
  • 客服资料管理：修改客服基本信息

2.2 客服聊天功能

  • 实时通信：基于WebSocket的实时聊天
  • 消息类型：支持文本、图片等多种消息类型
  • 聊天记录：聊天记录持久化存储，支持历史记录查询
  • 用户识别：支持游客和注册用户两种聊天模式
  • 消息提醒：新消息实时提醒
  • 消息已读状态：显示消息已读/未读状态

2.3 用户管理

  • 用户信息：查看用户详细信息
  • 用户标签：为用户添加/移除标签
  • 用户分组：将用户分配到不同分组
  • 聊天历史：查看用户历史聊天记录
  • 行为记录：查看用户浏览、购买等行为记录

2.4 订单处理

  • 订单列表：查看用户订单列表
  • 订单发货：处理订单发货
  • 订单退款：处理订单退款申请
  • 订单改价：修改订单价格
  • 订单备注：添加订单备注

2.5 商品相关

  • 商品详情：查看商品详细信息
  • 购买记录：查看用户购买记录
  • 浏览记录：查看用户浏览记录
  • 热销商品：查看热销商品列表

2.6 客服话术管理

  • 话术分类：管理话术分类
  • 话术添加：添加新的话术
  • 话术编辑：修改已有话术
  • 话术删除：删除无用话术
  • 全局话术：所有客服均可使用的话术
  • 个人话术：仅当前客服可使用的话术

2.7 客服转接

  • 会话转接：支持客服之间的会话转接
  • 转接历史：查看会话转接历史
  • 实时通知：转接时实时通知相关客服
  • 聊天记录保留：转接时保留完整聊天记录

3. 代码结构与设计

3.1 架构设计

客服系统采用前后端分离架构，后端使用ThinkPHP框架，前端使用Vue.js，基于WebSocket实现实时通信：

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   前端应用       │────▶│   WebSocket服务器  │────▶│   后端API服务    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                        │
                                        ▼
                                ┌─────────────────┐
                                │   数据库          │
                                └─────────────────┘

3.2 核心文件结构

3.2.1 后端目录

客服API：/crmeb/app/kefuapi/

  • controller/ - 客服API控制器
  • middleware/ - 客服API中间件
  • route/ - 客服API路由
  • validate/ - 客服API验证器

3.2.2 模型层

服务模型：/crmeb/app/model/service/

  • StoreService.php - 客服信息模型
  • StoreServiceRecord.php - 客服聊天用户记录模型
  • StoreServiceLog.php - 客服聊天记录模型
  • StoreServiceSpeechcraft.php - 客服话术模型

3.2.3 服务层

客服服务：/crmeb/app/services/kefu/

  • KefuLoginServices.php - 客服登录服务
  • KefuUserServices.php - 客服用户服务
  • KefuServiceServices.php - 客服服务管理
  • KefuSpeechcraftServices.php - 客服话术服务

3.2.4 前端目录

客服前端API：/template/admin/src/api/kefu.js

  • 包含客服系统前端调用的所有API接口

3.2.5 WebSocket服务

WebSocket实现：基于Workerman框架实现

  • 提供实时聊天功能
  • 处理消息推送和接收

4. 数据库设计

4.1 客服信息表（store_service）

字段名 数据类型 描述
id int(10) unsigned 客服ID
uid int(10) 关联用户ID
nick_name varchar(20) 客服昵称
avatar varchar(255) 客服头像
phone varchar(20) 客服手机号
password varchar(60) 客服密码
salt varchar(10) 密码盐
status tinyint(1) 状态（0-禁用，1-启用）
is_online tinyint(1) 在线状态（0-离线，1-在线）
add_time int(10) 添加时间

4.2 客服聊天用户记录表（store_service_record）

字段名 数据类型 描述
id int(10) unsigned 记录ID
uid int(10) 用户ID
service_id int(10) 客服ID
last_msg varchar(255) 最后一条消息内容
last_time int(10) 最后消息时间
is_visitor tinyint(1) 是否游客（0-否，1-是）
visitor_id varchar(50) 游客ID
status tinyint(1) 状态（0-结束，1-进行中）
add_time int(10) 添加时间

4.3 客服聊天记录表（store_service_log）

字段名 数据类型 描述
id int(10) unsigned 记录ID
from_id int(10) 发送者ID
to_id int(10) 接收者ID
service_id int(10) 客服ID
message text 消息内容
type tinyint(1) 消息类型（0-文本，1-图片）
is_read tinyint(1) 是否已读（0-未读，1-已读）
is_visitor tinyint(1) 是否游客（0-否，1-是）
visitor_id varchar(50) 游客ID
add_time int(10) 添加时间

4.4 客服话术表（store_service_speechcraft）

字段名 数据类型 描述
id int(10) unsigned 话术ID
uid int(10) 客服ID（0-全局话术）
cate_id int(10) 分类ID
title varchar(100) 话术标题
content text 话术内容
sort int(10) 排序
status tinyint(1) 状态（0-禁用，1-启用）
add_time int(10) 添加时间

5. API接口说明

5.1 客服登录相关

5.1.1 客服登录

  • 请求URL：/kefuapi/login
  • 请求方法：POST
  • 请求参数：
    • username：用户名
    • password：密码
  • 返回结果：登录状态、token等

5.1.2 微信扫码登录

  • 请求URL：/kefuapi/key
  • 请求方法：GET
  • 返回结果：扫码登录key

5.1.3 检测扫码情况

  • 请求URL：/kefuapi/scan/:key
  • 请求方法：GET
  • 返回结果：扫码状态

5.2 聊天相关

5.2.1 获取聊天用户列表

  • 请求URL：/kefuapi/user/record
  • 请求方法：GET
  • 请求参数：
    • page：页码
    • limit：每页数量
    • status：状态
  • 返回结果：聊天用户列表

5.2.2 获取聊天记录

  • 请求URL：/kefuapi/service/list
  • 请求方法：GET
  • 请求参数：
    • uid：用户ID
    • visitor_id：游客ID
    • page：页码
    • limit：每页数量
  • 返回结果：聊天记录列表

5.2.3 客服转接

  • 请求URL：/kefuapi/service/transfer
  • 请求方法：POST
  • 请求参数：
    • uid：用户ID
    • visitor_id：游客ID
    • to_service_id：转接目标客服ID
  • 返回结果：转接结果

5.3 用户管理相关

5.3.1 获取用户详细信息

  • 请求URL：/kefuapi/user/info/:uid
  • 请求方法：GET
  • 返回结果：用户详细信息

5.3.2 获取用户标签

  • 请求URL：/kefuapi/user/label/:uid
  • 请求方法：GET
  • 返回结果：用户标签列表

5.3.3 设置用户标签

  • 请求URL：/kefuapi/user/label/:uid
  • 请求方法：PUT
  • 请求参数：
    • label_ids：标签ID数组
  • 返回结果：操作结果

5.4 订单处理相关

5.4.1 获取用户订单列表

  • 请求URL：/kefuapi/order/list/:uid
  • 请求方法：GET
  • 请求参数：
    • page：页码
    • limit：每页数量
    • status：订单状态
  • 返回结果：用户订单列表

5.4.2 订单发货

  • 请求URL：/kefuapi/order/delivery/:id
  • 请求方法：POST
  • 请求参数：
    • express_id：快递公司ID
    • express_no：快递单号
  • 返回结果：操作结果

5.4.3 订单退款

  • 请求URL：/kefuapi/order/refund
  • 请求方法：POST
  • 请求参数：
    • order_id：订单ID
    • refund_money：退款金额
    • refund_reason：退款原因
  • 返回结果：操作结果

5.5 话术管理相关

5.5.1 获取话术列表

  • 请求URL：/kefuapi/service/speechcraft
  • 请求方法：GET
  • 请求参数：
    • cate_id：分类ID
    • type：类型（0-全局，1-个人）
  • 返回结果：话术列表

5.5.2 添加话术

  • 请求URL：/kefuapi/service/speechcraft
  • 请求方法：POST
  • 请求参数：
    • cate_id：分类ID
    • title：话术标题
    • content：话术内容
    • type：类型（0-全局，1-个人）
  • 返回结果：操作结果

5. 开发规范与流程

5.1 代码规范

  1. 命名规范：

    • 类名采用大驼峰命名法，如 KefuLoginServices
    • 方法名采用小驼峰命名法，如 getUserList
    • 变量名采用小驼峰命名法，如 chatMessage
    • 常量名采用全大写，下划线分隔，如 KEFU_STATUS_ONLINE

  2. 代码结构：

    • 严格遵循分层架构，禁止跨层调用
    • 每个方法职责单一，代码行数控制在50行以内
    • 适当添加注释，说明方法功能、参数含义和返回值
    • 所有聊天消息必须记录日志，便于追溯

  3. WebSocket规范：

    • WebSocket连接必须进行身份验证
    • 消息格式必须统一，便于前后端解析
    • 必须处理连接断开、重连等异常情况
    • 消息发送必须实现重试机制

5.2 开发流程

  1. 需求分析：明确客服系统的功能需求和业务逻辑
  2. 设计阶段：设计数据结构、API接口和业务流程
  3. 编码实现：
    • 实现后端API接口
    • 实现WebSocket服务
    • 实现前端页面和交互
  4. 单元测试：编写单元测试，确保功能正确性
  5. 集成测试：进行模块集成测试，测试客服系统与其他模块的交互
  6. 性能测试：对WebSocket连接、消息推送等进行性能测试
  7. 安全性测试：测试登录认证、权限控制等安全性功能
  8. 代码审查：提交代码审查，确保代码质量
  9. 部署上线：部署到生产环境

6. 常见问题与解决方案

6.1 WebSocket连接问题

问题：WebSocket连接失败或频繁断开 解决方案：

  1. 检查WebSocket服务器是否正常运行
  2. 检查防火墙设置，确保WebSocket端口开放
  3. 实现连接心跳机制，保持长连接
  4. 实现自动重连机制，处理连接断开情况

6.2 消息推送延迟

问题：消息推送延迟严重 解决方案：

  1. 优化WebSocket服务器性能，增加并发处理能力
  2. 使用消息队列处理消息推送，避免阻塞
  3. 优化网络环境，减少网络延迟
  4. 实现消息优先级，确保重要消息优先推送

6.3 聊天记录丢失

问题：聊天记录丢失或不完整 解决方案：

  1. 确保聊天记录及时持久化存储
  2. 使用事务处理，确保数据一致性
  3. 实现聊天记录备份机制
  4. 定期检查聊天记录完整性

6.4 客服转接问题

问题：客服转接失败或聊天记录丢失 解决方案：

  1. 确保转接逻辑正确，保留完整聊天记录
  2. 实现转接状态通知，确保相关客服收到通知
  3. 测试各种转接场景，确保转接功能稳定

7. 扩展与定制

7.1 添加新的消息类型

  1. 数据库修改：在store_service_log表中添加新的消息类型枚举
  2. 后端修改：
    • 在消息处理逻辑中添加新消息类型的处理
    • 更新API接口，支持新消息类型
  3. 前端修改：
    • 添加新消息类型的渲染组件
    • 更新消息发送组件，支持新消息类型

7.2 扩展客服权限

  1. 数据库修改：在store_service表中添加权限字段
  2. 后端修改：
    • 在权限验证中间件中添加新权限的验证
    • 更新API接口的权限控制
  3. 前端修改：
    • 根据权限动态显示菜单和功能按钮
    • 添加权限管理页面

7.3 集成第三方客服系统

  1. 设计适配层：设计与第三方客服系统的适配层
  2. 实现API对接：实现与第三方客服系统的API对接
  3. 数据同步：实现客服数据、聊天记录等数据的同步
  4. 前端集成：在前端页面中集成第三方客服系统的功能

8. 文档更新记录

版本 更新日期 更新内容 更新人
1.0 2026-01-19 初始版本，包含客服账号管理、客服聊天功能、用户管理、订单处理、商品相关、客服话术管理、客服转接等核心功能 AI Assistant

9. 附录

9.1 核心类关系图

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   前端应用       │────▶│   WebSocket服务器  │────▶│   后端API服务    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                        │
                                        ▼
                                ┌─────────────────┐
                                │   数据库          │
                                └─────────────────┘

9.2 聊天流程图

聊天流程：
1. 用户访问网站，发起聊天请求
2. 系统分配客服（或用户选择客服）
3. 建立WebSocket连接
4. 用户和客服开始聊天
   a. 发送消息
   b. 接收消息
   c. 消息已读状态更新
5. 聊天结束，保存聊天记录
6. 关闭WebSocket连接

9.3 客服转接流程图

客服转接流程：
1. 当前客服发起转接请求
2. 系统验证转接权限
3. 选择目标客服
4. 发送转接请求给目标客服
5. 目标客服接受转接
6. 系统更新会话归属
7. 通知当前客服和目标客服
8. 转接完成，保留聊天记录

9.4 客服权限列表

权限名称 描述
kefu_login 客服登录权限
kefu_chat 聊天功能权限
kefu_user 用户管理权限
kefu_order 订单处理权限
kefu_product 商品查看权限
kefu_speechcraft 话术管理权限
kefu_transfer 客服转接权限

提示：该文档由AI生成，仅供参考。