# 呼叫中心-python

**Repository Path**: lxcwlong/callcenter-python

## Basic Information

- **Project Name**: 呼叫中心-python
- **Description**: python版本的呼叫中心系统，使用ai coding构建的
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-07
- **Last Updated**: 2026-08-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 呼叫中心管理系统 (callcenter-admin) - Python3 版本

## 📋 项目概览

本项目从 Java Spring Boot + MyBatis 呼叫中心管理系统 (`callcenter-admin`) 转换为 Python3 版本。

- **Java原始项目**: `g:\code\Wcli\callcenter\dev\callcenter-admin`
- **Python3 新项目**: `G:\code\Python\callcenter`
- **框架**: FastAPI (替代 Spring Boot) + SQLAlchemy (替代 MyBatis)
- **Python版本**: 3.10+
- **端口**: 8083

## 🏗️ 项目架构转换对照

| Java 模块 | Python 模块 | 说明 |
|-----------|------------|------|
| `AdminApplication.java` | `app/main.py` | 应用启动入口 |
| `application.yml` | `.env` + `app/config.py` | 配置管理 |
| `DruidFreeswitchConfig` / `DruidVpbxConfig` | `app/database.py` | 双数据源管理 |
| `FsAgentController` (/callcenter/fs/agent) | `app/routers/fs/agent.py` | 坐席管理API |
| `FsQueueController` (/callcenter/fs/queue) | `app/routers/fs/queue.py` | 队列管理API |
| `FsTierController` (/callcenter/fs/tier) | `app/routers/fs/tier.py` | 技能组管理API |
| 38个 `Sc*Controller` | `app/routers/sc/routes.py` | 业务系统API |
| `CcAgentService` 等 (VPBX) | `app/routers/vpbx/*.py` | VPBX子模块API |
| `FreeswitchEslService.java` | `app/services/esl_service.py` | ESL通信客户端 |
| MyBatis Mapper XML | SQLAlchemy ORM Models | 数据库操作 |
| `TableDataInfo` / `AjaxResult` | `app/schemas/__init__.py` | 响应模型 |

## 📁 项目目录结构

```
G:\code\Python\callcenter\
├── .env                          # 环境变量配置
├── requirements.txt              # Python 依赖
├── README.md                     # 项目说明
├── API.md                        # 接口文档
├── uploads/                      # 文件上传目录
└── app/
    ├── __init__.py
    ├── main.py                   # FastAPI 应用主入口 (对应 AdminApplication)
    ├── config.py                 # 配置管理 (对应 application.yml)
    ├── database.py               # 双数据源管理 (对应 DruidFreeswitchConfig + DruidVpbxConfig)
    ├── models/                   # 数据模型 (对应 Entity + Mapper)
    │   ├── __init__.py
    │   ├── fs_models.py          # FreeSwitch 表模型 (fs_agent, fs_queue, fs_tier...)
    │   ├── sc_models.py          # 业务系统模型 (sc_user, sc_work_order...共38个)
    │   └── vpbx_models.py        # VPBX子模块模型 (cc_agent, cc_queue...)
    ├── schemas/                  # Pydantic Schema (对应 DTO/VO)
    │   └── __init__.py           # AjaxResult, TableDataInfo, PageQuery
    ├── crud/                     # CRUD 操作 (对应 Service + Dao)
    │   ├── __init__.py
    │   └── base.py               # 通用CRUD基类 (泛型)
    ├── routers/                  # API 路由 (对应 Controller)
    │   ├── __init__.py
    │   ├── router_factory.py     # 路由工厂 (自动生成标准CRUD端点)
    │   ├── fs/                   # FreeSwitch路由
    │   │   ├── agent.py          # 坐席管理 (含ESL状态/同步接口)
    │   │   ├── queue.py          # 队列管理
    │   │   └── tier.py           # 技能组管理
    │   ├── vpbx/                 # VPBX路由
    │   │   ├── agent.py          # VPBX坐席
    │   │   ├── queue.py          # VPBX队列
    │   │   └── tier.py           # VPBX技能组
    │   └── sc/                   # 业务系统路由 (38个Controller)
    │       └── routes.py         # 全部SC业务路由 (用户/角色/工单/知识库...)
    ├── services/                 # 业务服务层
    │   ├── __init__.py
    │   └── esl_service.py        # FreeSwitch ESL客户端 (Socket/异步)
    └── utils/                    # 工具模块
        └── __init__.py           # PageUtils, SecurityUtils
```

## 🚀 快速开始

### 1. 环境要求

- Python 3.10+
- MySQL 5.7+ (需要 freeswitch 和 vpbx 两个数据库)
- Redis (可选，用于缓存/会话)
- FreeSwitch (可选，用于ESL相关功能)

### 2. 安装依赖

```bash
cd G:\code\Python\callcenter
pip install -r requirements.txt
```

### 3. 配置环境变量

编辑 `.env` 文件，根据实际环境修改数据库连接等配置：

```env
# 数据库连接
DB_FREESWITCH_HOST=192.168.10.121
DB_FREESWITCH_PORT=3306
DB_FREESWITCH_USER=root
DB_FREESWITCH_PASSWORD=hctel
DB_FREESWITCH_DATABASE=freeswitch

DB_VPBX_HOST=192.168.10.121
DB_VPBX_PORT=3306
DB_VPBX_USER=root
DB_VPBX_PASSWORD=hctel
DB_VPBX_DATABASE=vpbx

# 开发模式 (免登录)
APP_DEBUG=true
DEV_MODE=true
```

### 4. 启动服务

```bash
# 开发模式 (热重载)
python -m app.main

# 或使用 uvicorn 直接启动
uvicorn app.main:app --host 0.0.0.0 --port 8083 --reload
```

### 5. 访问文档

- **Swagger UI**: http://localhost:8083/docs
- **ReDoc**: http://localhost:8083/redoc
- **OpenAPI JSON**: http://localhost:8083/openapi.json

## 🔧 核心功能模块

### 1. FreeSwitch 管理模块 (fs/)
- **坐席管理** (`/callcenter/fs/agent`) - 坐席CRUD + ESL状态查询 + ESL同步
- **队列管理** (`/callcenter/fs/queue`) - 队列CRUD + ESL同步
- **技能组管理** (`/callcenter/fs/tier`) - 技能组CRUD + ESL同步

### 2. VPBX 子模块 (vpbx/)
- **坐席管理** (`/callcenter/vpbx/agent`) - VPBX坐席CRUD
- **队列管理** (`/callcenter/vpbx/queue`) - VPBX队列CRUD
- **技能组管理** (`/callcenter/vpbx/tier`) - VPBX技能组CRUD

### 3. 业务系统模块 (sc/) - 38个功能模块
- **基础系统**: 用户/角色/菜单/权限/部门/字典/功能权限管理
- **客户管理**: 客户/客户配置/配置扩展
- **通知公告**: 公告/用户公告关联
- **风险管控**: 黑名单管理
- **业务规则**: 分配规则管理
- **工单系统**: 工单/工单记录/工单回访
- **通信录**: 电话簿管理
- **呼出管理**: 外呼记录管理
- **知识库**: 知识库管理
- **满意度**: 评价事件管理
- **测评调查**: 测评管理/模板/内容/值域/人员/统计/项目计划
- **日程管理**: 日程/日程消息
- **即时通讯**: 聊天室/聊天内容
- **OA集成**: OA用户/OA部门/OA岗位

## 🔑 关键设计说明

### 双数据源架构
项目使用双数据源设计：
- **主数据源 (freeswitch)**: 存储FreeSwitch配置和业务系统数据
- **从数据源 (vpbx)**: 存储VPBX子模块数据

对应 Java 的 `DruidFreeswitchConfig` 和 `DruidVpbxConfig`，Python 版本在 `app/database.py` 中管理两个独立的 SQLAlchemy 引擎。

### 通用CRUD模式
所有API遵循统一的 CRUD 模式（对应 Java 的 BaseController 模式）：
- `GET /list` - 分页查询
- `GET /{id}` - ID查询详情
- `POST /` - 新增
- `PUT /` - 修改
- `DELETE /{ids}` - 删除(支持批量)

通过 `router_factory.py` 的 `register_crud_routes()` 函数自动生成。

### ESL通信
FreeSwitch ESL 客户端使用 Python 的 `asyncio` 实现异步 Socket 通信，替代 Java 的阻塞 Socket 方式，支持：
- ESL 连接认证
- API 命令发送
- 事件订阅
- 坐席/队列/技能组数据同步

### 开发模式
开发模式下（`DEV_MODE=true`），跳过 JWT 认证，方便本地开发和调试。生产环境需关闭开发模式并配置 JWT 认证。

## 📊 数据表清单 (44张表)

### FreeSwitch 库 (6张)
| 表名 | 模型类 | 说明 |
|------|--------|------|
| fs_agent | FsAgent | 坐席信息 |
| fs_queue | FsQueue | 队列配置 |
| fs_tier | FsTier | 技能组 |
| fs_callcenter | FsCallcenter | 呼叫中心配置 |
| fs_voicemenu | FsVoicemenu | 语音菜单 |
| cdr | CdrEntity | 通话记录 |

### VPBX 库 (6张)
| 表名 | 模型类 | 说明 |
|------|--------|------|
| cc_agent | CcAgent | VPBX坐席 |
| cc_queue | CcQueue | VPBX队列 |
| cc_tier | CcTier | VPBX技能组 |
| cc_evaluate | CcEvaluate | 评价记录 |
| cc_ivr | CcIvr | IVR配置 |
| cc_smart_match | CcSmartMatch | 智能匹配 |

### 业务系统 (32张)
列表详见 [API.md](API.md)

## ⚠️ 注意事项

1. **数据库兼容性**: 确保 MySQL 数据库支持 utf8mb4 字符集
2. **ESL依赖**: 如果 FreeSwitch 未运行，系统仍可正常启动，ESL相关功能不可用
3. **Redis可选**: Redis 当前仅作为可选缓存，系统核心功能不依赖 Redis
4. **生产部署**: 生产环境请务必：
   - 关闭 `DEV_MODE`
   - 配置强密码的 `JWT_SECRET_KEY`
   - 使用 Gunicorn + Uvicorn workers 部署
   - 配置 Nginx 反向代理

## 🔄 Java → Python 转换对照

| 功能 | Java 实现 | Python 实现 |
|------|----------|------------|
| Web框架 | Spring Boot 3.3.3 | FastAPI 0.115 |
| ORM | MyBatis + MyBatis-Plus | SQLAlchemy 2.0 |
| 数据库连接池 | Alibaba Druid | SQLAlchemy pool |
| 配置管理 | application.yml | .env + pydantic-settings |
| 响应模型 | TableDataInfo / AjaxResult | Pydantic BaseModel |
| ESL通信 | java.net.Socket (阻塞) | asyncio (异步) |
| 依赖注入 | @Autowired / @Resource | FastAPI Depends |
| API文档 | Swagger (SpringDoc) | 内置 OpenAPI + Swagger UI |
| 定时任务 | @Scheduled | APScheduler |
| JWT认证 | Spring Security + JWT | python-jose + 自定义依赖 |