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

## 🎯 项目概述

客服管理模块是一套完整的客服系统前端实现，一致对标 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  
**状态**: ✅ 生产就绪

祝您使用愉快! 🎉
