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

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-05 16:36:32 +08:00
commit 59275ed4dc
126 changed files with 9120 additions and 0 deletions
--- a/docs/wecom-test-guide.md
+++ b/docs/wecom-test-guide.md
@@ -0,0 +1,544 @@
+# 企业微信回调功能测试详细流程
+
+## 一、前置准备
+
+### 1.1 检查服务状态
+
+```bash
+# 检查所有服务是否运行
+docker compose ps
+
+# 应该看到：
+# - ai-db-1 (Running)
+# - ai-backend-1 (Running)
+# - ai-admin-1 (Running，可选)
+```
+
+### 1.2 检查后端日志
+
+```bash
+# 查看后端最新日志，确认无错误
+docker compose logs backend --tail 50
+
+# 应该看到：
+# INFO: Uvicorn running on http://0.0.0.0:8000
+# INFO: Application startup complete.
+```
+
+### 1.3 配置环境变量
+
+编辑 `.env` 文件，确保以下企业微信相关配置已填写：
+
+```bash
+# 企业微信配置（必须）
+WECOM_CORP_ID=你的企业ID                    # 从"我的企业 → 企业信息"获取
+WECOM_AGENT_ID=你的应用AgentId              # 从"自建应用 → 应用详情"获取
+WECOM_SECRET=你的应用Secret                 # 从"自建应用 → 应用详情"获取（可选，用于主动发送消息）
+WECOM_TOKEN=你的Token                       # 自定义字符串，需与企微后台一致
+WECOM_ENCODING_AES_KEY=你的43位密钥         # 从企微后台获取，43位Base64编码
+WECOM_API_BASE=https://qyapi.weixin.qq.com
+WECOM_API_TIMEOUT=10
+WECOM_API_RETRIES=2
+```
+
+**重要提示**：
+- `WECOM_TOKEN` 和 `WECOM_ENCODING_AES_KEY` 必须与企微后台配置**完全一致**
+- `WECOM_ENCODING_AES_KEY` 是 43 位 Base64 编码字符串（不含等号）
+
+### 1.4 重启后端服务（如果修改了 .env）
+
+```bash
+# 重启后端以加载新的环境变量
+docker compose restart backend
+
+# 等待几秒后检查日志
+docker compose logs backend --tail 20
+```
+
+---
+
+## 二、企业微信后台配置
+
+### 2.1 获取必要参数
+
+1. **登录企业微信管理后台**：https://work.weixin.qq.com
+
+2. **获取企业 ID (CorpId)**：
+   - 进入 **我的企业** → **企业信息**
+   - 复制 **企业 ID**，填入 `.env` 的 `WECOM_CORP_ID`
+
+3. **获取应用信息**：
+   - 进入 **应用管理** → **自建应用** → 选择你的应用
+   - 在 **应用详情** 中获取：
+     - **AgentId**：填入 `.env` 的 `WECOM_AGENT_ID`
+     - **Secret**：填入 `.env` 的 `WECOM_SECRET`（可选）
+
+### 2.2 配置回调 URL（关键步骤）
+
+1. **进入接收消息设置**：
+   - 在应用详情页面，找到 **接收消息** 或 **API接收**
+   - 点击 **设置 API 接收** 或 **配置回调URL**
+
+2. **填写回调配置**：
+   - **接收消息服务器 URL**：`https://你的公网域名/api/wecom/callback`
+     - 本地测试：使用 ngrok 等工具暴露本地服务（见下方）
+     - 生产环境：使用你的实际域名
+   - **Token**：填写一个自定义字符串（例如：`my_wecom_token_2025`）
+     - **重要**：这个 Token 必须与 `.env` 中的 `WECOM_TOKEN` **完全一致**
+   - **EncodingAESKey**：
+     - 点击 **随机获取** 或手动输入 43 位 Base64 编码字符串
+     - **重要**：这个密钥必须与 `.env` 中的 `WECOM_ENCODING_AES_KEY` **完全一致**
+   - **消息加解密方式**：选择 **安全模式**（推荐）或 **明文模式**（仅测试）
+
+3. **保存配置**：
+   - 点击 **保存** 按钮
+   - 企业微信会立即发送 GET 请求到你的回调 URL 进行校验
+   - 如果配置正确，会显示 **保存成功** ✅
+
+---
+
+## 三、本地测试方法
+
+### 方法 1：使用 Cloudflare Tunnel（推荐 ⭐⭐⭐⭐⭐）
+
+Cloudflare Tunnel (cloudflared) 提供免费的固定域名，比 ngrok 更稳定。
+
+#### 3.1 安装 cloudflared
+
+**Windows（使用 Scoop）**：
+```powershell
+# 安装 Scoop（如果还没有）
+Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
+irm get.scoop.sh | iex
+
+# 安装 cloudflared
+scoop install cloudflared
+```
+
+**或使用 Chocolatey**：
+```powershell
+choco install cloudflared
+```
+
+**或手动下载**：
+- 访问：https://github.com/cloudflare/cloudflared/releases
+- 下载 `cloudflared-windows-amd64.exe`，重命名为 `cloudflared.exe`
+
+#### 3.2 启动 cloudflared
+
+```powershell
+# 在项目根目录运行（暴露本地 8000 端口）
+cloudflared tunnel --url http://localhost:8000
+```
+
+**输出示例**：
+```
+2025-02-05T10:00:00Z INF +--------------------------------------------------------------------------------------------+
+2025-02-05T10:00:00Z INF |  Your quick Tunnel has been created! Visit it at:                                        |
+2025-02-05T10:00:00Z INF |  https://abc123-def456-ghi789.trycloudflare.com                                           |
+2025-02-05T10:00:00Z INF +--------------------------------------------------------------------------------------------+
+```
+
+#### 3.3 获取公网 URL
+
+从输出中复制 `https://xxx.trycloudflare.com`，这就是你的公网 URL。
+
+**注意**：
+- 这个 URL 在本次运行期间是固定的
+- 关闭 cloudflared 后，URL 会失效
+- 如需固定域名，请登录 Cloudflare 创建命名 tunnel（见 `docs/cloudflared-setup.md`）
+
+#### 3.4 配置企微后台
+
+在企微后台的回调 URL 中填写：`https://你的cloudflared域名.trycloudflare.com/api/wecom/callback`
+
+例如：`https://abc123-def456-ghi789.trycloudflare.com/api/wecom/callback`
+
+#### 3.5 保存并验证
+
+1. 点击 **保存**
+2. 观察后端日志：
+   ```bash
+   docker compose logs backend -f
+   ```
+3. 应该看到：
+   ```
+   INFO: wecom verify success {"trace_id": "...", "echostr_length": 43}
+   ```
+4. 企微后台应显示 **保存成功**
+
+**详细文档**：参见 `docs/cloudflared-setup.md`
+
+---
+
+### 方法 2：使用 ngrok 暴露本地服务
+
+#### 2.1 安装 ngrok
+
+- **Windows**：下载 https://ngrok.com/download，解压到任意目录
+- **或使用包管理器**：`choco install ngrok` 或 `scoop install ngrok`
+
+#### 2.2 启动 ngrok
+
+```bash
+# 在终端中运行（暴露本地 8000 端口）
+ngrok http 8000
+
+# 输出示例：
+# Forwarding  https://abc123.ngrok.io -> http://localhost:8000
+```
+
+#### 2.3 获取公网 URL
+
+从 ngrok 输出中复制 `https://xxx.ngrok.io`，这就是你的公网 URL。
+
+**注意**：免费版 ngrok 每次重启 URL 都会变化，需要重新配置企微后台。
+
+#### 2.4 配置企微后台
+
+在企微后台的回调 URL 中填写：`https://你的ngrok域名.ngrok.io/api/wecom/callback`
+
+例如：`https://abc123.ngrok.io/api/wecom/callback`
+
+#### 2.5 保存并验证
+
+1. 点击 **保存**
+2. 观察后端日志：
+   ```bash
+   docker compose logs backend -f
+   ```
+3. 应该看到：
+   ```
+   INFO: wecom verify success {"trace_id": "...", "echostr_length": 43}
+   ```
+4. 企微后台应显示 **保存成功**
+
+---
+
+### 方法 2：使用企业微信官方测试工具
+
+1. 在企业微信管理后台，进入 **自建应用** → **接收消息** → **调试工具**
+2. 输入测试参数，生成测试请求
+3. 使用 curl 或 Postman 发送请求到本地服务
+
+---
+
+## 四、测试消息回调
+
+### 4.1 发送测试消息
+
+1. **在企业微信中**：
+   - 打开企业微信客户端
+   - 找到你配置的应用
+   - 发送一条文本消息，例如：`你好，测试一下`
+
+### 4.2 查看后端日志
+
+```bash
+# 实时查看日志
+docker compose logs backend -f
+
+# 应该看到以下日志：
+```
+
+**收到消息日志**：
+```json
+{
+  "timestamp": "2025-02-05T10:00:00Z",
+  "level": "INFO",
+  "message": "wecom message received",
+  "trace_id": "abc123-def456",
+  "external_userid": "wmxxxxx",
+  "msgid": "1234567890",
+  "msg_type": "text",
+  "content_summary": "你好，测试一下"
+}
+```
+
+**发送回复日志**：
+```json
+{
+  "timestamp": "2025-02-05T10:00:01Z",
+  "level": "INFO",
+  "message": "wecom reply sent",
+  "trace_id": "abc123-def456",
+  "external_userid": "wmxxxxx",
+  "msgid": "1234567890",
+  "reply_summary": "已收到：你好，测试一下"
+}
+```
+
+### 4.3 验证回复消息
+
+在企业微信客户端中，应该收到回复：**`已收到：你好，测试一下`**
+
+### 4.4 检查数据库
+
+```bash
+# 进入数据库容器
+docker compose exec db psql -U wecom -d wecom_ai
+
+# 查询会话
+SELECT id, external_user_id, external_name, status, created_at 
+FROM chat_sessions 
+ORDER BY created_at DESC 
+LIMIT 5;
+
+# 查询消息
+SELECT id, session_id, role, content, created_at 
+FROM messages 
+ORDER BY created_at DESC 
+LIMIT 10;
+
+# 应该看到：
+# - 一条会话记录（external_user_id 为你的企微用户ID）
+# - 两条消息记录（一条 user，一条 assistant）
+```
+
+---
+
+## 五、完整测试检查清单
+
+### 5.1 配置检查
+
+- [ ] `.env` 文件中所有企业微信配置已填写
+- [ ] `WECOM_TOKEN` 与企微后台一致
+- [ ] `WECOM_ENCODING_AES_KEY` 与企微后台一致（43位）
+- [ ] `WECOM_CORP_ID` 已填写
+- [ ] 后端服务正常运行
+
+### 5.2 GET 校验测试
+
+- [ ] 在企微后台点击保存配置
+- [ ] 后端日志显示 `wecom verify success`
+- [ ] 企微后台显示 **保存成功**
+
+### 5.3 POST 回调测试
+
+- [ ] 在企业微信中发送文本消息
+- [ ] 后端日志显示 `wecom message received`
+- [ ] 后端日志显示 `wecom reply sent`
+- [ ] 企业微信中收到回复消息
+- [ ] 数据库中创建了会话记录
+- [ ] 数据库中创建了消息记录（user + assistant）
+
+---
+
+## 六、常见问题排查
+
+### 问题 1：GET 校验失败
+
+**症状**：企微后台显示"保存失败"或"URL校验失败"
+
+**排查步骤**：
+
+1. **检查 Token**：
+   ```bash
+   # 查看 .env 中的 WECOM_TOKEN
+   cat .env | grep WECOM_TOKEN
+   
+   # 确保与企微后台完全一致（包括大小写、空格等）
+   ```
+
+2. **检查 EncodingAESKey**：
+   ```bash
+   # 查看 .env 中的 WECOM_ENCODING_AES_KEY
+   cat .env | grep WECOM_ENCODING_AES_KEY
+   
+   # 确保是 43 位 Base64 编码（不含等号）
+   # 确保与企微后台完全一致
+   ```
+
+3. **检查后端日志**：
+   ```bash
+   docker compose logs backend | grep "wecom verify"
+   
+   # 如果看到 "wecom verify failed"，检查签名或解密错误
+   ```
+
+4. **检查回调 URL**：
+   - 确保 URL 可公网访问（使用 ngrok 等工具）
+   - 确保 URL 格式正确：`https://域名/api/wecom/callback`
+   - 确保后端服务正常运行
+
+**解决方案**：
+- 重新检查并同步 Token 和 EncodingAESKey
+- 确保回调 URL 可访问
+- 重启后端服务：`docker compose restart backend`
+
+---
+
+### 问题 2：POST 回调失败
+
+**症状**：发送消息后没有收到回复，或后端日志显示错误
+
+**排查步骤**：
+
+1. **检查后端日志**：
+   ```bash
+   docker compose logs backend | grep -E "wecom|error|Error"
+   ```
+
+2. **检查解密错误**：
+   - 如果看到 `wecom decrypt error`，检查 `WECOM_ENCODING_AES_KEY` 是否正确
+   - 如果看到 `wecom xml parse failed`，检查 XML 格式
+
+3. **检查企业 ID**：
+   ```bash
+   # 确保 WECOM_CORP_ID 正确
+   cat .env | grep WECOM_CORP_ID
+   ```
+
+4. **检查数据库连接**：
+   ```bash
+   # 确保数据库服务正常运行
+   docker compose ps db
+   
+   # 检查数据库连接
+   docker compose exec backend python -c "from app.database import engine; print('DB OK')"
+   ```
+
+**解决方案**：
+- 检查并修复配置错误
+- 重启后端服务
+- 检查数据库连接
+
+---
+
+### 问题 3：收到消息但没有回复
+
+**症状**：后端日志显示收到消息，但企业微信中没有收到回复
+
+**排查步骤**：
+
+1. **检查回复日志**：
+   ```bash
+   docker compose logs backend | grep "wecom reply sent"
+   
+   # 如果没有这条日志，说明回复构造或加密失败
+   ```
+
+2. **检查回复 XML 格式**：
+   - 查看后端代码中的 `build_reply_xml` 函数
+   - 确保 XML 格式符合企业微信规范
+
+3. **检查加密**：
+   - 确保 `WECOM_ENCODING_AES_KEY` 正确
+   - 确保 `WECOM_CORP_ID` 正确（用于加密验证）
+
+**解决方案**：
+- 检查回复 XML 构造逻辑
+- 检查加密函数
+- 查看完整错误日志
+
+---
+
+### 问题 4：URL 变化问题
+
+**症状**：每次重启内网穿透工具，URL 都会变化
+
+**解决方案**：
+- **使用 Cloudflare Tunnel**：登录后可以创建固定域名的 tunnel（推荐）
+- **使用 ngrok**：每次重启后需要重新在企微后台更新回调 URL
+- **使用 ngrok 付费版**：可以设置固定域名
+- **其他工具**：frp、localtunnel 等（参见 `docs/cloudflared-setup.md`）
+
+---
+
+## 七、高级测试
+
+### 7.1 测试不同类型的消息
+
+- **文本消息**：发送普通文本
+- **图片消息**：发送图片（当前实现可能只回复"收到"）
+- **事件消息**：测试关注/取消关注等事件
+
+### 7.2 测试并发消息
+
+- 同时发送多条消息
+- 检查数据库是否正确记录所有消息
+- 检查回复是否正确
+
+### 7.3 测试错误处理
+
+- 发送格式错误的消息
+- 检查错误日志
+- 确保服务不会崩溃
+
+---
+
+## 八、测试完成后
+
+### 8.1 验证数据完整性
+
+```bash
+# 检查会话和消息数据
+docker compose exec db psql -U wecom -d wecom_ai -c "
+SELECT 
+  cs.id as session_id,
+  cs.external_user_id,
+  cs.external_name,
+  COUNT(m.id) as message_count,
+  MAX(m.created_at) as last_message_time
+FROM chat_sessions cs
+LEFT JOIN messages m ON cs.id = m.session_id
+GROUP BY cs.id
+ORDER BY cs.created_at DESC;
+"
+```
+
+### 8.2 清理测试数据（可选）
+
+```bash
+# 删除测试数据
+docker compose exec db psql -U wecom -d wecom_ai -c "
+DELETE FROM messages;
+DELETE FROM chat_sessions;
+"
+```
+
+---
+
+## 九、下一步
+
+完成阶段 4 测试后，可以继续：
+
+- **阶段 5**：接入 FAQ 匹配
+- **阶段 6**：接入 RAG 检索
+- **阶段 7**：实现工单转人工流程
+
+---
+
+## 十、快速测试命令汇总
+
+```bash
+# 1. 检查服务状态
+docker compose ps
+
+# 2. 查看后端日志
+docker compose logs backend -f
+
+# 3. 检查环境变量
+docker compose exec backend env | grep WECOM
+
+# 4. 启动 Cloudflare Tunnel（推荐）
+cloudflared tunnel --url http://localhost:8000
+
+# 5. 测试本地健康检查
+curl http://localhost:8000/api/health
+
+# 6. 测试公网健康检查（替换为你的 cloudflared URL）
+curl https://你的域名.trycloudflare.com/api/health
+
+# 7. 检查数据库
+docker compose exec db psql -U wecom -d wecom_ai -c "SELECT * FROM chat_sessions;"
+
+# 8. 重启服务
+docker compose restart backend
+```
+
+**详细 Cloudflare Tunnel 配置**：参见 `docs/cloudflared-setup.md`
+
+---
+
+**提示**：如果遇到问题，请先查看后端日志，大多数问题都会在日志中显示错误信息。