cf46b27610
P0-1 (limits.go): Allow()方法改为全程使用写锁保护counters map读写，避免RLock写入时的data race P0-2 (ticket_workflow.go+ticket_handler.go): Assign/Resolve/Close操作先查询ticket存在性和状态，返回明确的CS_TICKET_4001/CS_TKT_4002/CS_TICKET_4092/CS_TICKET_4093错误码，handler根据错误前缀路由HTTP状态码 P1-1 (ticket_store.go): 移除GetStats中3处手动rows.Close()，只保留defer Close()
199 lines
5.6 KiB
Markdown
199 lines
5.6 KiB
Markdown
# 客服运营后台需求说明
|
||
|
||
> 版本：v1.0 | 状态：已生效
|
||
> 关联：tech/INTERFACE.md、PRODUCTION_PHASE1_STATUS.md
|
||
|
||
---
|
||
|
||
## 1. 概述
|
||
|
||
客服运营后台是客服团队日常操作的核心工具，提供工单管理、会话查询、运营统计等能力。本文档定义生产一期的后台需求范围与接口规范。
|
||
|
||
---
|
||
|
||
## 2. 当前已落地的后台能力
|
||
|
||
### 2.1 工单管理（API 层）
|
||
|
||
| 功能 | 接口 | 状态 | 代码位置 |
|
||
|------|------|------|----------|
|
||
| 工单列表 | `GET /api/v1/customer-service/tickets` | ✅ 已落地 | `internal/http/router.go` |
|
||
| 工单详情 | `GET /api/v1/customer-service/tickets/{id}` | ✅ 已落地 | `internal/http/router.go` |
|
||
| 工单分配 | `POST /api/v1/customer-service/tickets/{id}/assign` | ✅ 已落地 | `internal/http/router.go` |
|
||
| 工单解决 | `POST /api/v1/customer-service/tickets/{id}/resolve` | ✅ 已落地 | `internal/http/router.go` |
|
||
| 工单关闭 | `POST /api/v1/customer-service/tickets/{id}/close` | ✅ 已落地 | `internal/store/postgres/ticket_workflow.go` |
|
||
| 工单统计 | `GET /api/v1/customer-service/tickets/stats` | ❌ 未落地（无独立 stats endpoint） | — |
|
||
|
||
### 2.2 健康检查
|
||
|
||
| 功能 | 接口 | 状态 |
|
||
|------|------|------|
|
||
| 存活检查 | `GET /actuator/live` | ✅ 已落地 |
|
||
| 就绪检查 | `GET /actuator/ready` | ✅ 已落地（含 PostgreSQL 依赖检查） |
|
||
| 健康检查 | `GET /actuator/health` | ✅ 已落地 |
|
||
|
||
---
|
||
|
||
## 3. 运营后台需求清单（生产一期范围）
|
||
|
||
### 3.1 核心需求（生产一期必须落地）
|
||
|
||
#### P0：工单运营视图
|
||
|
||
**需求描述**：客服人员可通过后台看到所有工单，并执行分配/解决操作。
|
||
|
||
**已落地**：
|
||
- 工单列表（按 status / assigned_to / priority 过滤）
|
||
- 工单分配（assign）
|
||
- 工单解决（resolve）
|
||
- 工单统计（总计、各状态数量）
|
||
|
||
**已收口 P0 缺口**：
|
||
- ✅ 工单状态流转审计（assign/resolve/close 均通过 `TicketWorkflowStore.writeAudit` 写入审计日志）
|
||
- ✅ 工单关闭语义（resolve=已解决关闭；另有独立 close 接口支持显式关闭）
|
||
|
||
#### P1：转人工原因分析
|
||
|
||
**需求描述**：运营团队需要看到转人工的原因分布，用于优化机器人回答质量。
|
||
|
||
**当前状态**：代码中 `handoff_service.CreateTicket` 记录了 `handoff_reason`，但**无专门的后台聚合接口**。
|
||
|
||
**待实现**：
|
||
- `GET /api/v1/customer-service/admin/handoff-reasons` — 按原因聚合统计
|
||
- 关联 `tech/INTERFACE.md` 中已定义的 `/admin/handoff-reasons` 接口
|
||
|
||
#### P1：会话历史查看
|
||
|
||
**需求描述**：客服处理工单时需要查看用户完整的对话历史。
|
||
|
||
**当前状态**：`GET /api/v1/customer-service/sessions/{id}/messages` 接口**已定义但未完全落地**。
|
||
|
||
---
|
||
|
||
### 3.2 延伸需求（生产一期明确排除）
|
||
|
||
以下功能不在生产一期范围内：
|
||
|
||
| 功能 | 排除原因 |
|
||
|------|----------|
|
||
| 知识库 CRUD / 发布 / 审核 | Phase 4 才落地 |
|
||
| WebSocket 实时会话 | Phase 4 才落地 |
|
||
| 客服排班 / 考勤 | 独立系统 |
|
||
| 用户满意度评价 | P1 待落地 |
|
||
| 质检 / 录音存档 | 独立系统 |
|
||
| 多租户隔离 | 后续版本 |
|
||
|
||
---
|
||
|
||
## 4. 接口详细说明
|
||
|
||
### 4.1 工单列表 `GET /api/v1/customer-service/tickets`
|
||
|
||
**查询参数**：
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `status` | string | 过滤状态：`open`、`assigned`、`resolved`、`closed` |
|
||
| `assigned_to` | string | 过滤客服 |
|
||
| `priority` | string | 过滤优先级：`P1`、`P2`、`P3` |
|
||
| `page` | int | 页码（默认 1） |
|
||
| `page_size` | int | 每页条数（默认 20，最大 100） |
|
||
|
||
**响应**：
|
||
|
||
```json
|
||
{
|
||
"tickets": [
|
||
{
|
||
"id": "uuid",
|
||
"session_id": "string",
|
||
"user_id": "string",
|
||
"priority": "P1",
|
||
"status": "open",
|
||
"handoff_reason": "refund_request",
|
||
"assigned_to": null,
|
||
"resolution": null,
|
||
"created_at": "2026-04-30T10:00:00Z",
|
||
"updated_at": "2026-04-30T10:00:00Z"
|
||
}
|
||
],
|
||
"total": 50,
|
||
"page": 1,
|
||
"page_size": 20
|
||
}
|
||
```
|
||
|
||
### 4.2 工单分配 `POST /api/v1/customer-service/tickets/{id}/assign`
|
||
|
||
**请求**：
|
||
- Query 参数：`agent_id`（必填）
|
||
|
||
**错误码**：
|
||
- `CS_TKT_4001`：工单不存在（404）
|
||
- `CS_TKT_4002`：工单已被分配（409）
|
||
- `CS_AUTH_4001`：越权访问（403）
|
||
|
||
### 4.3 工单解决 `POST /api/v1/customer-service/tickets/{id}/resolve`
|
||
|
||
**请求**：
|
||
- Query 参数：`resolution`（必填，说明解决方式）
|
||
|
||
### 4.4 工单统计 `GET /api/v1/customer-service/tickets/stats`
|
||
|
||
**响应**：
|
||
|
||
```json
|
||
{
|
||
"total": 100,
|
||
"open": 15,
|
||
"assigned": 30,
|
||
"resolved": 55,
|
||
"by_priority": {
|
||
"P1": 20,
|
||
"P2": 50,
|
||
"P3": 30
|
||
},
|
||
"avg_resolution_time_minutes": 45
|
||
}
|
||
```
|
||
|
||
### 4.5 转人工原因统计 `GET /api/v1/customer-service/admin/handoff-reasons`
|
||
|
||
**响应**：
|
||
|
||
```json
|
||
{
|
||
"reasons": [
|
||
{ "reason": "refund_request", "count": 45, "percentage": 35 },
|
||
{ "reason": "sensitive_content", "count": 30, "percentage": 23 },
|
||
{ "reason": "manual_request", "count": 25, "percentage": 19 },
|
||
{ "reason": "unknown", "count": 29, "percentage": 23 }
|
||
],
|
||
"total": 129
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 后台权限模型
|
||
|
||
### 5.1 角色定义
|
||
|
||
| 角色 | 权限 |
|
||
|------|------|
|
||
| `agent` | 查看自己被分配的工单、执行 assign/resolve |
|
||
| `supervisor` | 查看所有工单、查看统计数据、转人工原因分析 |
|
||
| `admin` | 所有权限 |
|
||
|
||
### 5.2 当前状态
|
||
|
||
生产一期**权限模型未落地**，所有接口无鉴权。Phase 4 运营后台才需要完整的 RBAC。
|
||
|
||
---
|
||
|
||
## 6. 当前版本状态
|
||
|
||
- **本文档版本**：v1.0
|
||
- **生效日期**：2026-04-30
|
||
- **下次审查**：Phase 4 开始前
|