feat(iit): Complete Day 3 - WeChat Work integration and URL verification
Summary: - Implement WechatService (314 lines, push notifications) - Implement WechatCallbackController (501 lines, async reply mode) - Complete iit_quality_check Worker with WeChat notifications - Configure WeChat routes (GET + POST /wechat/callback) - Configure natapp tunnel for local development - WeChat URL verification test passed Technical Highlights: - Async reply mode to avoid 5-second timeout - Message encryption/decryption using @wecom/crypto - Signature verification using getSignature - natapp tunnel: https://iit.nat100.top - Environment variables configuration completed Technical Challenges Solved: - Fix environment variable naming (WECHAT_CORP_SECRET) - Fix @wecom/crypto import (createRequire for CommonJS) - Fix decrypt function parameters (2 params, not 4) - Fix Token character recognition (lowercase l vs digit 1) - Regenerate EncodingAESKey (43 chars, correct format) - Configure natapp for internal network penetration Test Results: - WeChat developer tool verification: PASSED - Return status: request success - HTTP 200, decrypted 23 characters correctly - Backend logs: URL verification successful Documentation: - Add Day3 WeChat integration development record - Update MVP development task list (Day 2-3 completed) - Update module status guide (v1.2 -> v1.3) - Overall completion: 35% -> 50% Progress: - Module completion: 35% -> 50% - Day 3 development: COMPLETED - Ready for end-to-end testing (REDCap -> WeChat)
This commit is contained in:
161
backend/WECHAT_ENV_CONFIG.md
Normal file
161
backend/WECHAT_ENV_CONFIG.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# 企业微信环境变量配置说明
|
||||
|
||||
## 📋 必需的环境变量
|
||||
|
||||
在 `backend/.env` 文件中添加以下配置：
|
||||
|
||||
```env
|
||||
# ==========================================
|
||||
# 企业微信配置
|
||||
# ==========================================
|
||||
|
||||
# 企业微信基础配置（应用信息）
|
||||
WECHAT_CORP_ID=ww6ab493470ab4f377
|
||||
WECHAT_AGENT_ID=1000002
|
||||
WECHAT_CORP_SECRET=AZIVxMtoLb0rEszXS81e4dBRl-I9kgTjygIS0cFfENU
|
||||
|
||||
# 企业微信回调配置（消息加解密）
|
||||
WECHAT_TOKEN=oX1RBm1YnvMy2SbDLbvAdDd5Gq3oBGq
|
||||
WECHAT_ENCODING_AES_KEY=zE4tcdBeekCHPUV015jCh9RVUydnCITINqSmCzg9xtO
|
||||
```
|
||||
|
||||
## 📝 配置项说明
|
||||
|
||||
### 1. WECHAT_CORP_ID
|
||||
- **说明**：企业微信的企业ID
|
||||
- **获取方式**：企业微信管理后台 → 我的企业 → 企业信息 → 企业ID
|
||||
- **当前值**：`ww6ab493470ab4f377`
|
||||
|
||||
### 2. WECHAT_AGENT_ID
|
||||
- **说明**：应用的AgentID
|
||||
- **获取方式**：企业微信管理后台 → 应用管理 → IIT Manager Agent → AgentId
|
||||
- **当前值**：`1000002`
|
||||
- **应用名称**：`IIT Manager Agent`
|
||||
|
||||
### 3. WECHAT_CORP_SECRET
|
||||
- **说明**：应用的Secret（用于获取access_token）
|
||||
- **获取方式**：企业微信管理后台 → 应用管理 → IIT Manager Agent → Secret
|
||||
- **当前值**：`AZIVxMtoLb0rEszXS81e4dBRl-I9kgTjygIS0cFfENU`
|
||||
- **⚠️ 安全提示**：Secret 非常重要，切勿泄露
|
||||
|
||||
### 4. WECHAT_TOKEN
|
||||
- **说明**：消息回调的Token（用于验证签名）
|
||||
- **获取方式**：企业微信管理后台 → 应用管理 → IIT Manager Agent → 接收消息 → 点击"随机获取"
|
||||
- **当前值**：`oXlRBm1YnvMy2SbDLbvAdDd5Gq3oBGq`
|
||||
|
||||
### 5. WECHAT_ENCODING_AES_KEY
|
||||
- **说明**：消息加解密密钥（43位字符）
|
||||
- **获取方式**：企业微信管理后台 → 应用管理 → IIT Manager Agent → 接收消息 → 点击"随机获取"
|
||||
- **当前值**：`zE4tcdBeekCHPUV015jCh9RVUydnCITINqSmCzg9xtO`
|
||||
|
||||
## 🔧 企业微信回调URL配置
|
||||
|
||||
### 本地开发（natapp）
|
||||
|
||||
```
|
||||
回调URL: https://iit.nat100.top/api/v1/iit/wechat/callback
|
||||
Token: oXlRBm1YnvMy2SbDLbvAdDd5Gq3oBGq
|
||||
EncodingAESKey: zE4tcdBeekCHPUV015jCh9RVUydnCITINqSmCzg9xtO
|
||||
```
|
||||
|
||||
### 生产环境（SAE）
|
||||
|
||||
```
|
||||
回调URL: https://iit.xunzhengyixue.com/api/v1/iit/wechat/callback
|
||||
Token: oXlRBm1YnvMy2SbDLbvAdDd5Gq3oBGq
|
||||
EncodingAESKey: zE4tcdBeekCHPUV015jCh9RVUydnCITINqSmCzg9xtO
|
||||
```
|
||||
|
||||
## ⚠️ 重要提示
|
||||
|
||||
1. **IP白名单**（生产环境必需）
|
||||
- SAE NAT网关EIP：`182.92.176.14`
|
||||
- 需要在企业微信后台配置为"企业可信IP"
|
||||
- 位置：企业微信管理后台 → 应用管理 → IIT Manager Agent → 企业可信IP
|
||||
|
||||
2. **natapp隧道**（本地开发）
|
||||
- 确保natapp隧道正常运行：`http://iit.nat100.top`
|
||||
- 后端服务监听：`http://localhost:3001`
|
||||
|
||||
3. **环境变量加载**
|
||||
- 修改 `.env` 文件后，需要**重启后端服务**
|
||||
- 验证方法：查看后端启动日志是否显示"✅ 企业微信服务初始化成功"
|
||||
|
||||
## 🚀 验证配置
|
||||
|
||||
### 步骤1：检查后端日志
|
||||
|
||||
启动后端服务后，应该看到：
|
||||
|
||||
```
|
||||
✅ 企业微信服务初始化成功
|
||||
✅ 企业微信回调控制器初始化成功
|
||||
Registered route: GET /api/v1/iit/wechat/callback
|
||||
Registered route: POST /api/v1/iit/wechat/callback
|
||||
```
|
||||
|
||||
### 步骤2：访问健康检查
|
||||
|
||||
```bash
|
||||
curl https://iit.nat100.top/api/v1/iit/health
|
||||
```
|
||||
|
||||
预期返回：
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"module": "iit-manager",
|
||||
"version": "1.1.0",
|
||||
"timestamp": "2026-01-02T14:30:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
### 步骤3：保存企业微信回调配置
|
||||
|
||||
在企业微信后台点击"保存"，如果配置正确：
|
||||
- ✅ 企业微信会发送GET请求验证URL
|
||||
- ✅ 后端会解密echostr并返回
|
||||
- ✅ 显示"保存成功"
|
||||
|
||||
## 📞 常见问题
|
||||
|
||||
### Q1: 保存回调URL时提示"URL验证失败"
|
||||
|
||||
**可能原因**：
|
||||
1. 后端服务未启动或无法访问
|
||||
2. natapp隧道未运行
|
||||
3. 环境变量配置错误（Token或EncodingAESKey不匹配）
|
||||
|
||||
**解决方法**：
|
||||
1. 检查后端日志是否有错误
|
||||
2. 确认natapp状态：`http://iit.nat100.top/api/v1/iit/health`
|
||||
3. 检查 `.env` 文件中的Token和EncodingAESKey
|
||||
|
||||
### Q2: 收不到企业微信消息
|
||||
|
||||
**可能原因**：
|
||||
1. 回调URL未保存成功
|
||||
2. 消息类型未勾选（文本消息、支付且退款通知等）
|
||||
3. 用户未关注应用
|
||||
|
||||
**解决方法**：
|
||||
1. 确认回调URL已保存成功
|
||||
2. 检查"选择需要接收的消息事件类型"是否勾选了对应类型
|
||||
3. 用户在企业微信中打开应用
|
||||
|
||||
### Q3: 发送消息提示"invalid user"
|
||||
|
||||
**可能原因**：
|
||||
1. 用户UserID不存在
|
||||
2. 用户未在应用的可见范围内
|
||||
|
||||
**解决方法**：
|
||||
1. 确认UserID正确（企业微信后台查看）
|
||||
2. 检查应用的可见范围设置
|
||||
|
||||
## 📚 相关文档
|
||||
|
||||
- [企业微信API文档](https://developer.work.weixin.qq.com/document/path/90664)
|
||||
- [企业微信消息加解密说明](https://developer.work.weixin.qq.com/document/path/90968)
|
||||
- [最小MVP闭环开发计划](../docs/03-业务模块/IIT Manager Agent/04-开发计划/最小MVP闭环开发计划.md)
|
||||
|
||||
Reference in New Issue
Block a user