# OPSX Proposal: 在线客服模块集成

## 变更标识
- **变更ID**: customer-service-module
- **创建日期**: 2026-01-28
- **状态**: SPEC_COMPLETE

---

## 1. 上下文 (Context)

### 1.1 用户需求
在OG Live Gaming Platform的admin后台集成在线客服模块，将PC端和移动端(Game/Portal)的客服功能从外链跳转改为内置实时聊天，所有用户消息统一转发到后台由客服人员回复。

### 1.2 现有实现
- **当前方案**: 外链跳转第三方客服平台
  - PC端: `PC/src/components/updateService/update-service.vue` - 通过 `webconfig.customerLink` 跳转
  - Portal端: `Portal/pages/user/customservice.vue` - 支持 Telegram/Line 外部链接
- **问题**: 无法统一管理用户咨询，缺乏历史记录追溯

### 1.3 技术环境
| 组件 | 技术栈 | 版本 |
|------|--------|------|
| 后端主服务 | ThinkPHP | 5.x |
| WebSocket服务 | ThinkPHP + Swoole | 6.x |
| PC前端 | Vue.js + Element UI | 2.x |
| Game前端 | Vue.js + Vant | 3.x |
| Portal前端 | uni-app + uView | - |
| 数据库 | MySQL | 5.7 |
| 缓存 | Redis | 5.x |

---

## 2. 约束集合 (Constraint Sets)

### 2.1 硬约束 (Hard Constraints) - 不可违反

| ID | 约束 | 来源 | 影响 |
|----|------|------|------|
| HC-01 | 必须使用现有Socket服务(ThinkPHP 6.x + Swoole)作为WebSocket通信基础 | 架构一致性 | 不能引入新的WebSocket服务 |
| HC-02 | 数据库表必须使用 `cg_` 前缀 | `application/database.php:23` | 表名规范 |
| HC-03 | Admin后台控制器必须继承 `Common` 基类 | `application/admin/controller/Common.php` | 权限控制 |
| HC-04 | 前端API请求必须通过现有封装的HTTP客户端 | 各端API封装 | 接口一致性 |
| HC-05 | 用户认证必须复用现有Session/Token机制 | 安全性 | 不能引入新认证体系 |

### 2.2 软约束 (Soft Constraints) - 建议遵循

| ID | 约束 | 来源 | 建议 |
|----|------|------|------|
| SC-01 | Admin后台UI应使用Layui框架 | 现有后台风格 | 保持视觉一致性 |
| SC-02 | WebSocket事件应遵循现有listener模式 | `Socket/app/listener/` | 代码组织一致 |
| SC-03 | 前端组件命名应遵循各端现有规范 | 代码风格 | PascalCase组件名 |
| SC-04 | 日志记录应使用现有 `insertAdminLog()` 函数 | `application/helper.php` | 审计追踪 |

### 2.3 依赖约束 (Dependencies)

| ID | 依赖项 | 类型 | 说明 |
|----|--------|------|------|
| DC-01 | cg_user 表 | 数据 | 用户信息关联 |
| DC-02 | cg_admin 表 | 数据 | 客服人员账号 |
| DC-03 | Redis | 基础设施 | 在线状态、会话分配 |
| DC-04 | Socket服务 | 服务 | 实时消息推送 |

---

## 3. 需求规格 (Requirements)

### 3.1 功能需求

#### REQ-01: 后台客服工作台
**场景**: 客服人员登录admin后台，进入客服模块
**验收标准**:
- [ ] 显示待接入会话列表（按等待时间排序）
- [ ] 显示当前处理中的会话列表
- [ ] 支持同时处理多个会话（标签页切换）
- [ ] 实时显示新消息通知（声音+视觉提示）
- [ ] 显示用户基本信息（用户名、余额、来源端）

#### REQ-02: 会话自动分配
**场景**: 用户发起客服咨询
**验收标准**:
- [ ] 系统自动将用户分配给当前会话数最少的在线客服
- [ ] 客服离线时，消息进入待分配队列
- [ ] 支持会话转接给其他在线客服
- [ ] 记录会话分配历史

#### REQ-03: 实时消息通信
**场景**: 用户与客服进行对话
**验收标准**:
- [ ] 支持文字消息发送/接收
- [ ] 支持图片消息发送/接收（上传+预览）
- [ ] 消息实时推送（延迟<500ms）
- [ ] 显示消息发送状态（发送中/已送达/已读）
- [ ] 支持消息时间戳显示

#### REQ-04: 离线消息
**场景**: 用户发送消息时客服全部离线，或客服回复时用户已离线
**验收标准**:
- [ ] 离线消息持久化存储
- [ ] 用户/客服上线后自动推送未读消息
- [ ] 显示未读消息数量角标

#### REQ-05: 快捷回复
**场景**: 客服需要快速回复常见问题
**验收标准**:
- [ ] 支持预设快捷回复语管理（增删改）
- [ ] 支持快捷回复分类
- [ ] 一键插入快捷回复内容

#### REQ-06: 聊天记录查询
**场景**: 客服或管理员需要查看历史对话
**验收标准**:
- [ ] 支持按用户名搜索
- [ ] 支持按时间范围筛选
- [ ] 支持按客服人员筛选
- [ ] 支持导出聊天记录

#### REQ-07: 用户信息展示
**场景**: 客服处理会话时需要了解用户背景
**验收标准**:
- [ ] 显示用户账号、昵称
- [ ] 显示用户余额
- [ ] 显示用户来源（PC/Game/Portal）
- [ ] 显示用户上级代理信息
- [ ] 显示用户最近下注记录（可选）

#### REQ-08: 会话评价
**场景**: 用户结束咨询后对服务进行评价
**验收标准**:
- [ ] 会话结束后弹出评价窗口
- [ ] 支持1-5星评分
- [ ] 支持文字评价（可选）
- [ ] 后台可查看评价统计

#### REQ-09: 前端客服入口改造
**场景**: 用户在PC/Game/Portal端点击客服按钮
**验收标准**:
- [ ] PC端: 替换外链跳转为内嵌聊天窗口
- [ ] Game端: 添加客服聊天组件
- [ ] Portal端: 替换外链页面为聊天页面
- [ ] 三端UI风格与各自设计语言一致

---

## 4. 数据库设计

### 4.1 新增表结构

```sql
-- 客服会话表
CREATE TABLE `cg_chat_session` (
  `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
  `user_id` int(10) unsigned NOT NULL COMMENT '用户ID',
  `admin_id` int(10) unsigned DEFAULT NULL COMMENT '客服ID',
  `source` tinyint(1) NOT NULL DEFAULT '1' COMMENT '来源: 1=PC 2=Game 3=Portal',
  `status` tinyint(1) NOT NULL DEFAULT '0' COMMENT '状态: 0=待分配 1=进行中 2=已结束',
  `rating` tinyint(1) DEFAULT NULL COMMENT '评分: 1-5',
  `rating_content` varchar(500) DEFAULT NULL COMMENT '评价内容',
  `create_time` int(10) unsigned NOT NULL,
  `update_time` int(10) unsigned NOT NULL,
  `end_time` int(10) unsigned DEFAULT NULL,
  PRIMARY KEY (`id`),
  KEY `user_id` (`user_id`),
  KEY `admin_id` (`admin_id`),
  KEY `status` (`status`),
  KEY `create_time` (`create_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='客服会话表';

-- 聊天消息表
CREATE TABLE `cg_chat_message` (
  `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
  `session_id` int(10) unsigned NOT NULL COMMENT '会话ID',
  `sender_type` tinyint(1) NOT NULL COMMENT '发送者类型: 1=用户 2=客服',
  `sender_id` int(10) unsigned NOT NULL COMMENT '发送者ID',
  `msg_type` tinyint(1) NOT NULL DEFAULT '1' COMMENT '消息类型: 1=文字 2=图片',
  `content` text NOT NULL COMMENT '消息内容',
  `is_read` tinyint(1) NOT NULL DEFAULT '0' COMMENT '是否已读',
  `create_time` int(10) unsigned NOT NULL,
  PRIMARY KEY (`id`),
  KEY `session_id` (`session_id`),
  KEY `sender_type` (`sender_type`),
  KEY `is_read` (`is_read`),
  KEY `create_time` (`create_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='聊天消息表';

-- 快捷回复表
CREATE TABLE `cg_chat_quick_reply` (
  `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
  `category` varchar(50) DEFAULT NULL COMMENT '分类',
  `title` varchar(100) NOT NULL COMMENT '标题',
  `content` text NOT NULL COMMENT '内容',
  `sort` int(10) unsigned NOT NULL DEFAULT '0' COMMENT '排序',
  `status` tinyint(1) NOT NULL DEFAULT '1' COMMENT '状态',
  `create_time` int(10) unsigned NOT NULL,
  PRIMARY KEY (`id`),
  KEY `category` (`category`),
  KEY `status` (`status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='快捷回复表';

-- 客服在线状态表 (Redis辅助)
CREATE TABLE `cg_chat_admin_status` (
  `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
  `admin_id` int(10) unsigned NOT NULL COMMENT '客服ID',
  `is_online` tinyint(1) NOT NULL DEFAULT '0' COMMENT '是否在线',
  `current_sessions` int(10) unsigned NOT NULL DEFAULT '0' COMMENT '当前会话数',
  `max_sessions` int(10) unsigned NOT NULL DEFAULT '10' COMMENT '最大会话数',
  `last_active_time` int(10) unsigned DEFAULT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `admin_id` (`admin_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='客服状态表';
```

---

## 5. 技术方案

### 5.1 架构图

```
┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│   PC端      │  │   Game端    │  │  Portal端   │
│  (Vue 2.x)  │  │  (Vue 3.x)  │  │  (uni-app)  │
└──────┬──────┘  └──────┬──────┘  └──────┬──────┘
       │                │                │
       └────────────────┼────────────────┘
                        │ WebSocket
                        ▼
              ┌─────────────────┐
              │  Socket服务     │
              │ (TP6 + Swoole)  │
              │                 │
              │ 新增listener:   │
              │ - ChatConnect   │
              │ - ChatMessage   │
              │ - ChatSession   │
              └────────┬────────┘
                       │
         ┌─────────────┼─────────────┐
         │             │             │
         ▼             ▼             ▼
   ┌──────────┐  ┌──────────┐  ┌──────────┐
   │  MySQL   │  │  Redis   │  │  文件存储 │
   │ 消息持久化│  │ 在线状态 │  │ 图片上传  │
   └──────────┘  └──────────┘  └──────────┘
                        │
                        ▼
              ┌─────────────────┐
              │   Admin后台     │
              │   (TP5 + Layui) │
              │                 │
              │ 新增模块:       │
              │ - Chat控制器    │
              │ - 客服工作台    │
              │ - 快捷回复管理  │
              │ - 聊天记录查询  │
              └─────────────────┘
```

### 5.2 WebSocket事件设计

| 事件名 | 方向 | 说明 |
|--------|------|------|
| `chat.connect` | Client→Server | 用户/客服建立聊天连接 |
| `chat.message` | 双向 | 发送/接收消息 |
| `chat.typing` | 双向 | 正在输入状态 |
| `chat.read` | Client→Server | 消息已读回执 |
| `chat.session.new` | Server→Admin | 新会话通知 |
| `chat.session.assign` | Server→Admin | 会话分配通知 |
| `chat.session.transfer` | Admin→Server | 会话转接 |
| `chat.session.end` | 双向 | 会话结束 |
| `chat.admin.online` | Admin→Server | 客服上线 |
| `chat.admin.offline` | Admin→Server | 客服下线 |

### 5.3 文件变更清单

#### Pro模块 (Admin后台)
```
application/admin/controller/
├── Chat.php              # 新增 - 客服工作台控制器
├── ChatRecord.php        # 新增 - 聊天记录控制器
└── ChatQuickReply.php    # 新增 - 快捷回复管理控制器

application/admin/view/
├── chat/
│   ├── index.html        # 新增 - 客服工作台页面
│   └── record.html       # 新增 - 聊天记录页面
└── chat_quick_reply/
    ├── index.html        # 新增 - 快捷回复列表
    └── add.html          # 新增 - 添加快捷回复

application/admin/view/index/index.html  # 修改 - 添加客服菜单入口
```

#### Socket模块
```
app/listener/chat/
├── ChatConnect.php       # 新增 - 聊天连接处理
├── ChatMessage.php       # 新增 - 消息处理
└── ChatSession.php       # 新增 - 会话管理

app/services/chat/
├── ChatService.php       # 新增 - 聊天核心服务
├── SessionService.php    # 新增 - 会话分配服务
└── MessageService.php    # 新增 - 消息存储服务

app/models/chat/
├── ChatSession.php       # 新增 - 会话模型
├── ChatMessage.php       # 新增 - 消息模型
└── ChatQuickReply.php    # 新增 - 快捷回复模型
```

#### PC端
```
src/components/chat/
├── ChatWindow.vue        # 新增 - 聊天窗口组件
├── ChatMessage.vue       # 新增 - 消息气泡组件
└── ChatInput.vue         # 新增 - 输入框组件

src/components/updateService/
└── update-service.vue    # 修改 - 改为打开聊天窗口
```

#### Game端
```
src/components/chat/
├── ChatWindow.vue        # 新增 - 聊天窗口组件
├── ChatMessage.vue       # 新增 - 消息气泡组件
└── ChatInput.vue         # 新增 - 输入框组件

src/components/
└── HallNav.vue           # 修改 - 添加客服入口
```

#### Portal端
```
pages/user/
└── customservice.vue     # 修改 - 改为聊天页面

components/chat/
├── ChatWindow.vue        # 新增 - 聊天窗口组件
└── ChatMessage.vue       # 新增 - 消息组件
```

---

## 6. 风险评估

| 风险 | 等级 | 缓解措施 |
|------|------|----------|
| WebSocket连接数过多导致服务压力 | 中 | 实现连接池、心跳检测、自动断开空闲连接 |
| 消息丢失 | 中 | 消息持久化优先、ACK确认机制 |
| 图片上传占用存储 | 低 | 图片压缩、定期清理、可配置存储路径 |
| 客服全部离线时用户体验 | 低 | 显示离线提示、支持留言 |

---

## 7. 成功判据 (Success Criteria)

- [ ] 用户可在PC/Game/Portal三端发起客服咨询
- [ ] 客服可在Admin后台实时接收和回复消息
- [ ] 消息延迟 < 500ms
- [ ] 支持文字和图片消息
- [ ] 离线消息可正常存储和推送
- [ ] 会话自动分配正常工作
- [ ] 聊天记录可查询和导出
- [ ] 快捷回复功能正常
- [ ] 会话评价功能正常

---

## 8. 实施阶段建议

### Phase 1: 基础架构
- 数据库表创建
- Socket服务聊天事件监听器
- 基础消息收发功能

### Phase 2: Admin后台
- 客服工作台UI
- 会话管理
- 快捷回复管理

### Phase 3: 前端改造
- PC端聊天组件
- Game端聊天组件
- Portal端聊天页面

### Phase 4: 增强功能
- 离线消息
- 会话评价
- 聊天记录查询导出

---

*文档版本: 1.0*
*最后更新: 2026-01-28*