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

# 企业微信回调功能测试详细流程

## 一、前置准备

### 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`

---

**提示**：如果遇到问题，请先查看后端日志，大多数问题都会在日志中显示错误信息。