444 lines
10 KiB
Markdown
444 lines
10 KiB
Markdown
# OPSX Tasks: 在线客服模块实施计划
|
||
|
||
## 变更标识
|
||
- **变更ID**: customer-service-module
|
||
- **版本**: 2.0
|
||
- **状态**: ARCHIVED
|
||
- **更新日期**: 2026-01-29
|
||
- **完成日期**: 2026-01-29
|
||
|
||
---
|
||
|
||
## 执行原则
|
||
|
||
> **零决策实施**: 以下所有任务均为纯机械执行，无需实施者做任何技术决策。
|
||
> 所有参数、算法、约束已在 specs.md 和 design.md 中完全定义。
|
||
|
||
---
|
||
|
||
## Phase 1: 基础架构 (数据库 + Socket服务)
|
||
|
||
### TASK-1.1: 创建数据库表
|
||
|
||
**输入**: design.md Section 2.1 表结构SQL
|
||
|
||
**执行步骤**:
|
||
1. 在 `Pro/init.sql` 末尾追加以下4个表的CREATE语句:
|
||
- `cg_chat_session`
|
||
- `cg_chat_message`
|
||
- `cg_chat_quick_reply`
|
||
- `cg_chat_admin_status`
|
||
2. 执行SQL创建表
|
||
|
||
**验收标准**:
|
||
- [x] 4个表创建成功
|
||
- [x] 所有索引创建正确
|
||
- [x] 字符集为utf8mb4
|
||
|
||
---
|
||
|
||
### TASK-1.2: 实现雪花算法工具类
|
||
|
||
**输入**: design.md Section 3.1 Snowflake代码
|
||
|
||
**执行步骤**:
|
||
1. 创建文件 `Socket/app/utils/Snowflake.php`
|
||
2. 复制 design.md 中的 Snowflake 类实现
|
||
3. 配置 workerId=1, datacenterId=1
|
||
|
||
**验收标准**:
|
||
- [x] 生成ID唯一且有序
|
||
- [x] 10000次调用无重复
|
||
|
||
---
|
||
|
||
### TASK-1.3: 创建Socket模型类
|
||
|
||
**输入**: design.md Section 2.1 表结构
|
||
|
||
**执行步骤**:
|
||
1. 创建 `Socket/app/models/chat/ChatSession.php`
|
||
2. 创建 `Socket/app/models/chat/ChatMessage.php`
|
||
3. 创建 `Socket/app/models/chat/ChatQuickReply.php`
|
||
4. 创建 `Socket/app/models/chat/ChatAdminStatus.php`
|
||
|
||
**验收标准**:
|
||
- [x] 4个模型类创建完成
|
||
- [x] 表名前缀正确 `cg_`
|
||
- [x] 自动时间戳配置正确
|
||
|
||
---
|
||
|
||
### TASK-1.4: 实现AssignService分配服务
|
||
|
||
**输入**:
|
||
- design.md Section 3.2 分配算法
|
||
- specs.md Section 1 约束 (CC-01~CC-04)
|
||
|
||
**执行步骤**:
|
||
1. 创建 `Socket/app/services/chat/AssignService.php`
|
||
2. 实现以下方法:
|
||
- `assignSession(int $userId, int $sessionId): ?int`
|
||
- `getOnlineAgents(): array`
|
||
- `selectLeastLoadAgent(): ?int`
|
||
- `addToOfflineQueue(int $userId, int $sessionId): void`
|
||
- `processOfflineQueue(int $adminId): void`
|
||
- `releaseLock(): void`
|
||
3. Redis Key 前缀严格使用 specs.md Section 3 定义
|
||
|
||
**约束参数**:
|
||
- 分配锁超时: 3000ms
|
||
- 单客服最大会话数: 10
|
||
- 队列Key: `cs:queue:pending`
|
||
- 队列Score: `-balance` (余额负数实现降序)
|
||
|
||
**验收标准**:
|
||
- [x] 分配锁防止并发双分配
|
||
- [x] 最少会话数策略正确
|
||
- [x] 离线队列按余额排序
|
||
|
||
---
|
||
|
||
### TASK-1.5: 实现MessageService消息服务
|
||
|
||
**输入**:
|
||
- design.md Section 3.3 重试算法
|
||
- specs.md Section 1 约束 (CC-05~CC-09)
|
||
|
||
**执行步骤**:
|
||
1. 创建 `Socket/app/services/chat/MessageService.php`
|
||
2. 实现以下方法:
|
||
- `createMessage(array $data): int` (生成雪花ID，入库)
|
||
- `pushMessage(int $msgId, int $targetFd, array $payload): bool`
|
||
- `updateMessageStatus(int $msgId, string $status): void`
|
||
- `getUnreadMessages(int $sessionId, int $limit = 50): array`
|
||
- `markMessagesAsRead(array $msgIds): void`
|
||
|
||
**约束参数**:
|
||
- 最大重试次数: 3
|
||
- 重试间隔: [1000, 2000, 4000] ms
|
||
- 消息长度限制: 500字符
|
||
- 重连拉取上限: 50条
|
||
|
||
**验收标准**:
|
||
- [x] 消息ID使用雪花算法
|
||
- [x] 重试策略为指数退避
|
||
- [x] 消息状态正确流转
|
||
|
||
---
|
||
|
||
### TASK-1.6: 实现SessionService会话服务
|
||
|
||
**输入**: specs.md 约束
|
||
|
||
**执行步骤**:
|
||
1. 创建 `Socket/app/services/chat/SessionService.php`
|
||
2. 实现以下方法:
|
||
- `createSession(int $userId, int $source): int`
|
||
- `getActiveSession(int $userId): ?array`
|
||
- `endSession(int $sessionId, int $operatorId): bool`
|
||
- `transferSession(int $sessionId, int $newAdminId): bool`
|
||
- `rateSession(int $sessionId, int $rating, ?string $content): bool`
|
||
|
||
**约束参数**:
|
||
- 会话状态: 0=待分配, 1=进行中, 2=已结束
|
||
- 无自动超时关闭
|
||
|
||
**验收标准**:
|
||
- [x] 同一用户只能有一个活跃会话
|
||
- [x] 转接会话正确更新admin_id
|
||
- [x] 评价存储正确
|
||
|
||
---
|
||
|
||
### TASK-1.7: 实现ChatConnectListener
|
||
|
||
**输入**:
|
||
- specs.md Section 4 WebSocket事件协议
|
||
- specs.md 约束 (CC-10~CC-13)
|
||
|
||
**执行步骤**:
|
||
1. 创建 `Socket/app/listener/chat/ChatConnectListener.php`
|
||
2. 处理事件:
|
||
- `chat.connect`: 验证Token，注册在线状态
|
||
- `chat.ping`: 续期在线状态TTL
|
||
- 断开连接: 清理Redis映射
|
||
3. 在线状态Key: `cs:online:agent:{adminId}` / `cs:conn:user:{userId}`
|
||
|
||
**约束参数**:
|
||
- 心跳间隔: 30秒
|
||
- 离线判定: 60秒 (TTL)
|
||
- 在线状态TTL: 60秒
|
||
|
||
**验收标准**:
|
||
- [x] 连接时验证Token
|
||
- [x] 心跳正确续期TTL
|
||
- [x] 断开时清理Redis
|
||
|
||
---
|
||
|
||
### TASK-1.8: 实现ChatMessageListener
|
||
|
||
**输入**: specs.md Section 4 事件协议
|
||
|
||
**执行步骤**:
|
||
1. 创建 `Socket/app/listener/chat/ChatMessageListener.php`
|
||
2. 处理事件:
|
||
- `chat.message.send`: 创建消息 → 返回server_ack → 推送对端 → 等待peer_ack
|
||
- `chat.message.ack`: 更新消息状态为delivered/read
|
||
- `chat.typing`: 转发正在输入状态
|
||
|
||
**验收标准**:
|
||
- [x] 两段ACK机制实现
|
||
- [x] 消息幂等性(msgId去重)
|
||
- [x] typing状态正确转发
|
||
|
||
---
|
||
|
||
### TASK-1.9: 实现ChatSessionListener
|
||
|
||
**输入**: specs.md Section 4 事件协议
|
||
|
||
**执行步骤**:
|
||
1. 创建 `Socket/app/listener/chat/ChatSessionListener.php`
|
||
2. 处理事件:
|
||
- `chat.session.end`: 结束会话
|
||
- `chat.session.rate`: 提交评价
|
||
- `chat.agent.online`: 客服上线，触发队列处理
|
||
- `chat.agent.offline`: 客服下线
|
||
- `chat.session.transfer`: 转接会话
|
||
|
||
**验收标准**:
|
||
- [x] 客服上线自动处理离线队列
|
||
- [x] 转接正确更新会话归属
|
||
|
||
---
|
||
|
||
### TASK-1.10: 注册Listener到Swoole事件
|
||
|
||
**输入**: 现有Socket模块event.php配置
|
||
|
||
**执行步骤**:
|
||
1. 编辑 `Socket/config/event.php`
|
||
2. 在listen数组中添加聊天相关Listener
|
||
|
||
**验收标准**:
|
||
- [x] Listener正确注册
|
||
- [x] 不影响现有游戏事件处理
|
||
|
||
---
|
||
|
||
## Phase 2: Admin后台
|
||
|
||
### TASK-2.1: 创建Chat控制器
|
||
|
||
**输入**: design.md Section 4.1 API
|
||
|
||
**执行步骤**:
|
||
1. 创建 `Pro/application/admin/controller/Chat.php`
|
||
2. 继承 `Common` 基类
|
||
3. 实现方法:
|
||
- `index()`: 客服工作台页面
|
||
- `sessions()`: 获取会话列表
|
||
- `messages()`: 获取消息历史
|
||
- `endSession()`: 结束会话
|
||
- `transfer()`: 转接会话
|
||
- `stats()`: 统计数据
|
||
|
||
**验收标准**:
|
||
- [x] 继承Common基类
|
||
- [x] 权限校验通过
|
||
|
||
---
|
||
|
||
### TASK-2.2: 创建ChatQuickReply控制器
|
||
|
||
**执行步骤**:
|
||
1. 创建 `Pro/application/admin/controller/ChatQuickReply.php`
|
||
2. 实现CRUD方法:
|
||
- `index()`: 列表
|
||
- `add()`: 添加
|
||
- `edit()`: 编辑
|
||
- `del()`: 删除
|
||
|
||
**验收标准**:
|
||
- [x] CRUD功能完整
|
||
- [x] 使用insertAdminLog记录操作
|
||
|
||
---
|
||
|
||
### TASK-2.3: 创建客服工作台页面
|
||
|
||
**输入**: Layui组件规范
|
||
|
||
**执行步骤**:
|
||
1. 创建 `Pro/application/admin/view/chat/index.html`
|
||
2. 布局:
|
||
- 左侧: 会话列表(待接入/进行中)
|
||
- 中间: 聊天窗口
|
||
- 右侧: 用户信息面板
|
||
3. WebSocket连接Admin后台
|
||
|
||
**验收标准**:
|
||
- [x] Layui风格一致
|
||
- [x] 实时消息收发
|
||
- [x] 新消息声音提示
|
||
|
||
---
|
||
|
||
### TASK-2.4: 创建快捷回复管理页面
|
||
|
||
**执行步骤**:
|
||
1. 创建 `Pro/application/admin/view/chat_quick_reply/index.html`
|
||
2. 创建 `Pro/application/admin/view/chat_quick_reply/add.html`
|
||
3. 表格展示: 分类、标题、内容、排序、状态
|
||
|
||
**验收标准**:
|
||
- [x] 列表分页正确
|
||
- [x] 添加/编辑表单验证
|
||
|
||
---
|
||
|
||
### TASK-2.5: 创建聊天记录查询页面
|
||
|
||
**执行步骤**:
|
||
1. 创建 `Pro/application/admin/view/chat/record.html`
|
||
2. 筛选条件: 用户名、客服、时间范围
|
||
3. 支持CSV导出
|
||
|
||
**验收标准**:
|
||
- [x] 搜索功能正确
|
||
- [x] 导出格式正确
|
||
|
||
---
|
||
|
||
### TASK-2.6: 添加后台菜单入口
|
||
|
||
**执行步骤**:
|
||
1. 在数据库 `cg_auth_rule` 表插入菜单
|
||
2. 分配权限给客服角色
|
||
|
||
**验收标准**:
|
||
- [x] 菜单显示正确
|
||
- [x] 权限控制正确
|
||
|
||
---
|
||
|
||
## Phase 3: 前端改造
|
||
|
||
### TASK-3.1: PC端聊天组件开发
|
||
|
||
**输入**: Element UI组件规范
|
||
|
||
**执行步骤**:
|
||
1. 创建 `PC/src/components/chat/chat.vue`
|
||
|
||
**验收标准**:
|
||
- [x] WebSocket连接稳定
|
||
- [x] 消息实时收发
|
||
|
||
---
|
||
|
||
### TASK-3.2: PC端客服入口改造
|
||
|
||
**执行步骤**:
|
||
1. 修改客服入口，改为打开ChatWindow组件
|
||
|
||
**验收标准**:
|
||
- [x] 点击客服按钮打开聊天窗口
|
||
- [x] 不再跳转外链
|
||
|
||
---
|
||
|
||
### TASK-3.3: Game端聊天组件开发
|
||
|
||
**状态**: 跳过 (用户确认不需要集成)
|
||
|
||
---
|
||
|
||
### TASK-3.4: Game端客服入口添加
|
||
|
||
**状态**: 跳过 (用户确认不需要集成)
|
||
|
||
---
|
||
|
||
### TASK-3.5: Portal端聊天页面改造
|
||
|
||
**输入**: uView组件规范
|
||
|
||
**执行步骤**:
|
||
1. 修改 `Portal/pages/user/customservice.vue`
|
||
2. 移除Telegram/Line外链
|
||
3. 改为内嵌聊天功能
|
||
|
||
**验收标准**:
|
||
- [x] uView风格
|
||
- [x] uni-app兼容(H5/小程序)
|
||
|
||
---
|
||
|
||
### TASK-3.6: 前端图片上传接口对接
|
||
|
||
**执行步骤**:
|
||
1. 各端创建图片上传方法
|
||
2. 调用 `/api/chat/upload` 接口
|
||
3. 限制: 2MB, jpg/png/gif
|
||
|
||
**验收标准**:
|
||
- [x] 上传前校验大小
|
||
- [x] 上传后返回URL
|
||
|
||
---
|
||
|
||
## Phase 4: 集成测试
|
||
|
||
### TASK-4.1: PBT属性测试
|
||
|
||
**状态**: 跳过 (手动测试验证)
|
||
|
||
---
|
||
|
||
### TASK-4.2: 端到端测试
|
||
|
||
**执行步骤**:
|
||
1. 用户发起咨询 → 客服接入 → 消息往返 → 结束会话 → 评价
|
||
2. 离线留言 → 客服上线 → 按余额顺序处理
|
||
3. 断线重连 → 补发未读消息
|
||
|
||
**验收标准**:
|
||
- [x] 完整流程通过
|
||
- [x] 消息延迟<500ms
|
||
|
||
---
|
||
|
||
## 实施统计
|
||
|
||
### 代码量统计
|
||
|
||
| 模块 | 文件数 | 代码行数 |
|
||
|------|--------|----------|
|
||
| Pro 控制器 | 2 | 692 |
|
||
| Pro 视图 | 5 | 1,600 |
|
||
| Socket Listener | 14 | 1,381 |
|
||
| Socket Services | 3 | 986 |
|
||
| Socket Models | 4 | 236 |
|
||
| Portal 前端 | 1 | 518 |
|
||
| PC 前端 | 1 | 122 |
|
||
| **总计** | **30** | **5,535** |
|
||
|
||
### 完成情况
|
||
|
||
| Phase | 任务数 | 完成 | 跳过 |
|
||
|-------|--------|------|------|
|
||
| Phase 1: 基础架构 | 10 | 10 | 0 |
|
||
| Phase 2: Admin后台 | 6 | 6 | 0 |
|
||
| Phase 3: 前端改造 | 6 | 4 | 2 (Game端) |
|
||
| Phase 4: 集成测试 | 2 | 1 | 1 (PBT测试) |
|
||
| **总计** | **24** | **21** | **3** |
|
||
|
||
---
|
||
|
||
*文档版本: 2.0*
|
||
*最后更新: 2026-01-29*
|
||
*归档日期: 2026-01-29*
|