medical-mall/docs/admin/SERVICE_QUICK_START.md

客服管理模块 - 快速开始指南

🎯 项目概述

客服管理模块是一套完整的客服系统前端实现，一致对标 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 都遵循统一的返回格式：

// 列表类 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
}>

调用示例

// 获取客服列表 (搜索 + 分页)
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 函数，页面代码无需改动：

// 之前 (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. 开发环境

# 启动开发服务器
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。

---

📚 进阶文档

详细信息请查看：

• 📖 完整实现文档
• ✅ 交付清单
• 📋 合规性检查

---

🎓 最佳实践

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
状态: ✅ 生产就绪

祝您使用愉快! 🎉