修改页面结构
This commit is contained in:
409
docs/admin/SERVICE_QUICK_START.md
Normal file
409
docs/admin/SERVICE_QUICK_START.md
Normal file
@@ -0,0 +1,409 @@
|
||||
# 客服管理模块 - 快速开始指南
|
||||
|
||||
## 🎯 项目概述
|
||||
|
||||
客服管理模块是一套完整的客服系统前端实现，一致对标 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
|
||||
**状态**: ✅ 生产就绪
|
||||
|
||||
祝您使用愉快! 🎉
|
||||
Reference in New Issue
Block a user