Initial commit: 浼佷笟寰俊 AI 鏈哄櫒浜哄姪鐞?MVP

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/wecom-test.md

@@ -0,0 +1,193 @@
+# 企业微信回调本地测试指南
+
+## 前置条件
+
+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：实现工单转人工流程