人工客服系统 技术开发文档
更新内容
- 增加允许用户查看历史对话设置项,推荐开启
- 增加允许用户删除历史对话设置项
- UI美化
更新内容
- 深度适配子比主题,完美挂钩右侧悬浮按钮
- 客户视角

首次点击效果,注意:客户首次点击开始对话时,会自动刷新页面,需要再次点击悬浮图标才会打开聊天模态框

- 客服视角

悬浮按钮点击效果

- 客户视角
- 悬浮状态下实时接收消息,并伴随数字计数自动更新与声音提醒,允许客服人员后台挂机。客户视角效果也一样
1
系统架构设计
多层架构模式
表示层 (Presentation)
- 模态框交互界面
- 实时消息展示
- 响应式CSS设计
- WebSocket模拟
业务逻辑层 (Business Logic)
- 对话状态机管理
- 客服分配算法
- 消息队列处理
- 通知调度系统
数据访问层 (Data Access)
- MySQL关系型存储
- 文件系统管理
- 缓存策略实现
- 事务处理机制
核心技术特性
🔄 实时通信机制
基于AJAX长轮询模拟WebSocket,实现伪实时消息推送,采用消息ID增量同步策略避免重复拉取
⚡ 状态机管理
定义waiting/active/ended三种对话状态,通过状态转移函数控制业务流程流转
🔒 双重验证机制
基于WP Nonce的请求验证 + 用户权限验证 + 业务逻辑验证的三层安全防护
2
数据库结构详解
📊 表关系拓扑图
│ ssupport_chats │◄──┤ssupport_messages│◄──┐│ssupport_agents │
└─────────────────┘ └─────────────────┘ │└─────────────────┘
│ │ │ │
▼ ▼ │ ▼
┌─────────────────┐ ┌─────────────────┐ │┌─────────────────┐
│ssupport_schedules│ │ ssupport_notif │ └┤ (User Meta) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
核心表结构设计
| 表名 | 字段数 | 索引策略 | 数据规模 | 事务级别 |
|---|---|---|---|---|
| ssupport_chats | 14个字段 | 6个B+Tree索引 | ~10K-100K行 | RR隔离级别 |
| ssupport_messages | 9个字段 | 5个复合索引 | ~100K-1M行 | RC隔离级别 |
| ssupport_agents | 11个字段 | 唯一约束索引 | ~10-100行 | 轻量事务 |
📈 索引优化策略
-- 聊天表复合索引设计 CREATE INDEX idx_chat_status_time ON wp_ssupport_chats (status, last_message_at DESC); CREATE INDEX idx_user_status ON wp_ssupport_chats (user_id, status); CREATE INDEX idx_agent_status ON wp_ssupport_chats (agent_id, status); -- 消息表查询优化索引 CREATE INDEX idx_chat_created ON wp_ssupport_messages (chat_id, created_at DESC); CREATE INDEX idx_unread_notify ON wp_ssupport_messages (chat_id, sender_type, is_read); -- 覆盖索引减少回表 CREATE INDEX idx_agent_perf ON wp_ssupport_agents (is_online, active_chats, avg_rating DESC);
3
核心工作流程
①
用户发起对话流程
步骤1:身份验证
WP Nonce验证 → 用户会话检查 → 权限验证 → 防CSRF攻击
步骤2:对话创建
原子性INSERT操作 → 用户信息JSON序列化 → 初始状态设置
步骤3:消息初始化
系统欢迎消息 → 时间戳记录 → 触发器激活 → 钩子执行
步骤4:通知分发
多播通知机制 → 防重复发送 → 异步处理 → 失败重试
②
客服处理流程
状态检测
在线状态验证
并发对话限制
对话接管
原子性UPDATE
乐观锁控制
消息同步
增量拉取策略
消息状态同步
评价处理
加权平均计算
分布统计更新
③
实时通信流程
客户端轮询策略
- 初始全量加载:last_id = 0
- 增量同步:WHERE id > last_id
- 智能轮询间隔:3-5秒动态调整
- 防抖机制:防止重复请求
服务端推送逻辑
- 消息持久化:事务性写入
- 状态更新:last_message_at
- 未读标记:is_read字段管理
- 附件处理:文件系统存储
4
功能模块解析
智能客服分配
- 最少活跃对话优先策略
- 在线状态实时监测
- 最大并发数限制保护
- 故障转移机制
多通道通知系统
- 站内信即时通知
- SMTP邮件推送
- 通知记录持久化
- 智能重试策略
服务评价体系
- 五星评分机制
- 文字评价反馈
- 评分分布统计
- 绩效数据分析
多媒体支持
- 图片上传验证
- 文件类型过滤
- 大小限制控制
- 安全路径存储
🚀 高级功能特性
🛡️ 数据安全
SQL注入防护、XSS过滤、CSRF令牌、文件上传验证、会话安全机制
⚙️ 配置管理
动态设置系统、角色权限管理、邮件模板配置、业务规则引擎
📊 数据分析
对话统计报表、客服绩效评估、用户行为分析、服务质量监控
5
AJAX接口规范
接口调用规范
$.ajax({
url: admin_url(‘admin-ajax.php’),
type: ‘POST’,
data: {
action: ‘ssupport_xxx’, // 接口标识
param1: value1, // 业务参数
_wpnonce: wp_create_nonce() // 安全令牌
},
dataType: ‘json’
});
| 接口名称 | HTTP方法 | 请求参数 | 响应格式 | 业务说明 |
|---|---|---|---|---|
| ssupport_start_chat | POST | _wpnonce | JSON | 创建新对话会话 |
| ssupport_send_message | POST (multipart) | chat_id, message, image | JSON | 发送消息(支持图片) |
| ssupport_get_messages | GET | chat_id, last_id | JSON | 增量获取消息 |
| ssupport_take_chat | POST | chat_id | JSON | 客服接单处理 |
| ssupport_submit_rating | POST | chat_id, rating, feedback | JSON | 提交服务评价 |
📋 响应数据结构示例
成功响应
{
"success": true,
"data": {
"chat_id": 12345,
"status": "active",
"agent_id": 1,
"agent_name": "客服专员",
"message_id": 67890,
"timestamp": "2024-01-15 14:30:25"
}
}
失败响应
{
"success": false,
"data": "权限验证失败",
"code": "ERR_PERMISSION_DENIED",
"timestamp": "2024-01-15 14:30:25"
}
6
钩子系统分析
🪝 钩子类型分类
Action Hooks
执行特定动作,不返回值
Filter Hooks
过滤修改数据,返回处理值
AJAX Hooks
处理前端异步请求
核心钩子列表
| 钩子名称 | 类型 | 触发时机 | 参数说明 | 扩展示例 |
|---|---|---|---|---|
| ssupport_new_chat_created | Action | 新对话创建完成 | $chat_id, $user_id | 通知第三方系统 |
| ssupport_chat_accepted | Action | 客服接单成功 | $chat_id, $user_id, $agent_id | 记录接单时间 |
| ssupport_chat_ended | Action | 对话结束处理 | $chat_id, $user_id, $agent_id | 生成对话报告 |
| user_ctnter_main_tabs_array | Filter | 用户中心标签加载 | $tabs_array | 自定义标签样式 |
💡 钩子使用示例
/**
* 自定义对话创建后处理
*/
add_action('ssupport_new_chat_created', 'custom_chat_created_handler', 10, 2);
function custom_chat_created_handler($chat_id, $user_id) {
// 1. 记录到自定义日志系统
error_log("新对话创建: 聊天ID={$chat_id}, 用户ID={$user_id}");
// 2. 发送到外部CRM系统
$chat_data = get_chat_details($chat_id);
$response = wp_remote_post('https://crm.example.com/api/chats', [
'body' => json_encode($chat_data),
'headers' => ['Content-Type' => 'application/json']
]);
// 3. 更新用户元数据
$chat_count = get_user_meta($user_id, 'ssupport_chat_count', true);
update_user_meta($user_id, 'ssupport_chat_count', $chat_count + 1);
// 4. 触发自定义业务规则
if (should_escalate_chat($chat_id)) {
escalate_to_supervisor($chat_id);
}
}
/**
* 过滤客服分配规则
*/
add_filter('ssupport_agent_assignment_rules', 'custom_assignment_rules');
function custom_assignment_rules($rules) {
$rules['priority_customers'] = [
'condition' => 'user_is_vip',
'agent_type' => 'senior',
'weight' => 10
];
$rules['business_hours'] = [
'condition' => 'is_business_hours',
'agent_type' => 'regular',
'weight' => 5
];
return $rules;
}
7
安全机制设计
🛡️ 五层安全防护体系
输入验证层
- 数据类型验证
- 长度限制检查
- 格式正则匹配
- 白名单过滤
权限控制层
- 角色权限验证
- 操作范围检查
- 会话状态验证
- 最小权限原则
数据安全层
- SQL参数化查询
- XSS输出转义
- CSRF令牌保护
- 数据加密存储
🔐 具体安全实现
📝 输入验证机制
$chat_id = intval($_POST[‘chat_id’]);
$message = sanitize_textarea_field($_POST[‘message’]);
$rating = min(max(intval($_POST[‘rating’]), 1), 5);
$email = sanitize_email($_POST[’email’]);
🔑 权限验证流程
verify_ajax_request(‘action_name’);
check_user_permission();
validate_chat_ownership($chat_id, $user_id);
check_business_rules($action);
📁 文件上传安全策略
类型验证
MIME类型检查
扩展名白名单
文件头验证
大小限制
客户端限制
服务端验证
配置化管理
存储安全
独立目录存储
随机文件名
权限设置755
清理机制
定期清理任务
引用计数管理
孤儿文件删除
8
性能优化策略
⚡ 多维度优化方案
1
数据库优化
- 索引优化:复合索引、覆盖索引、索引下推
- 查询优化:分页查询、避免SELECT *、使用EXPLAIN
- 连接优化:INNER JOIN替代子查询、连接缓冲
- 缓存策略:查询结果缓存、对象缓存、片段缓存
2
前端优化
- 资源加载:异步加载、懒加载、资源合并
- 渲染优化:虚拟滚动、DOM复用、CSS硬件加速
- 网络优化:请求合并、CDN加速、Gzip压缩
- 内存管理:事件解绑、对象释放、防内存泄漏
📊 性能监控指标
响应时间
并发用户
消息同步
数据容量
🧠 缓存策略设计
对象缓存
用户信息、客服数据、配置设置、权限信息
查询缓存
统计信息、未读计数、等待列表、活跃对话
片段缓存
历史记录、消息列表、用户界面、模态框内容
页面缓存
静态资源、CSS样式、JS脚本、图标字体
9
用户中心集成
🔗 集成架构设计
前端集成
- 标签页集成:通过user_ctnter_main_tabs_array过滤器添加标签
- 侧边栏按钮:通过zib_user_center_page_sidebar_button_3_args添加入口
- 响应式设计:自适应桌面和移动端显示
- 动态徽章:实时显示未读消息和等待对话计数
后端集成
- 权限集成:与WordPress用户角色系统深度集成
- 会话管理:复用WordPress用户会话和认证机制
- 数据隔离:基于用户ID的数据访问控制
- 事件集成:与WordPress钩子系统无缝对接
💻 集成代码示例
/**
* 添加用户中心客服系统标签页
*/
add_filter('user_ctnter_main_tabs_array', 'add_user_center_tab');
function add_user_center_tab($tabs_array) {
if (!is_user_logged_in()) {
return $tabs_array;
}
$user_id = get_current_user_id();
$is_agent = is_user_agent($user_id);
$tabs_array['ssupport'] = array(
'title' => $is_agent ? '客服工作台' : '在线客服',
'nav_attr' => 'drawer-title="' . ($is_agent ? '客服工作台' : '在线客服') . '"',
'loader' => '<div class="text-center p30"><i class="fa fa-spinner fa-spin fa-2x"></i><p class="mt10">加载中...</p></div>',
'content_func' => 'zib_main_user_tab_content_ssupport',
);
return $tabs_array;
}
/**
* 添加用户中心侧边栏按钮
*/
add_filter('zib_user_center_page_sidebar_button_3_args', 'add_user_center_button');
function add_user_center_button($buttons) {
if (!is_user_logged_in()) {
return $buttons;
}
$user_id = get_current_user_id();
$is_agent = is_user_agent($user_id);
if ($is_agent) {
// 客服工作台按钮
$waiting_count = get_waiting_chats_count();
$badge = $waiting_count > 0 ? '<span class="ssupport-unread-badge">' . $waiting_count . '</span>' : '';
$buttons[] = array(
'html' => '',
'icon' => '<svg viewBox="0 0 24 24">...</svg>',
'name' => '客服工作台' . $badge,
'tab' => 'ssupport',
);
} else {
// 用户客服按钮
$unread_count = get_user_unread_total($user_id);
$badge = $unread_count > 0 ? '<span class="ssupport-unread-badge">' . $unread_count . '</span>' : '';
$buttons[] = array(
'html' => '',
'icon' => '<svg t="1764818929823">...</svg>',
'name' => '在线客服' . $badge,
'tab' => 'ssupport',
);
}
return $buttons;
}
/**
* 用户中心标签页内容渲染
*/
function zib_main_user_tab_content_ssupport() {
if (!is_user_logged_in()) {
return '<div class="zib-widget"><div class="text-center c-red">请先登录</div></div>';
}
$user_id = get_current_user_id();
$is_agent = is_user_agent($user_id);
if ($is_agent) {
return render_agent_dashboard();
} else {
return render_user_dashboard();
}
}
10
使用部署指南
🚀 快速部署流程
环境准备与安装
- 系统要求:PHP 7.4+、MySQL 5.7+、WordPress 6.8+
- 文件权限:确保wp-content/uploads目录可写
- 插件安装:上传插件文件到wp-content/plugins目录
- 激活插件:在WordPress后台激活人工客服系统插件
数据库初始化
- 自动建表:插件激活时自动创建5张核心表
- 默认数据:管理员用户自动添加为客服
- 初始配置:加载默认系统设置参数
- 目录创建:建立聊天图片存储目录
系统配置与测试
- 访问用户中心:点击在线客服标签进入系统
- 测试对话流程:创建对话、发送消息、结束对话
- 客服功能测试:登录客服账户测试接单、回复功能
- 通知功能验证:测试站内信和邮件通知是否正常
⚙️ 系统配置详解
基础配置
- 自动分配客服:
- 启用后新对话自动分配给在线客服
- 欢迎消息:
- 用户开始对话时发送的欢迎语
- 结束消息:
- 对话结束时发送的提示信息
- 非活动超时:
- 无消息自动结束对话的时间(分钟)
客服配置
- 客服最大对话数:
- 每个客服同时处理的最大对话数量
- 客服角色:
- 具有这些角色的用户自动成为客服
- 客服接入要求:
- 客服未接入时是否允许用户发送消息
高级配置
- 邮件通知:
- 启用新对话邮件通知功能
- 通知邮箱:
- 接收通知的邮箱地址
- 允许删除历史:
- 是否允许用户删除历史对话
- 图片上传限制:
- 限制用户上传的图片大小(MB)
🔧 故障排除指南
问题:无法发送消息
- 检查用户登录状态
- 验证对话是否已结束
- 确认客服是否已接入
- 检查网络连接状态
问题:图片上传失败
- 检查图片格式支持
- 确认图片大小限制
- 验证目录写入权限
- 查看PHP配置限制
问题:通知未收到
- 检查通知配置是否启用
- 验证邮箱地址有效性
- 查看邮件发送日志
- 检查垃圾邮件文件夹









🎉 系统总结与展望
人工客服系统 v1.3.0 是一个基于WordPress平台开发的专业级在线客服解决方案。系统采用模块化架构设计,支持实时对话、智能客服分配、多通道通知、服务评价等核心功能,同时提供了完善的安全防护和性能优化机制。通过深度集成WordPress用户中心,为用户和客服提供了统一的交互界面。
© 2025 人工客服系统 v1.3.0 | 技术支持:请叫我阿祖 | 文档版本:2025.12
















暂无评论内容