# 企业微信回调配置完整步骤

## 当前状态检查

✅ Docker 服务运行正常
✅ 后端服务正常（http://localhost:8000）
✅ .env 文件已配置企业微信参数

---

## 步骤 1：安装 cloudflared

### 方法 A：使用 MSI 安装包（推荐，最简单）

1. **下载安装包**：
   - 直接下载：https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-windows-amd64.msi
   - 或访问：https://github.com/cloudflare/cloudflared/releases 选择最新版本

2. **安装**：
   - 双击下载的 `cloudflared-windows-amd64.msi` 文件
   - 按照安装向导完成安装
   - 安装完成后会自动添加到系统 PATH

3. **验证安装**：
   ```powershell
   cloudflared --version
   ```
   应该显示版本号，例如：`cloudflared 2026.1.2`

### 方法 B：使用 Scoop（如果已安装）

```powershell
scoop install cloudflared
```

---

## 步骤 2：启动 Cloudflare Tunnel

### 2.1 启动 tunnel

在 PowerShell 中运行：

```powershell
cloudflared tunnel --url http://localhost:8000
```

### 2.2 复制公网 URL

启动后会显示类似这样的输出：

```
+--------------------------------------------------------------------------------------------+
|  Your quick Tunnel has been created! Visit it at:                                        |
|  https://abc123-def456-ghi789.trycloudflare.com                                           |
+--------------------------------------------------------------------------------------------+
```

**重要**：复制这个 URL（例如：`https://abc123-def456-ghi789.trycloudflare.com`）

### 2.3 保持窗口运行

**重要**：不要关闭这个 PowerShell 窗口，保持 cloudflared 运行。

---

## 步骤 3：配置企业微信后台

### 3.1 登录企业微信管理后台

访问：https://work.weixin.qq.com

### 3.2 进入应用设置

1. 点击 **应用管理**
2. 选择 **自建应用**
3. 选择你的应用（AgentId: 1000003）
4. 找到 **接收消息** 或 **API接收**
5. 点击 **设置 API 接收** 或 **配置回调URL**

### 3.3 填写回调配置

根据你的 `.env` 文件，填写以下信息：

| 配置项 | 值 | 说明 |
|--------|-----|------|
| **接收消息服务器 URL** | `https://你的cloudflared域名.trycloudflare.com/api/wecom/callback` | 将 `你的cloudflared域名` 替换为步骤 2.2 中复制的域名 |
| **Token** | `tuqA13S8A9L2` | 与 `.env` 中的 `WECOM_TOKEN` 一致 |
| **EncodingAESKey** | `VjrVc9NuGr1pikvwKLjr2OpB6gh1wDlBaUMKeUHAlKw` | 与 `.env` 中的 `WECOM_ENCODING_AES_KEY` 一致 |
| **消息加解密方式** | **安全模式** | 推荐选择安全模式 |

**示例**：
- 如果 cloudflared URL 是：`https://abc123-def456-ghi789.trycloudflare.com`
- 那么回调 URL 应该是：`https://abc123-def456-ghi789.trycloudflare.com/api/wecom/callback`

### 3.4 保存配置

点击 **保存** 按钮。

---

## 步骤 4：验证配置

### 4.1 查看后端日志

在另一个 PowerShell 窗口中运行：

```powershell
docker compose logs backend -f
```

### 4.2 检查验证结果

保存配置后，企业微信会立即发送 GET 请求进行校验。

**成功标志**：
- 后端日志中应该看到：
  ```
  INFO: wecom verify success {"trace_id": "...", "echostr_length": 43}
  ```
- 企业微信后台应显示 **保存成功** ✅

**失败标志**：
- 后端日志显示 `wecom verify failed`
- 企业微信后台显示"URL校验失败"

**如果失败，检查**：
1. Token 是否与 `.env` 中的 `WECOM_TOKEN` 完全一致
2. EncodingAESKey 是否与 `.env` 中的 `WECOM_ENCODING_AES_KEY` 完全一致（43位，不含等号）
3. 回调 URL 是否正确（包含 `/api/wecom/callback`）
4. cloudflared 是否仍在运行

---

## 步骤 5：测试消息回调

### 5.1 发送测试消息

1. 打开企业微信客户端
2. 找到你配置的应用
3. 发送一条文本消息，例如：`你好，测试一下`

### 5.2 查看后端日志

在后端日志中应该看到：

**收到消息**：
```json
{
  "level": "INFO",
  "message": "wecom message received",
  "trace_id": "...",
  "external_userid": "wmxxxxx",
  "msgid": "1234567890",
  "msg_type": "text",
  "content_summary": "你好，测试一下"
}
```

**发送回复**：
```json
{
  "level": "INFO",
  "message": "wecom reply sent",
  "trace_id": "...",
  "external_userid": "wmxxxxx",
  "msgid": "1234567890",
  "reply_summary": "已收到：你好，测试一下"
}
```

### 5.3 验证回复

在企业微信客户端中，应该收到回复：**`已收到：你好，测试一下`**

### 5.4 检查数据库

```powershell
# 查看会话
docker compose exec db psql -U wecom -d wecom_ai -c "SELECT id, external_user_id, status, created_at FROM chat_sessions ORDER BY created_at DESC LIMIT 5;"

# 查看消息
docker compose exec db psql -U wecom -d wecom_ai -c "SELECT id, session_id, role, content, created_at FROM messages ORDER BY created_at DESC LIMIT 10;"
```

---

## 常见问题

### Q1: cloudflared 命令找不到？

**解决**：
- 如果使用 MSI 安装，重启 PowerShell 窗口
- 或使用完整路径运行：`C:\Program Files\Cloudflare\cloudflared.exe tunnel --url http://localhost:8000`

### Q2: GET 校验失败？

**检查清单**：
- [ ] Token 是否与 `.env` 中的 `WECOM_TOKEN` 完全一致（包括大小写、空格）
- [ ] EncodingAESKey 是否与 `.env` 中的 `WECOM_ENCODING_AES_KEY` 完全一致（43位）
- [ ] 回调 URL 是否正确（格式：`https://域名.trycloudflare.com/api/wecom/callback`）
- [ ] cloudflared 是否仍在运行
- [ ] 后端服务是否正常运行

### Q3: 收到消息但没有回复？

**检查**：
- 查看后端日志是否有错误
- 检查数据库连接是否正常
- 确认消息类型是否为文本消息

---

## 快速命令参考

```powershell
# 检查服务状态
docker compose ps

# 查看后端日志
docker compose logs backend -f

# 测试本地服务
curl http://localhost:8000/api/health

# 启动 cloudflared
cloudflared tunnel --url http://localhost:8000

# 检查数据库
docker compose exec db psql -U wecom -d wecom_ai -c "SELECT * FROM chat_sessions;"
```

---

## 下一步

完成配置后，可以：
1. 测试不同类型的消息（文本、图片等）
2. 查看管理后台的会话列表和消息记录
3. 继续开发阶段 5：FAQ 匹配功能