# call-center

**Repository Path**: VictorInfo/call-center

## Basic Information

- **Project Name**: call-center
- **Description**: 阿里外呼中心调用DEMO
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-02-02
- **Last Updated**: 2026-02-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 呼叫中心模块 (Call Center Module)

## 概述

呼叫中心模块是基于阿里云外呼机器人服务构建的集成模块，提供完整的外呼功能管理。该模块封装了阿里云外呼机器人的核心API，提供了任务管理、实例管理、话术管理等功能，便于系统内其他模块集成使用。

## 功能特性

### 1. 任务组管理
- **创建外呼任务组**：通过API创建外呼任务组，支持指定实例、任务组名称、话术和策略
- **查询任务组列表**：根据实例ID查询所有相关的任务组信息

### 2. 外呼任务管理
- **批量分配任务**：支持批量创建外呼任务到指定的任务组
- **分配单个任务**：支持向指定任务组分配单个外呼任务，并可携带业务参考ID (Reference ID)
- **查询多个任务**：通过任务ID列表批量查询外呼任务信息
- **查询单个任务详情**：获取特定外呼任务的详细信息
- **按任务组查询任务**：根据任务组ID分页查询关联的外呼任务
- **按 Reference ID 查询**：支持通过业务参考 ID 在任务组内筛选外呼任务，便于业务系统关联查询

### 3. 实例管理
- **查询实例列表**：获取当前账户下的所有外呼机器人实例信息
- **过滤真实业务实例**：自动过滤掉预置实例和系统实例，仅返回真实业务实例

### 4. 话术管理
- **查询话术列表**：根据实例ID查询所有可用的话术信息
- **话术详情获取**：获取话术的详细信息包括NLU配置等

### 5. 录音管理
- **下载通话录音**：通过任务ID下载通话录音文件

## 技术架构

### 核心技术栈
- **Spring Boot**：作为基础框架
- **阿里云外呼机器人SDK**：集成阿里云外呼机器人服务
- **MyBatis-Plus**：提供分页功能
- **Swagger**：API文档生成

### 主要组件

#### Controller层
- [CallCenterController](./src/main/java/com/benetech/callcenter/controller/CallCenterController.java)：提供REST API接口

#### Service层
- [AliyunCallCenterService](./src/main/java/com/benetech/callcenter/service/AliyunCallCenterService.java)：核心业务逻辑实现

#### DTO层
- 各种数据传输对象，用于API请求和响应数据的封装

#### Config层
- [CallCenterConfig](./src/main/java/com/benetech/callcenter/config/CallCenterConfig.java)：模块配置类

## API端点

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | `/call-center/job-group` | 创建外呼任务组 |
| POST | `/call-center/assign-jobs` | 批量分配外呼任务 |
| POST | `/call-center/assign-single-job` | 分配单个外呼任务 |
| GET | `/call-center/jobs` | 批量查询外呼任务信息 |
| GET | `/call-center/instance/{instanceId}/job/{jobId}` | 查询单个外呼任务详情 |
| GET | `/call-center/instance/{instanceId}/task-result/{taskId}` | 根据 Task ID 获取对应结果信息 |
| GET | `/call-center/instance/{instanceId}/job-group/{jobGroupId}/jobs` | 根据 JobGroup ID 分页查询 Job 列表 |
| GET | `/call-center/instance/{instanceId}/job-group/{jobGroupId}/reference/{referenceId}` | 根据 Reference ID 查询外呼任务 |
| GET | `/call-center/instance/{instanceId}/recording/{taskId}` | 下载通话录音 |
| GET | `/call-center/instances` | 分页获取所有实例信息 |
| GET | `/call-center/instance/{instanceId}/job-groups` | 根据实例ID分页获取 JobGroup 列表 |
| GET | `/call-center/instance/{instanceId}/scripts` | 根据实例ID分页获取话术列表 |
| GET | `/call-center/instance/{instanceId}/scenarios` | 根据实例ID分页获取场景列表 |

## 配置说明

模块通过以下配置参数进行初始化：

```yaml
aliyun:
  call-center:
    access-key-id: # 阿里云访问密钥ID
    access-key-secret: # 阿里云访问密钥Secret
    instance-id: # 外呼机器人实例ID
    region-id: # 地域ID，默认为cn-shanghai
    endpoint: # 外呼机器人服务域名，默认为outboundbot.cn-shanghai.aliyuncs.com
```

## 使用示例

### 创建外呼任务组
```bash
POST /call-center/job-group
Parameters:
- instanceId: 实例外呼机器人实例ID
- jobGroupName: 任务组名称
- scriptId: 话术ID
- strategyJson: 策略JSON（可选）
```

### 分配单个外呼任务
```bash
POST /call-center/assign-single-job
Parameters:
- instanceId: 实例ID
- jobGroupId: 任务组ID
Body (SingleJobDto):
{
  "phoneNumber": "13800138000",
  "contactName": "张三",
  "referenceId": "BIZ_001",
  "scenarioId": "SCENARIO_001",
  "extras": {"key1": "value1"}
}
```

### 按 Reference ID 查询任务
```bash
GET /call-center/instance/{instanceId}/job-group/{jobGroupId}/reference/{referenceId}
Parameters:
- pageNum: 页码
- pageSize: 每页数量
```

### 查询实例下的所有话术
```bash
GET /call-center/instance/{instanceId}/scripts
Parameters:
- pageNum: 页码
- pageSize: 每页数量
```

### 查询实例下的所有场景
```bash
GET /call-center/instance/{instanceId}/scenarios
Parameters:
- pageNum: 页码
- pageSize: 每页数量
```

## 错误处理

- 模块实现了完善的异常处理机制
- 使用[ServiceException](../common/common-core/src/main/java/com/benetech/common/core/exception/ServiceException.java)处理业务异常
- 记录详细的错误日志便于问题排查

## 安全性

- 使用阿里云认证机制确保API调用安全
- 敏感配置信息（AK/SK）通过配置文件管理
- 支持Spring Security集成

## 扩展性

模块设计遵循高内聚低耦合原则，易于扩展：
- 可轻松添加新的外呼机器人功能
- 支持对接其他云服务商的外呼服务
- 统一的接口设计便于维护

## 开发指南

### 添加新功能
1. 在[AliyunCallCenterService](./src/main/java/com/benetech/callcenter/service/AliyunCallCenterService.java)中添加业务方法
2. 在[CallCenterController](./src/main/java/com/benetech/callcenter/controller/CallCenterController.java)中暴露API接口
3. 如需要，创建相应的DTO类

### 测试
模块提供了完整的API测试接口，可通过Swagger UI进行功能验证。