229 lines
6.4 KiB
Markdown
229 lines
6.4 KiB
Markdown
# 工单运营闭环 SOP
|
||
|
||
> 版本：v1.0 | 状态：已生效
|
||
> 关联：tech/INTERFACE.md、PRODUCTION_PHASE1_STATUS.md
|
||
|
||
---
|
||
|
||
## 1. 工单生命周期
|
||
|
||
```
|
||
用户触发转人工
|
||
→ 工单创建
|
||
→ 客服接单（assign）
|
||
→ 客服处理
|
||
→ 客服解决（resolve）
|
||
→ 客服/主管关闭（close）
|
||
→ 用户满意度反馈（可选）
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 各状态定义
|
||
|
||
| 状态 | 含义 | 触发条件 | 当前是否落地 |
|
||
|------|------|----------|--------------|
|
||
| `open` | 待接单 | 转人工触发工单创建 | ✅ 已落地 |
|
||
| `assigned` | 已分配 | 客服主动接单或系统分配 | ✅ 已落地 |
|
||
| `resolved` | 已给出处理结论，等待最终归档 | 已分配工单处理完毕后调用 `resolve` | ✅ 已落地 |
|
||
| `closed` | 已最终关闭，不允许再继续流转 | 仅 `resolved` 工单可调用 `close` | ✅ 已落地 |
|
||
|
||
### 2.1 状态流转规则
|
||
|
||
| 当前状态 | 允许动作 | 下一个状态 | 不允许动作 |
|
||
|----------|----------|------------|------------|
|
||
| `open` | `assign` | `assigned` | `resolve` / `close` |
|
||
| `assigned` | `resolve` | `resolved` | 重复 `assign` / 直接 `close` |
|
||
| `resolved` | `close` | `closed` | 重复 `resolve` / 重复 `assign` |
|
||
| `closed` | 无 | 无 | `assign` / `resolve` / `close` |
|
||
|
||
---
|
||
|
||
## 3. 触发转人工的条件
|
||
|
||
### 3.1 自动转人工（系统触发）
|
||
|
||
以下意图识别结果会**自动创建工单**（代码：`internal/service/dialog/service.go`）：
|
||
|
||
- 退款请求（intent = refund / 退款）
|
||
- 敏感内容（intent.sensitive = true）
|
||
|
||
### 3.2 手动转人工
|
||
|
||
- 用户发送"人工客服"、"转人工"等关键词（需 RAG 识别后触发）
|
||
- 会话 turnCount 超过阈值（待实现）
|
||
|
||
---
|
||
|
||
## 4. 工单创建流程
|
||
|
||
### 4.1 当前已落地（最小闭环）
|
||
|
||
**接口**：`POST /api/v1/customer-service/sessions/{session_id}/handoff`
|
||
|
||
**代码**：`internal/service/dialog/service.go` → `handoff_service.CreateTicket`
|
||
|
||
**流程**：
|
||
1. 对话服务检测到需要转人工
|
||
2. 创建 ticket 记录（session_id, user_id, priority, handoff_reason）
|
||
3. ticket 状态 = `open`
|
||
4. 触发审计日志写入
|
||
|
||
**缺失项**：
|
||
- 工单创建时**未记录上下文快照**（`context_snapshot` 字段为空）
|
||
- 排队位置**未实现**（用户无法查询前面还有多少人）
|
||
- 工单创建**未主动通知**客服（无消息推送链路）
|
||
|
||
### 4.2 待落地项
|
||
|
||
| 缺失项 | 优先级 | 说明 |
|
||
|--------|--------|------|
|
||
| 工单创建时上下文快照 | P0 | 用于客服接手时了解会话历史 |
|
||
| 排队位置查询 API | P1 | `GET /tickets/queue-position` |
|
||
| 客服新工单通知 | P1 | 飞书/邮件/站内信通知 |
|
||
| 客服回复用户链路 | P1 | 人工消息推送回用户 |
|
||
|
||
---
|
||
|
||
## 5. 工单分配流程
|
||
|
||
### 5.1 已落地
|
||
|
||
**接口**：`POST /api/v1/customer-service/tickets/{id}/assign?agent_id={agent_id}`
|
||
|
||
**代码**：`internal/http/handlers/ticket_handler.go` → `POST /tickets/{id}/assign`
|
||
|
||
**流程**：
|
||
1. 客服调用 assign 接口
|
||
2. 更新 ticket.status = `assigned`，ticket.assigned_to = agent_id
|
||
3. 写入审计日志（✅ 已落地：调用 `TicketWorkflowStore.writeAudit`）
|
||
|
||
**缺失项**：
|
||
- 工单状态流转审计 ✅ 已落地（`TicketWorkflowStore.writeAudit` 在 assign 时调用）
|
||
|
||
---
|
||
|
||
## 6. 工单解决流程
|
||
|
||
### 6.1 已落地
|
||
|
||
**接口**：`POST /api/v1/customer-service/tickets/{id}/resolve?resolution={resolution}`
|
||
|
||
**流程**：
|
||
1. 已接单工单处理完毕后调用 resolve
|
||
2. 更新 ticket.status = `resolved`，ticket.resolution = resolution
|
||
3. 写入审计日志（✅ 已落地：调用 `TicketWorkflowStore.writeAudit`）
|
||
4. `resolved` 表示已经有处理结论，但尚未最终关闭
|
||
|
||
---
|
||
|
||
## 7. 工单关闭流程
|
||
|
||
### 7.1 当前状态
|
||
|
||
**已落地**：`TicketWorkflowStore.Close` 接口已实现，支持显式关闭工单。
|
||
|
||
**语义定义**：
|
||
- `resolve` = 客服确认已给出处理结论，工单进入 `resolved`
|
||
- `close` = 对 `resolved` 工单做最终归档，工单进入 `closed`
|
||
- 未 `resolved` 的工单不能直接 `close`
|
||
- `closed` 工单不能再次 `resolve`
|
||
|
||
### 7.2 返回语义
|
||
|
||
| 场景 | HTTP | 错误码 |
|
||
|------|------|--------|
|
||
| 工单不存在 | `404` | `CS_TICKET_4001` |
|
||
| 非法 `resolve` 状态流转 | `409` | `CS_TICKET_4092` |
|
||
| 非法 `close` 状态流转 | `409` | `CS_TICKET_4093` |
|
||
|
||
---
|
||
|
||
## 8. 客服工作台操作规范（API 层）
|
||
|
||
受保护接口必须携带：
|
||
|
||
- `X-CS-Actor-ID`
|
||
- `X-CS-Actor-Role`
|
||
|
||
### 8.1 班次开始
|
||
|
||
1. 调用 `GET /api/v1/customer-service/tickets?status=open` 查看当前待接单工单
|
||
2. 按 priority（ P1 > P2 > P3）和创建时间排序
|
||
|
||
### 8.2 接单
|
||
|
||
```bash
|
||
curl -X POST "https://{host}/api/v1/customer-service/tickets/{ticket_id}/assign?agent_id={agent_id}"
|
||
```
|
||
|
||
成功后工单状态变为 `assigned`
|
||
|
||
### 8.3 处理与解决
|
||
|
||
```bash
|
||
curl -X POST "https://{host}/api/v1/customer-service/tickets/{ticket_id}/resolve?resolution={解决说明}"
|
||
```
|
||
|
||
成功后工单状态变为 `resolved`。
|
||
|
||
### 8.4 最终关闭
|
||
|
||
```bash
|
||
curl -X POST "https://{host}/api/v1/customer-service/tickets/{ticket_id}/close?resolution={最终结论}"
|
||
```
|
||
|
||
只有 `resolved` 工单可以执行该操作，成功后状态变为 `closed`。
|
||
|
||
### 8.5 工单列表查询
|
||
|
||
```bash
|
||
# 查看所有 open 工单
|
||
curl "https://{host}/api/v1/customer-service/tickets?status=open"
|
||
|
||
# 查看指定客服的工单
|
||
curl "https://{host}/api/v1/customer-service/tickets?assigned_to={agent_id}"
|
||
|
||
# 查看统计
|
||
curl "https://{host}/api/v1/customer-service/tickets/stats"
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 用户侧体验
|
||
|
||
### 9.1 转人工后用户感知
|
||
|
||
**当前已落地**：用户发送敏感/退款意图 → 收到机器人回复"已为您转接人工客服，请稍候"
|
||
|
||
**待落地**：
|
||
- 排队位置（如"前面还有 3 位在等待"）
|
||
- 人工客服接单通知
|
||
- 人工处理进度更新
|
||
- 解决后的满意度评价
|
||
|
||
---
|
||
|
||
## 10. SOP 执行检查单
|
||
|
||
### 客服班次检查
|
||
|
||
- [ ] 登录运营后台，查看当前 open 工单数量
|
||
- [ ] 按 P1优先原则接单
|
||
- [ ] 处理完毕后调用 resolve 接口
|
||
- [ ] 如遇无法解决的工单，升级 Team Lead
|
||
|
||
### 异常处理
|
||
|
||
- [ ] 工单 assign 后长时间（> 2h）未 resolve → 系统告警（待实现）/ 人工巡检
|
||
- [ ] 同一用户连续创建 > 3 个 open 工单 → 异常标记，人工复核
|
||
- [ ] 工单创建失败（服务异常） → 降级：保留内存记录 → 恢复后补录
|
||
|
||
---
|
||
|
||
## 11. 当前版本状态
|
||
|
||
- **本文档版本**：v1.0
|
||
- **生效日期**：2026-04-30
|
||
- **下次审查**：灰度阶段复盘
|