# python-wechat-kf

微信客服 API 网页测试工具：监听用户消息、主动/被动发消息，消息存储到 PostgreSQL。

## 快速开始

### 1. 创建 PostgreSQL 数据库

```bash
createdb wechat_kf
```

### 2. 配置 .env

```bash
cp .env.example .env
```

编辑 `.env` 填入真实配置：

```env
# --- 企业微信基础信息（必填）---
# 企业 ID，在企业微信管理后台 - 我的企业 页面底部查看
CORPID=ww9f866d5bf5175e77

# 应用 Secret，在企业微信管理后台 - 微信客服 - 开发配置 中获取
SECRET=your_secret_here

# 客服账号 ID，在企业微信管理后台 - 微信客服 - 客服账号 详情页查看
OPEN_KFID=wkxxxxxxxxxxxxx

# --- 回调配置（可选，仅接收实时消息时需要）---
# 自定义 3-32 位字符串，与后台配置的回调 Token 一致
CALLBACK_TOKEN=my_token_123

# 企业微信后台随机生成的 43 位 EncodingAESKey
CALLBACK_AES_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# --- 数据库配置 ---
# 格式: postgresql+asyncpg://用户名:密码@主机:端口/数据库名
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/wechat_kf
```

**数据库连接字符串** 格式：
```
postgresql+asyncpg://用户名:密码@主机地址:端口/数据库名
```
如果需要修改用户名、密码、主机或数据库名，直接改这个连接字符串即可。

### 3. 安装依赖并启动

```bash
pip install -r requirements.txt
python run.py
```

访问 http://localhost:8000 即可看到聊天界面。

---

## CALLBACK_TOKEN 和 CALLBACK_AES_KEY 的使用

这两个参数用于 **微信回调消息的加解密**，只在需要接收实时消息推送时才需要配置。

### 配置流程

1. 登录 [企业微信管理后台](https://work.weixin.qq.com)
2. 进入 **微信客服** → 选中客服账号 → **开发配置**
3. 在回调配置中：
   - **Token**：自定义填一个 3-32 位字符串（如 `my_token_123`），同时写入 `.env` 的 `CALLBACK_TOKEN`
   - **EncodingAESKey**：点击"随机生成"，得到一个 **43 位字符串**，填入 `.env` 的 `CALLBACK_AES_KEY`
   - **回调 URL**：填写 `https://你的域名/webhook`（见下方本地测试方案）
4. 保存后微信会立刻发送 GET 请求到回调 URL 进行验证

### 如果不配回调

不配回调不影响以下功能：
- 点击页面的 **"同步拉取"** 按钮主动轮询获取消息
- 在页面中 **发送消息** 给客户

---

## 本地测试方案

回调模式要求 URL 必须是 **公网 HTTPS**。本地开发可以用以下工具：

### ngrok（推荐）

```bash
# 安装 ngrok 并启动
ngrok http 8000

# 会得到一个公网 URL，例如 https://abc123.ngrok.io
# 在微信管理后台填入 https://abc123.ngrok.io/webhook 即可
```

### 其他方案

| 方案 | 说明 |
|------|------|
| **ngrok** | 免费，一行命令，推荐 |
| **frp** | 需要一台有公网 IP 的服务器 |
| **localhost.run** | `ssh -R 80:localhost:8000 localhost.run` |
| **部署到公网服务器** | 直接部署到有 HTTPS 的服务器 |

### 不配回调也能测试

即使没有公网地址，也可以：
1. 启动应用 → 打开页面 → 点击 **"同步拉取"** 获取历史消息
2. 在输入框输入内容 → 点击 **"发送"** 主动给客户发消息
3. 这是**轮询模式**，不需要公网、不需要回调配置