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

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

docs/setup-steps.md

@@ -0,0 +1,240 @@
+# 企业微信回调配置完整步骤
+
+## 当前状态检查
+
+✅ 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 匹配功能