# 企微机器人集成架构全景

四种企微接入方式的全量对比，避免项目初期选错方案导致返工。

## 1. 群机器人 Webhook

**方向**: 服务器 → 企微群（单向推送）  
**需要**: 仅 Webhook URL（`https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx`）  
**不需要**: 公网 URL、SSL 证书、域名、回调验证  

```python
# utils.py: send_qw_markdown()
payload = {"msgtype": "markdown", "markdown": {"content": "## ..."}}
requests.post(QW_WEBHOOK_URL, json=payload)
```

**适用**: 每日文章推送、系统通知、定时汇总  
**限制**: 不能接收用户消息，不能回复  

---

## 2. 自建应用主动推送（send_wx_app_message）

**方向**: 服务器 → 指定企微用户（单向推送）  
**需要**: WX_CORP_ID + WX_APP_SECRET + WX_APP_AGENT_ID（拿 access_token）  
**不需要**: 公网 URL、回调验证  

```python
# 获取 token → POST qyapi.weixin.qq.com/cgi-bin/message/send
send_wx_app_message(touser="userid", content="markdown")
```

**适用**: 向特定用户推送 DM  
**限制**: 需服务端出站能访问 qyapi.weixin.qq.com，不能接收消息  

---

## 3. 自建应用回调（URL 回调模式）

**方向**: 双向（用户发消息 → 企微回调 → 服务器回复）  
**需要**: 
- 公网 HTTPS URL（`https://domain/wx-callback`）
- CA 签名的 SSL 证书（自签名证书被企微拒绝）
- Token + EncodingAESKey（在企微后台配置）

**验证流程**: 企微 GET `/wx-callback?msg_signature=...&echostr=...` → 解密 echostr → 返回明文

**限制**: 
- 腾讯云轻量服务器 80/443 端口常被 ISP 封锁（无 ICP 备案）
- Cloudflare Tunnel 可绕过，但增加复杂度
- 企微只允许配置一个回调 URL

---

## 4. 智能机器人长连接（WebSocket 模式）⭐

**方向**: 双向（服务器主动连接企微 WebSocket，企微通过长连接推送消息）  
**需要**: 
- Token + EncodingAESKey（从智能机器人配置页获取）
- 服务器出站能连企微 WebSocket 服务

**不需要**: 公网 URL、SSL 证书、域名  

**协议**: 服务器 → WebSocket 连接到企微 → 企微通过连接推送 `aibot_msg_callback`（消息）和 `aibot_event_callback`（事件）

**文档**:  
- 概述: `https://developer.work.weixin.qq.com/document/path/100718`  
- 长连接: `https://developer.work.weixin.qq.com/document/path/101463`  
- 接收消息: `https://developer.work.weixin.qq.com/document/path/100719`

**优势**: 
- 完美解决「服务器无公网 IP/端口被封」问题
- 支持消息接收、流式回复、模板卡片
- 一个机器人同时处理推送和交互

**配置步骤**（用户在企微后台操作）:
1. 企微管理后台 → 应用管理 → 智能机器人 → 配置
2. 接收消息模式 → 选择「长连接」（不是「URL 回调」）
3. 获取 Token 和 EncodingAESKey
4. 将 Token 和 AESKey 提供给服务器端长连接客户端

**加密方式**: AES-256-CBC, PKCS#7 填充, IV 取 aeskey 前 16 字节

---

## 决策表

| 场景 | 推荐方案 |
|------|----------|
| 只推送文章到群 | ① 群机器人 Webhook |
| 只推送消息给个人 | ② 自建应用主动推送 |
| 群内交互 + 有公网 | ③ 自建应用回调 |
| 群内交互 + 无公网 | ④ 智能机器人长连接 ⭐ |
| 已有群机器人 + 要加交互 | ④ 智能机器人（覆盖①的功能） |

## 本项目实际路径

本项目（春考选题助手）的演进：
1. ✅ **阶段一**：群机器人 Webhook — 定时抓取 + 推送文章到群（已完成）
2. ⏳ **阶段二**：智能机器人长连接 — 群内选题互动（待实现，需用户提供 Token/AESKey）
3. ❌ 自建应用回调 — 不再需要（被长连接替代）