wecom-ai-assistant/docs/wecom-test.md

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

前置条件

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：

   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 请求测试

curl -X GET "http://localhost:8000/api/wecom/callback?msg_signature=xxx&timestamp=xxx&nonce=xxx&echostr=xxx"

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

POST 请求测试

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 校验日志

docker compose logs backend | grep "wecom verify"

成功日志示例：

{
  "level": "INFO",
  "message": "wecom verify success",
  "trace_id": "abc123",
  "echostr_length": 43
}

2. 检查 POST 回调日志

docker compose logs backend | grep "wecom message"

成功日志示例：

{
  "level": "INFO",
  "message": "wecom message received",
  "trace_id": "abc123",
  "external_userid": "wmxxxxx",
  "msgid": "1234567890",
  "msg_type": "text",
  "content_summary": "你好，我想咨询一下..."
}

{
  "level": "INFO",
  "message": "wecom reply sent",
  "trace_id": "abc123",
  "external_userid": "wmxxxxx",
  "msgid": "1234567890",
  "reply_summary": "已收到：你好，我想咨询一下..."
}

3. 检查数据库

# 进入数据库容器
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：实现工单转人工流程