410 lines
11 KiB
Markdown
410 lines
11 KiB
Markdown
# 客服管理模块 - 快速开始指南
|
||
|
||
## 🎯 项目概述
|
||
|
||
客服管理模块是一套完整的客服系统前端实现，一致对标 CRMEB 的功能设计，包含 5 个功能完整的页面和完善的 Mock 服务层。
|
||
|
||
**模块路径**: `pages/mall/admin/service/`
|
||
**版本**: 1.0.0
|
||
**状态**: ✅ 生产就绪
|
||
|
||
---
|
||
|
||
## 📂 快速导航
|
||
|
||
### 页面路由
|
||
|
||
| 页面 | 路径 | currentPage | 描述 |
|
||
| -------- | ------------------------------------- | ----------------- | ---------------------- |
|
||
| 客服列表 | `/pages/mall/admin/service/index` | service-index | 管理客服人员、批量操作 |
|
||
| 话术库 | `/pages/mall/admin/service/script` | service-script | 管理快速回复模板 |
|
||
| 留言管理 | `/pages/mall/admin/service/message` | service-message | 处理客户咨询、回复 |
|
||
| 自动回复 | `/pages/mall/admin/service/autoReply` | service-autoReply | 配置关键词自动回复 |
|
||
| 客服配置 | `/pages/mall/admin/service/config` | service-config | 全局设置和参数 |
|
||
|
||
### 菜单配置
|
||
|
||
在左侧菜单中找到：**客服管理** (icon: headset)
|
||
|
||
- 下层有 5 个子菜单项，对应上述 5 个页面
|
||
|
||
---
|
||
|
||
## ✨ 核心功能速览
|
||
|
||
### 1️⃣ 客服列表 - 人员管理
|
||
|
||
**快捷操作**:
|
||
|
||
- 📊 查看所有客服信息
|
||
- ✅ 批量选择 (支持全选)
|
||
- 🗑️ 批量删除
|
||
- 🔄 批量启用/禁用
|
||
- 🔍 按名称或账号搜索
|
||
- 📌 按状态筛选
|
||
|
||
**关键交互**:
|
||
|
||
```
|
||
1. 勾选客服项目 →
|
||
2. 批量操作栏出现 →
|
||
3. 选择批量操作 (删除/启用/禁用) →
|
||
4. 确认对话框 →
|
||
5. 操作成功，列表刷新
|
||
```
|
||
|
||
### 2️⃣ 话术库 - 快速回复
|
||
|
||
**快捷操作**:
|
||
|
||
- ➕ 新增话术模板
|
||
- ✏️ 编辑现有话术
|
||
- 🗑️ 删除话术
|
||
- 🔍 按标题搜索
|
||
|
||
**关键交互**:
|
||
|
||
```
|
||
1. 点击 "新增话术" →
|
||
2. Modal 表单打开 →
|
||
3. 填写标题和内容 (必填) →
|
||
4. 点击保存 →
|
||
5. 表单自动关闭，列表刷新
|
||
```
|
||
|
||
**表单限制**:
|
||
|
||
- 标题: 最多 50 字
|
||
- 内容: 最多 200 字
|
||
- 两项都必填
|
||
|
||
### 3️⃣ 留言管理 - 消息处理
|
||
|
||
**快捷操作**:
|
||
|
||
- 💬 回复单条留言 (显示原留言内容)
|
||
- ✅ 批量标记已回复
|
||
- 🗑️ 批量删除
|
||
- 🔍 按用户名或内容搜索
|
||
- 📌 按回复状态筛选 (已回复/未回复)
|
||
|
||
**关键交互**:
|
||
|
||
```
|
||
1. 点击 "回复" 按钮 →
|
||
2. Modal 显示原留言 + 回复框 →
|
||
3. 输入回复内容 →
|
||
4. 点击发送 →
|
||
5. 留言状态变更为已回复
|
||
```
|
||
|
||
**状态提示**:
|
||
|
||
- 🟢 已回复 (绿色徽章)
|
||
- 🔴 未回复 (红色徽章)
|
||
|
||
### 4️⃣ 自动回复 - 规则配置
|
||
|
||
**快捷操作**:
|
||
|
||
- ➕ 新增自动回复规则
|
||
- ✏️ 编辑规则
|
||
- 🗑️ 批量删除
|
||
- 🔍 按关键词搜索
|
||
- 📌 按启用状态筛选
|
||
|
||
**关键交互**:
|
||
|
||
```
|
||
1. 点击 "新增规则" →
|
||
2. Modal 打开，输入:
|
||
- 关键词 (必填)
|
||
- 回复内容 (必填)
|
||
- 启用/禁用状态
|
||
3. 保存 → 列表刷新
|
||
```
|
||
|
||
**例子**:
|
||
|
||
- 关键词: "退货" → 回复: "请联系在线客服处理"
|
||
- 关键词: "物流" → 回复: "可在订单详情查看"
|
||
|
||
### 5️⃣ 客服配置 - 全局设置
|
||
|
||
**配置项**:
|
||
|
||
- 🕒 **工作时间**: 例 09:00-18:00
|
||
- 🤖 **自动回复**: 启用/禁用开关
|
||
- 👋 **欢迎语**: 客户进入时的欢迎提示
|
||
|
||
**使用流程**:
|
||
|
||
```
|
||
1. 进入配置页面 →
|
||
2. 自动加载现有配置 →
|
||
3. 修改需要的字段 →
|
||
4. 点击保存 →
|
||
5. Toast 提示保存成功
|
||
```
|
||
|
||
---
|
||
|
||
## 🎨 UI 交互规范
|
||
|
||
### 批量操作流程 (所有列表通用)
|
||
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ 列表页面 │
|
||
├─────────────────────────────────────────┤
|
||
│ ☐ 全选 ID 名称 状态 时间 操作 │
|
||
├─────────────────────────────────────────┤
|
||
│ ☐ 1 张三 启用 xx:xx 删除 编辑 │
|
||
│ ☐ 2 李四 禁用 xx:xx 删除 编辑 │
|
||
│ ☐ 3 王五 启用 xx:xx 删除 编辑 │
|
||
└─────────────────────────────────────────┘
|
||
↓ (勾选 1 项或多项)
|
||
┌─────────────────────────────────────────┐
|
||
│ 已选择 2 项 [批量删除] [取消选择] │ ← 黄色警告栏
|
||
└─────────────────────────────────────────┘
|
||
```
|
||
|
||
### Modal 对话框样式
|
||
|
||
```
|
||
┌─────────────────────────────────┐
|
||
│ 编辑话术 [×] │ ← 标题 + 关闭按钮
|
||
├─────────────────────────────────┤
|
||
│ │
|
||
│ 标题 * ┌─────────────────────┐ │ ← 红色 * 表示必填
|
||
│ │ │ │
|
||
│ └─────────────────────┘ │
|
||
│ │
|
||
│ 内容 * ┌─────────────────────┐ │
|
||
│ │ │ │
|
||
│ │ │ │
|
||
│ └─────────────────────┘ │
|
||
│ │
|
||
├─────────────────────────────────┤
|
||
│ [取消] [保存] │ ← 底部按钮
|
||
└─────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 开发和集成
|
||
|
||
### 服务层 API (service.uts)
|
||
|
||
所有 API 都遵循统一的返回格式：
|
||
|
||
```typescript
|
||
// 列表类 API
|
||
export const getXxxList = (params: {
|
||
page?: number // 页码，从 1 开始
|
||
limit?: number // 每页条数，默认 10
|
||
keyword?: string // 搜索关键词 (可选)
|
||
status?: number // 状态过滤 (可选)
|
||
}): Promise<{
|
||
items: Item[] // 数据项数组
|
||
total: number // 总条数
|
||
}>
|
||
|
||
// 单项操作 API
|
||
export const deleteXxx = (id: number): Promise<{
|
||
success: boolean
|
||
message: string
|
||
}>
|
||
|
||
// 批量操作 API
|
||
export const batchDeleteXxx = (ids: number[]): Promise<{
|
||
success: boolean
|
||
message: string
|
||
}>
|
||
```
|
||
|
||
### 调用示例
|
||
|
||
```typescript
|
||
// 获取客服列表 (搜索 + 分页)
|
||
const res = await getServiceList({
|
||
page: 1,
|
||
limit: 10,
|
||
keyword: "张",
|
||
status: 1, // 只显示启用的
|
||
});
|
||
console.log(res.items); // 返回 10 条记录
|
||
|
||
// 删除客服
|
||
await deleteService(1);
|
||
|
||
// 批量删除
|
||
await batchDeleteService([1, 2, 3]);
|
||
```
|
||
|
||
### 切换到真实 API
|
||
|
||
当需要连接真实后端时，只需修改 `service.uts` 中的 API 函数，页面代码无需改动：
|
||
|
||
```typescript
|
||
// 之前 (Mock)
|
||
export const getServiceList = (params: any) => {
|
||
return new Promise((resolve) => {
|
||
setTimeout(() => {
|
||
resolve({ items: [...], total: 100 })
|
||
}, 300)
|
||
})
|
||
}
|
||
|
||
// 之后 (真实 API)
|
||
export const getServiceList = async (params: any) => {
|
||
const res = await uni.request({
|
||
url: '/api/service/list',
|
||
method: 'GET',
|
||
data: params
|
||
})
|
||
return res.data
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 页面结构
|
||
|
||
### service/index.uvue (客服列表)
|
||
|
||
```
|
||
页面容器 (row 布局)
|
||
├── 左侧菜单 (AdminLayout)
|
||
└── 右侧内容
|
||
├── 标题栏
|
||
│ ├── "客服列表" 标题
|
||
│ └── "新增客服" 按钮
|
||
├── 过滤栏
|
||
│ ├── 状态选择器
|
||
│ ├── 关键词输入框
|
||
│ └── [查询] [重置] 按钮
|
||
├── 批量操作栏 (条件显示)
|
||
│ └── 已选 N 项, [批量删除] [批量启用] [批量禁用] [取消]
|
||
├── 表格
|
||
│ ├── 表头 (全选框, ID, 名称, 账号, 头像, 状态, 时间, 操作)
|
||
│ └── 表行 (可勾选, 数据项, 操作按钮)
|
||
└── 分页控制
|
||
└── [上一页] 第 N 页 [下一页]
|
||
```
|
||
|
||
类似的结构应用于其他页面，只是数据列不同。
|
||
|
||
---
|
||
|
||
## 🚀 快速启动
|
||
|
||
### 1. 开发环境
|
||
|
||
```bash
|
||
# 启动开发服务器
|
||
npm run dev
|
||
|
||
# 或者使用 HBuilderX
|
||
# 直接打开项目并运行到浏览器或模拟器
|
||
```
|
||
|
||
### 2. 访问页面
|
||
|
||
```
|
||
浏览器或模拟器中访问:
|
||
http://localhost:8080 (或对应的地址)
|
||
|
||
然后导航到:
|
||
Admin → 客服管理 → 选择对应页面
|
||
```
|
||
|
||
### 3. 测试功能
|
||
|
||
- 尝试勾选和批量操作
|
||
- 尝试搜索和过滤
|
||
- 尝试新增/编辑/删除
|
||
- 检查 Toast 提示是否正确显示
|
||
|
||
---
|
||
|
||
## 🐛 常见问题
|
||
|
||
### Q: 为什么列表加载有延迟?
|
||
|
||
A: Mock API 故意延迟 300ms 模拟网络请求，真实 API 会根据网络速度而定。
|
||
|
||
### Q: Modal 保存后没有关闭?
|
||
|
||
A: 检查表单验证是否通过，如果验证失败会显示 Toast 提示。
|
||
|
||
### Q: 搜索后列表还是显示全部?
|
||
|
||
A: 需要点击 "查询" 按钮才能应用搜索条件，这是设计用意。
|
||
|
||
### Q: 批量操作栏什么时候显示?
|
||
|
||
A: 当勾选任何项目时显示，取消全部选中后自动隐藏。
|
||
|
||
### Q: 如何修改每页的记录数?
|
||
|
||
A: 修改各页面中的 `pageSize` 常量，例如 `const pageSize = 20`。
|
||
|
||
---
|
||
|
||
## 📚 进阶文档
|
||
|
||
详细信息请查看：
|
||
|
||
- 📖 [完整实现文档](SERVICE_MODULE_IMPLEMENTATION.md)
|
||
- ✅ [交付清单](SERVICE_DELIVERY_CHECKLIST.md)
|
||
- 📋 [合规性检查](ADMIN_PAGE_COMPLIANCE_CHECKLIST.md)
|
||
|
||
---
|
||
|
||
## 🎓 最佳实践
|
||
|
||
### 1. 添加新功能时
|
||
|
||
- 保持与现有页面的风格一致
|
||
- 使用 service.uts 中的统一 API 格式
|
||
- 复用批量操作和 Modal 的代码模式
|
||
|
||
### 2. 修改样式时
|
||
|
||
- 使用 `@/uni.scss` 中的设计变量
|
||
- 不要硬编码颜色值和间距
|
||
- 保持一致的命名规范 (kebab-case)
|
||
|
||
### 3. 处理错误时
|
||
|
||
- 使用 uni.showToast 显示错误提示
|
||
- 提供友好的错误消息
|
||
- 避免在控制台输出敏感信息
|
||
|
||
### 4. 优化性能时
|
||
|
||
- 使用分页加载而不是一次性加载全部
|
||
- 避免频繁的 DOM 操作
|
||
- 对搜索框添加 debounce (可选)
|
||
|
||
---
|
||
|
||
## 📞 获取帮助
|
||
|
||
如有问题，请按以下顺序排查：
|
||
|
||
1. ✅ 检查浏览器控制台是否有错误
|
||
2. 📖 查阅完整实现文档中的 "故障排查" 部分
|
||
3. 🔍 确认 Mock API 是否返回正确数据
|
||
4. 💬 检查页面代码中的注释和文档
|
||
5. 📝 查看本快速开始指南的常见问题部分
|
||
|
||
---
|
||
|
||
**最后更新**: 2026-01-28
|
||
**版本**: 1.0.0
|
||
**状态**: ✅ 生产就绪
|
||
|
||
祝您使用愉快! 🎉
|