# 企业微信回调本地测试指南

## 前置条件

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&timestamp=xxx&nonce=xxx&echostr=xxx"
```

**预期响应**：返回解密后的 `echostr` 明文

#### POST 请求测试

```bash
curl -X POST "http://localhost:8000/api/wecom/callback?msg_signature=xxx&timestamp=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：实现工单转人工流程