HaHafeng
36ce1bbcb2
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)
4.8 KiB
4.8 KiB
企业微信环境变量配置说明
📋 必需的环境变量
在 backend/.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
⚠️ 重要提示
-
IP白名单（生产环境必需）
- SAE NAT网关EIP：
182.92.176.14 - 需要在企业微信后台配置为"企业可信IP"
- 位置：企业微信管理后台 → 应用管理 → IIT Manager Agent → 企业可信IP
- SAE NAT网关EIP：
-
natapp隧道（本地开发）
- 确保natapp隧道正常运行：
http://iit.nat100.top - 后端服务监听：
http://localhost:3001
- 确保natapp隧道正常运行：
-
环境变量加载
- 修改
.env文件后，需要重启后端服务 - 验证方法：查看后端启动日志是否显示"✅ 企业微信服务初始化成功"
- 修改
🚀 验证配置
步骤1：检查后端日志
启动后端服务后，应该看到：
✅ 企业微信服务初始化成功
✅ 企业微信回调控制器初始化成功
Registered route: GET /api/v1/iit/wechat/callback
Registered route: POST /api/v1/iit/wechat/callback
步骤2：访问健康检查
curl https://iit.nat100.top/api/v1/iit/health
预期返回：
{
"status": "ok",
"module": "iit-manager",
"version": "1.1.0",
"timestamp": "2026-01-02T14:30:00.000Z"
}
步骤3：保存企业微信回调配置
在企业微信后台点击"保存"，如果配置正确：
- ✅ 企业微信会发送GET请求验证URL
- ✅ 后端会解密echostr并返回
- ✅ 显示"保存成功"
📞 常见问题
Q1: 保存回调URL时提示"URL验证失败"
可能原因：
- 后端服务未启动或无法访问
- natapp隧道未运行
- 环境变量配置错误（Token或EncodingAESKey不匹配）
解决方法：
- 检查后端日志是否有错误
- 确认natapp状态：
http://iit.nat100.top/api/v1/iit/health - 检查
.env文件中的Token和EncodingAESKey
Q2: 收不到企业微信消息
可能原因：
- 回调URL未保存成功
- 消息类型未勾选（文本消息、支付且退款通知等）
- 用户未关注应用
解决方法：
- 确认回调URL已保存成功
- 检查"选择需要接收的消息事件类型"是否勾选了对应类型
- 用户在企业微信中打开应用
Q3: 发送消息提示"invalid user"
可能原因：
- 用户UserID不存在
- 用户未在应用的可见范围内
解决方法：
- 确认UserID正确（企业微信后台查看）
- 检查应用的可见范围设置
📚 相关文档
- 企业微信API文档
- 企业微信消息加解密说明
- [最小MVP闭环开发计划](../docs/03-业务模块/IIT Manager Agent/04-开发计划/最小MVP闭环开发计划.md)