# AI客服-微信mock

**Repository Path**: clementdik/ai_customer_service_wx_mock

## Basic Information

- **Project Name**: AI客服-微信mock
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-21
- **Last Updated**: 2025-08-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Mock微信接口服务

基于Flask框架实现的企业微信API Mock服务，用于本地开发和调试。

## 功能特性

- 完全模拟企业微信客服API接口
- 支持完整的业务逻辑和状态管理
- 详细的日志记录和监控
- 数据持久化存储
- 健康检查和状态监控

## 支持的接口

1. **获取访问令牌** - `/cgi-bin/gettoken`
2. **获取客服账号列表** - `/cgi-bin/kf/account/list`
3. **获取客服消息** - `/cgi-bin/kf/sync_msg`
4. **获取客服会话列表** - `/cgi-bin/kf/sync_service_state`
5. **检查会话状态** - `/cgi-bin/kf/service_state/get`
6. **会话状态变更** - `/cgi-bin/kf/service_state/trans`
7. **发送客服消息** - `/cgi-bin/kf/send_msg`
8. **获取客服人员列表** - `/cgi-bin/kf/servicer/list`
9. **Webhook模拟器** - `/webhook/simulate` (模拟客户输入并触发webhook回调)
10. **Webhook测试** - `/webhook/test` (测试webhook接口)
11. **Webhook验证** - `/webhook/verify` (验证webhook URL)

## 安装和运行

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 配置环境变量（可选）

```bash
# Mock配置
export MOCK_WX_CORP_ID=wxc4c1ad1d26dc0daf
export MOCK_WX_CORP_SECRET=mock_secret_456
export MOCK_OPEN_KF_ID=mock_kf_001

# 服务器配置
export MOCK_WX_HOST=localhost
export MOCK_WX_PORT=8080
export MOCK_WX_DEBUG=true

# 日志配置
export MOCK_LOG_LEVEL=INFO
export MOCK_LOG_FILE=./logs/mock_wx_api.log
```

### 3. 启动服务

```bash
python app.py
```

服务将在 `http://localhost:8084` 启动。

## 配置说明

### 环境变量

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| MOCK_WX_CORP_ID | wxc4c1ad1d26dc0daf | 企业ID |
| MOCK_WX_CORP_SECRET | mock_secret_456 | 应用密钥 |
| MOCK_OPEN_KF_ID | mock_kf_001 | 客服账号ID |
| MOCK_WX_HOST | localhost | 服务地址 |
| MOCK_WX_PORT | 8084 | 服务端口 |
| MOCK_WX_DEBUG | true | 调试模式 |
| MOCK_LOG_LEVEL | INFO | 日志级别 |
| MOCK_LOG_FILE | ./logs/mock_wx_api.log | 日志文件路径 |
| WEBHOOK_URL | http://localhost:5005/webhook | Webhook回调地址 |
| WX_TOKEN | Sv3mVW1LOIU | 微信Token |
| WX_AES_KEY | NgHrjQdRw46FQIyTedXxJu6GrjqcoewHWlCQVLA76Ai | 微信EncodingAESKey |
| WEBHOOK_ENABLE_CALLBACK | true | 是否启用webhook回调 |

### 配置文件

可以通过 `config.json` 文件进行配置，支持以下配置项：

```json
{
  "server": {
    "host": "localhost",
    "port": 8084,
    "debug": true
  },
  "mock": {
    "corp_id": "wxc4c1ad1d26dc0daf",
    "corp_secret": "mock_secret_456",
    "open_kf_id": "mock_kf_001",
    "token_expires": 7200,
    "enable_logging": true
  },
  "webhook": {
    "url": "http://localhost:5005/webhook",
    "token": "Sv3mVW1LOIU",
    "encoding_aes_key": "NgHrjQdRw46FQIyTedXxJu6GrjqcoewHWlCQVLA76Ai",
    "enable_callback": true
  },
  "data": {
    "storage_type": "memory",
    "file_path": "./mock_data.json"
  },
  "logging": {
    "level": "INFO",
    "file": "./logs/mock_wx_api.log"
  }
}
```

## 接口使用示例

### 1. 获取访问令牌

```bash
curl "http://localhost:8084/cgi-bin/gettoken?corpid=wxc4c1ad1d26dc0daf&corpsecret=mock_secret_456"
```

### 2. 获取客服账号列表

```bash
curl "http://localhost:8084/cgi-bin/kf/account/list?access_token=mock_access_token_123456789"
```

### 3. 发送客服消息

```bash
curl -X POST "http://localhost:8084/cgi-bin/kf/send_msg?access_token=mock_access_token_123456789" \
  -H "Content-Type: application/json" \
  -d '{
    "open_kfid": "mock_kf_001",
    "touser": "mock_user_001",
    "msgtype": "text",
    "text": {
      "content": "您好，我是客服助手，有什么可以帮助您的吗？"
    }
  }'
```

### 4. 检查会话状态

```bash
curl -X POST "http://localhost:8084/cgi-bin/kf/service_state/get?access_token=mock_access_token_123456789" \
  -H "Content-Type: application/json" \
  -d '{
    "external_userid": "mock_user_001",
    "open_kfid": "mock_kf_001"
  }'
```

### 5. 模拟客户输入 (Webhook)

支持多种方式指定用户ID：

#### 5.1 通过URL参数指定用户ID

```bash
curl -X POST "http://localhost:8084/webhook/simulate?user_id=customer_001" \
  -H "Content-Type: application/json" \
  -d '{
    "msgtype": "text",
    "content": "你好，我是客户001，需要帮助"
  }'
```

#### 5.2 通过请求体指定用户ID

```bash
curl -X POST "http://localhost:8084/webhook/simulate" \
  -H "Content-Type: application/json" \
  -d '{
    "external_userid": "customer_002",
    "open_kfid": "mock_kf_001",
    "msgtype": "text",
    "content": "你好，我是客户002，有问题咨询"
  }'
```

#### 5.3 自动生成用户ID

```bash
curl -X POST "http://localhost:8084/webhook/simulate" \
  -H "Content-Type: application/json" \
  -d '{
    "msgtype": "text",
    "content": "你好，我是自动生成的用户"
  }'
```

#### 5.4 批量模拟多个用户

```bash
curl -X POST "http://localhost:8084/webhook/simulate/batch" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "external_userid": "batch_user_001",
        "msgtype": "text",
        "content": "批量消息1 - 用户001"
      },
      {
        "external_userid": "batch_user_002",
        "msgtype": "text",
        "content": "批量消息2 - 用户002"
      },
      {
        "msgtype": "text",
        "content": "批量消息3 - 自动生成用户"
      }
    ]
  }'
```

#### 5.5 用户管理功能

获取活跃用户列表：
```bash
curl http://localhost:8084/webhook/users
```

获取用户消息历史：
```bash
curl http://localhost:8084/webhook/users/customer_001/messages
```

#### 5.6 用户ID规则

- **长度限制**：3-64个字符
- **字符限制**：不能包含 `<`, `>`, `&`, `"`, `'`, `\`, `/`, `|`, `?`, `*`, `:`, `;` 等特殊字符
- **自动生成**：如果不指定用户ID，系统会自动生成格式为 `mock_user_xxxxxxxx` 的用户ID
- **批量限制**：批量模拟最多支持10个消息

### 6. 测试Webhook接口

```bash
curl http://localhost:8084/webhook/test
```

### 7. 验证Webhook URL

```bash
curl -X POST "http://localhost:8084/webhook/verify" \
  -H "Content-Type: application/json" \
  -d '{
    "echostr": "test_echostr_123"
  }'
```

## 监控接口

### 健康检查

```bash
curl http://localhost:8084/health
```

### 状态监控

```bash
curl http://localhost:8084/status
```

## 日志管理

服务会自动创建 `logs` 目录并生成日志文件：

- 日志文件：`./logs/mock_wx_api.log`
- 日志轮转：每个文件最大10MB，保留5个备份
- 日志级别：可通过环境变量或配置文件调整

## 数据管理

### 数据存储

- 支持内存存储（默认）
- 支持文件存储（JSON格式）
- 数据自动持久化到 `mock_data.json`

### 默认数据

服务启动时会自动创建以下默认数据：

- 客服账号：`mock_kf_001`, `mock_kf_002`
- 客服人员：`mock_servicer_001`, `mock_servicer_002`
- 示例会话：`mock_user_001`
- 示例消息：欢迎消息

## 错误处理

服务支持完整的错误码和错误处理：

| 错误码 | 说明 |
|--------|------|
| 0 | 成功 |
| 40001 | 不合法的secret参数 |
| 40014 | 不合法的access_token |
| 41001 | 缺少参数 |
| 42001 | access_token超时 |
| 95016 | 不允许状态转移 |
| 95018 | 会话状态无效 |

## 开发说明

### 项目结构

```
mock_WX/
├── app.py                 # 主应用文件
├── config.json           # 配置文件
├── requirements.txt      # 依赖文件
├── README.md            # 说明文档
├── postman_collection.json # Postman测试集合
├── api/                 # 接口模块
│   ├── __init__.py
│   ├── gettoken.py      # 获取访问令牌
│   ├── kf_account_list.py
│   ├── kf_sync_msg.py
│   ├── kf_sync_service_state.py
│   ├── kf_service_state_get.py
│   ├── kf_service_state_trans.py
│   ├── kf_send_msg.py
│   ├── kf_servicer_list.py
│   └── webhook_simulator.py # Webhook模拟器
├── utils/               # 工具模块
│   ├── __init__.py
│   ├── config.py        # 配置管理
│   ├── logger.py        # 日志管理
│   └── data_manager.py  # 数据管理
└── logs/                # 日志目录
```

### 扩展开发

每个接口都使用独立的文件，便于维护和扩展：

1. 在 `api/` 目录下创建新的接口文件
2. 在 `app.py` 中注册新的蓝图
3. 在 `utils/data_manager.py` 中添加相应的数据管理方法

## 许可证

MIT License