194 lines
4.6 KiB
Markdown
194 lines
4.6 KiB
Markdown
# 企业微信回调本地测试指南
|
||
|
||
## 前置条件
|
||
|
||
1. 已配置企业微信后台（Token、EncodingAESKey、回调 URL）
|
||
2. 已配置 `.env` 文件中的企业微信相关参数
|
||
3. 后端服务已启动：`docker compose up -d backend`
|
||
|
||
## 测试方法
|
||
|
||
### 方法 1：使用企业微信官方测试工具（推荐）
|
||
|
||
企业微信提供了在线测试工具，可以模拟回调请求：
|
||
|
||
1. 访问企业微信管理后台
|
||
2. 进入 **自建应用** → **接收消息** → **调试工具**
|
||
3. 输入测试参数，生成测试请求
|
||
4. 使用 curl 或 Postman 发送请求到本地服务
|
||
|
||
### 方法 2：使用 ngrok 暴露本地服务
|
||
|
||
1. **安装 ngrok**：https://ngrok.com/
|
||
|
||
2. **启动 ngrok**：
|
||
```bash
|
||
ngrok http 8000
|
||
```
|
||
|
||
3. **获取公网 URL**：例如 `https://abc123.ngrok.io`
|
||
|
||
4. **配置企微后台**：
|
||
- 回调 URL：`https://abc123.ngrok.io/api/wecom/callback`
|
||
- Token 和 EncodingAESKey 与 `.env` 一致
|
||
|
||
5. **保存配置**：企微会自动发送 GET 请求校验
|
||
|
||
6. **发送测试消息**：在企业微信中向应用发送消息
|
||
|
||
### 方法 3：手动构造测试请求（高级）
|
||
|
||
**注意**：需要真实的签名和加密数据，通常从企微后台的实际请求中获取。
|
||
|
||
#### GET 请求测试
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8000/api/wecom/callback?msg_signature=xxx×tamp=xxx&nonce=xxx&echostr=xxx"
|
||
```
|
||
|
||
**预期响应**：返回解密后的 `echostr` 明文
|
||
|
||
#### POST 请求测试
|
||
|
||
```bash
|
||
curl -X POST "http://localhost:8000/api/wecom/callback?msg_signature=xxx×tamp=xxx&nonce=xxx" \
|
||
-H "Content-Type: application/xml" \
|
||
-d '<xml><Encrypt><![CDATA[加密后的消息XML]]></Encrypt></xml>'
|
||
```
|
||
|
||
**预期响应**：返回加密后的回复 XML
|
||
|
||
## 验证步骤
|
||
|
||
### 1. 检查 GET 校验日志
|
||
|
||
```bash
|
||
docker compose logs backend | grep "wecom verify"
|
||
```
|
||
|
||
**成功日志示例**：
|
||
```json
|
||
{
|
||
"level": "INFO",
|
||
"message": "wecom verify success",
|
||
"trace_id": "abc123",
|
||
"echostr_length": 43
|
||
}
|
||
```
|
||
|
||
### 2. 检查 POST 回调日志
|
||
|
||
```bash
|
||
docker compose logs backend | grep "wecom message"
|
||
```
|
||
|
||
**成功日志示例**：
|
||
```json
|
||
{
|
||
"level": "INFO",
|
||
"message": "wecom message received",
|
||
"trace_id": "abc123",
|
||
"external_userid": "wmxxxxx",
|
||
"msgid": "1234567890",
|
||
"msg_type": "text",
|
||
"content_summary": "你好，我想咨询一下..."
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"level": "INFO",
|
||
"message": "wecom reply sent",
|
||
"trace_id": "abc123",
|
||
"external_userid": "wmxxxxx",
|
||
"msgid": "1234567890",
|
||
"reply_summary": "已收到：你好，我想咨询一下..."
|
||
}
|
||
```
|
||
|
||
### 3. 检查数据库
|
||
|
||
```bash
|
||
# 进入数据库容器
|
||
docker compose exec db psql -U wecom -d wecom_ai
|
||
|
||
# 查询会话
|
||
SELECT id, external_user_id, status, created_at FROM chat_sessions;
|
||
|
||
# 查询消息
|
||
SELECT id, session_id, role, content, created_at FROM messages ORDER BY created_at DESC LIMIT 10;
|
||
```
|
||
|
||
### 4. 在企业微信中验证
|
||
|
||
- 发送消息后，应收到回复：`已收到：{你发送的消息}`
|
||
- 如果未收到回复，检查后端日志中的错误信息
|
||
|
||
## 常见错误排查
|
||
|
||
### 错误 1：GET 校验失败
|
||
|
||
**日志**：`wecom verify failed`
|
||
|
||
**可能原因**：
|
||
- Token 不匹配
|
||
- EncodingAESKey 不匹配
|
||
- 签名计算错误
|
||
|
||
**解决方法**：
|
||
1. 检查 `.env` 中的 `WECOM_TOKEN` 是否与企微后台一致
|
||
2. 检查 `.env` 中的 `WECOM_ENCODING_AES_KEY` 是否与企微后台一致（43 位，不含等号）
|
||
3. 确认回调 URL 可公网访问
|
||
|
||
### 错误 2：POST 解密失败
|
||
|
||
**日志**：`wecom decrypt error`
|
||
|
||
**可能原因**：
|
||
- EncodingAESKey 错误
|
||
- 加密数据格式错误
|
||
- 企业 ID 不匹配
|
||
|
||
**解决方法**：
|
||
1. 检查 `WECOM_ENCODING_AES_KEY` 是否正确
|
||
2. 检查 `WECOM_CORP_ID` 是否正确（用于验证解密后的企业 ID）
|
||
|
||
### 错误 3：XML 解析失败
|
||
|
||
**日志**：`wecom xml parse failed`
|
||
|
||
**可能原因**：
|
||
- XML 格式错误
|
||
- 字符编码问题
|
||
|
||
**解决方法**：
|
||
1. 检查解密后的 XML 格式是否正确
|
||
2. 确认 XML 使用 UTF-8 编码
|
||
|
||
### 错误 4：回复未收到
|
||
|
||
**可能原因**：
|
||
- 回复 XML 格式错误
|
||
- 回复加密错误
|
||
- 网络问题
|
||
|
||
**解决方法**：
|
||
1. 检查日志中是否有 `wecom reply sent` 记录
|
||
2. 检查回复 XML 格式是否正确
|
||
3. 检查加密后的回复是否正确
|
||
|
||
## 测试检查清单
|
||
|
||
- [ ] GET 校验成功（企微后台显示"保存成功"）
|
||
- [ ] POST 回调日志正常（收到消息和发送回复都有日志）
|
||
- [ ] 数据库中有会话和消息记录
|
||
- [ ] 企业微信中能收到回复消息
|
||
- [ ] 日志中包含 trace_id、external_userid、msgid、content_summary
|
||
|
||
## 下一步
|
||
|
||
完成阶段 4 测试后，可以继续：
|
||
- 阶段 5：接入 FAQ 匹配
|
||
- 阶段 6：接入 RAG 检索
|
||
- 阶段 7：实现工单转人工流程
|