# 客服管理模块 - 快速开始指南 ## 🎯 项目概述 客服管理模块是一套完整的客服系统前端实现，一致对标 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 **状态**: ✅ 生产就绪 祝您使用愉快! 🎉