Files

HaHafeng b31255031e feat(iit-manager): Add WeChat Official Account integration for patient notifications

Features:
- PatientWechatCallbackController for URL verification and message handling
- PatientWechatService for template and customer messages
- Support for secure mode (message encryption/decryption)
- Simplified route /wechat/patient/callback for WeChat config
- Event handlers for subscribe/unsubscribe/text messages
- Template message for visit reminders

Technical details:
- Reuse @wecom/crypto for encryption (compatible with Official Account)
- Relaxed Fastify schema validation to prevent early request blocking
- Access token caching (7000s with 5min pre-refresh)
- Comprehensive logging for debugging

Testing: Local URL verification passed, ready for SAE deployment

Status: Code complete, waiting for WeChat platform configuration

2026-01-04 22:53:42 +08:00

14 KiB

Raw Blame History

微信环境变量配置说明（企业微信 + 服务号）

📋 必需的环境变量

在 backend/.env 文件中添加以下配置：

# ==========================================
# 企业微信配置（研究者端）
# ==========================================

# 企业微信基础配置（应用信息）
WECHAT_CORP_ID=ww6ab493470ab4f377
WECHAT_AGENT_ID=1000002
WECHAT_CORP_SECRET=AZIVxMtoLb0rEszXS81e4dBRl-I9kgTjygIS0cFfENU

# 企业微信回调配置（消息加解密）
WECHAT_TOKEN=oXlRBm1YnvMy2SbDLbvAdDd5Gq3oBGq
WECHAT_ENCODING_AES_KEY=V88eT3O9bMW897h4btr7v7qvQlmlMf31edTQCmuhOhO

# 测试用户ID（可选，仅测试环境使用）
WECHAT_TEST_USER_ID=FengZhiBo

# ==========================================
# 微信服务号配置（患者端）
# ==========================================

# 微信服务号基础配置
WECHAT_MP_APP_ID=wx062568ff49e4570c
WECHAT_MP_APP_SECRET=c0d19435d1a1e948939c16d767ec0faf

# 微信服务号回调配置（消息加解密，安全模式）
WECHAT_MP_TOKEN=<需要生成3-32位字符串>
WECHAT_MP_ENCODING_AES_KEY=<需要生成43位字符串>

# 微信小程序配置（可选，后续开发）
WECHAT_MINI_APP_ID=<待申请>

📝 配置项说明

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
⚠️ 注意：Token必须与企业微信后台配置的完全一致，否则URL验证会失败

5. WECHAT_ENCODING_AES_KEY

说明：消息加解密密钥（43位字符）
获取方式：企业微信管理后台 → 应用管理 → IIT Manager Agent → 接收消息 → 点击"随机获取"
当前值：V88eT3O9bMW897h4btr7v7qvQlmlMf31edTQCmuhOhO
⚠️ 注意：必须与企业微信后台配置的完全一致，大小写敏感，用于消息加解密

6. WECHAT_TEST_USER_ID（可选）

说明：测试用户的企业微信UserID，仅用于开发和测试环境
获取方式：企业微信管理后台 → 通讯录 → 选择成员 → 查看"账号"字段
当前值：FengZhiBo
用途：
- 用于快速测试企业微信推送功能
- 生产环境中，UserID应从项目配置的notificationConfig中动态获取
- 可配置多个用户，用竖线分隔：FengZhiBo|ZhangSan|LiSi
⚠️ 注意：该配置仅供测试使用，生产环境通知目标应由项目配置决定

📝 REDCap项目配置说明

REDCap项目配置（包括URL、API Token等）不使用环境变量，而是存储在数据库的 iit_schema.projects 表中。

这样设计的优点：

✅ 支持多项目管理
✅ 动态配置，无需重启服务
✅ 安全性更好（Token加密存储）
✅ 便于团队协作

🔧 企业微信回调URL配置

本地开发（natapp + 公司备案域名）

回调URL: https://devlocal.xunzhengyixue.com/api/v1/iit/wechat/callback
Token: oXlRBm1YnvMy2SbDLbvAdDd5Gq3oBGq
EncodingAESKey: V88eT3O9bMW897h4btr7v7qvQlmlMf31edTQCmuhOhO

natapp映射：

https://devlocal.xunzhengyixue.com → 127.0.0.1:3001
需要公司备案域名，否则企业微信不允许配置

生产环境（SAE）

回调URL: https://iit.xunzhengyixue.com/api/v1/iit/wechat/callback
Token: oXlRBm1YnvMy2SbDLbvAdDd5Gq3oBGq
EncodingAESKey: V88eT3O9bMW897h4btr7v7qvQlmlMf31edTQCmuhOhO

⚠️ 重要提示

IP白名单（生产环境必需）
- SAE NAT网关EIP：182.92.176.14
- 需要在企业微信后台配置为"企业可信IP"
- 位置：企业微信管理后台 → 应用管理 → IIT Manager Agent → 企业可信IP
natapp隧道（本地开发）
- 确保natapp隧道正常运行：https://devlocal.xunzhengyixue.com
- 后端服务监听：http://localhost:3001
- ⚠️ 关键：必须使用公司备案域名，否则企业微信不允许配置回调URL
环境变量加载
- 修改 .env 文件后，需要重启后端服务
- 验证方法：查看后端启动日志是否显示"✅ 企业微信服务初始化成功"

🧪 消息推送测试

在配置后端服务之前，建议先使用企业微信官方调试工具测试推送功能。

测试工具地址

https://developer.work.weixin.qq.com/document/path/90236

在文档页面右侧有"在线调试"按钮。

测试步骤

Step 1: 获取Access Token

接口：获取access_token

参数：

corpid: ww6ab493470ab4f377
corpsecret: AZlVxMtoLb0rEszXS81e4dBRl-I9kgTjyglS0cFfENU

预期返回：

{
  "errcode": 0,
  "errmsg": "ok",
  "access_token": "很长的token字符串...",
  "expires_in": 7200
}

Step 2: 发送测试消息

接口：发送应用消息

参数：

access_token: 从Step 1获取的token

消息Body示例：

A. 文本消息（简单测试）

{
  "touser": "FengZhiBo",
  "msgtype": "text",
  "agentid": 1000002,
  "text": {
    "content": "🎉 IIT Manager 测试消息\n\n这是来自企业微信官方调试工具的测试推送。\n\n如果您收到此消息，说明推送功能正常！"
  }
}

B. 卡片消息（数据录入通知）

{
  "touser": "FengZhiBo",
  "msgtype": "textcard",
  "agentid": 1000002,
  "textcard": {
    "title": "📊 test0102 - 数据录入",
    "description": "<div class=\"gray\">2026-01-03 16:00</div><div class=\"normal\">受试者：8</div><div class=\"normal\">操作：新增</div><div class=\"normal\">表单：demographics</div><div class=\"normal\">录入8个字段</div>",
    "url": "https://iit.xunzhengyixue.com",
    "btntxt": "查看详情"
  }
}

C. Markdown消息（富文本）

{
  "touser": "FengZhiBo",
  "msgtype": "markdown",
  "agentid": 1000002,
  "markdown": {
    "content": "## 📊 IIT Manager 数据通知\n\n**项目名称**：test0102\n**受试者ID**：8\n**操作类型**：新增\n**数据表单**：demographics\n**录入字段**：8个\n\n---\n\n### 📋 字段摘要\n- 姓名：张三\n- 年龄：45岁\n- 性别：男\n- BMI：23.5\n\n> 数据录入时间：2026-01-03 16:30  \n> 录入人员：CRC001\n\n[点击查看详情](https://iit.xunzhengyixue.com/chat?recordId=8)"
  }
}

预期效果：

API返回：{"errcode":0,"errmsg":"ok","msgid":"消息ID"}
企业微信客户端（手机或PC）收到消息（1-2秒内）

测试结果记录

测试日期：2026-01-03

测试项	状态	说明
获取Access Token	✅ 通过	errcode=0，token有效期7200秒
发送文本消息	✅ 通过	手机端成功接收
发送卡片消息	✅ 通过	卡片显示正常，可点击跳转
发送Markdown消息	✅ 通过	富文本格式正确

🚀 验证配置

步骤1：检查后端日志

启动后端服务后，应该看到：

✅ 企业微信服务初始化成功
✅ 企业微信回调控制器初始化成功
Registered route: GET /api/v1/iit/wechat/callback
Registered route: POST /api/v1/iit/wechat/callback

步骤2：访问健康检查

curl https://devlocal.xunzhengyixue.com/api/v1/iit/health

预期返回：

{
  "status": "ok",
  "module": "iit-manager",
  "version": "1.1.0",
  "timestamp": "2026-01-02T14:30:00.000Z"
}

步骤3：保存企业微信回调配置

在企业微信后台点击"保存"，如果配置正确：

✅ 企业微信会发送GET请求验证URL
✅ 后端会解密echostr并返回
✅ 显示"保存成功"

👤 如何获取UserID

UserID是企业微信成员的唯一标识（不是姓名），用于指定消息接收人。

方法1：通过管理后台查看（推荐）

登录企业微信管理后台
进入"通讯录"
找到要获取UserID的成员
点击成员详情
查看"账号"字段，即为UserID

示例：FengZhiBo、ZhangSan、LiSi

方法2：通过API获取部门成员列表

# 获取部门1的成员列表
curl "https://qyapi.weixin.qq.com/cgi-bin/user/simplelist?access_token=ACCESS_TOKEN&department_id=1"

返回示例：

{
  "errcode": 0,
  "errmsg": "ok",
  "userlist": [
    {
      "userid": "FengZhiBo",
      "name": "冯智博",
      "department": [1]
    },
    {
      "userid": "ZhangSan",
      "name": "张三",
      "department": [1]
    }
  ]
}

方法3：使用特殊UserID

@all - 发送给应用可见范围内的所有人（仅用于测试或全员通知）

示例：

{
  "touser": "@all",
  "msgtype": "text",
  "agentid": 1000002,
  "text": {
    "content": "这是发给所有人的测试消息"
  }
}

📞 常见问题

Q1: 保存回调URL时提示"URL验证失败"

可能原因：

后端服务未启动或无法访问
natapp隧道未运行
环境变量配置错误（Token或EncodingAESKey不匹配）

解决方法：

检查后端日志是否有错误
确认natapp状态：https://devlocal.xunzhengyixue.com/api/v1/iit/health
检查 .env 文件中的Token和EncodingAESKey是否与企业微信后台配置完全一致

Q2: 收不到企业微信消息

可能原因：

回调URL未保存成功
消息类型未勾选（文本消息、支付且退款通知等）
用户未关注应用

解决方法：

确认回调URL已保存成功
检查"选择需要接收的消息事件类型"是否勾选了对应类型
用户在企业微信中打开应用

Q3: 发送消息提示"invalid user"

可能原因：

用户UserID不存在
用户未在应用的可见范围内

解决方法：

确认UserID正确（企业微信后台查看）
检查应用的可见范围设置

Q4: 获取Access Token提示"60020"错误

错误信息：errcode: 60020, errmsg: "not allow to access from your ip"

原因：请求来源IP未在"企业可信IP"白名单中

解决方法：

确认当前IP地址（本地开发：公网IP；SAE：182.92.176.14）
登录企业微信管理后台
应用管理 → IIT Manager Agent → 企业可信IP
添加IP地址到白名单
保存并重试

Q5: 官方调试工具测试成功，但代码发送失败

可能原因：

环境变量未正确配置
后端服务未重启
Access Token缓存有误

解决方法：

检查 .env 文件中的配置是否与调试工具中使用的一致
重启后端服务
清空Access Token缓存（重新获取）
查看后端日志排查具体错误

✅ 配置检查清单

在开始开发前，请确认以下配置项已完成：

企业微信后台配置

企业微信应用已创建（IIT Manager Agent）
应用可见范围已设置（包含测试用户）
企业可信IP已添加（本地开发可跳过，生产环境必须配置）
Token和EncodingAESKey已生成
回调URL已配置并验证成功（用于接收消息）

环境变量配置 - 企业微信

WECHAT_CORP_ID 已配置（ww6ab493470ab4f377）
WECHAT_AGENT_ID 已配置（1000002）
WECHAT_CORP_SECRET 已配置
WECHAT_TOKEN 已配置
WECHAT_ENCODING_AES_KEY 已配置
WECHAT_TEST_USER_ID 已配置（FengZhiBo）

数据库配置 - REDCap项目

test0102项目已在数据库中（iit_schema.projects）
项目状态为active
REDCap URL和API Token已配置

功能测试

使用官方调试工具成功获取Access Token
使用官方调试工具成功发送文本消息
使用官方调试工具成功发送卡片消息
使用官方调试工具成功发送Markdown消息
后端服务启动成功，日志显示"企业微信服务初始化成功"
回调URL验证成功
完整闭环测试通过（REDCap → Node.js → 企业微信）
REDCap查询测试通过（test0102项目，10条记录）
AI对话集成REDCap数据测试通过（真实数据，无幻觉）

📚 相关文档

企业微信官方文档

项目文档

[Day 3 企业微信集成开发完成记录](../docs/03-业务模块/IIT Manager Agent/06-开发记录/Day3-企业微信集成开发完成记录.md)
[最小MVP闭环开发计划](../docs/03-业务模块/IIT Manager Agent/04-开发计划/最小MVP闭环开发计划.md)
[模块当前状态与开发指南](../docs/03-业务模块/IIT Manager Agent/00-模块当前状态与开发指南.md)

文档维护者：开发团队
最后更新：2026-01-03
测试状态：✅ 推送功能已验证通过

14 KiB Raw Blame History Unescape Escape

微信环境变量配置说明（企业微信 + 服务号）

📋 必需的环境变量

📝 配置项说明

1. WECHAT_CORP_ID

2. WECHAT_AGENT_ID

3. WECHAT_CORP_SECRET

4. WECHAT_TOKEN

5. WECHAT_ENCODING_AES_KEY

6. WECHAT_TEST_USER_ID（可选）

📝 REDCap项目配置说明

🔧 企业微信回调URL配置

本地开发（natapp + 公司备案域名）

生产环境（SAE）

⚠️ 重要提示

🧪 消息推送测试

测试工具地址

测试步骤

Step 1: 获取Access Token

Step 2: 发送测试消息

A. 文本消息（简单测试）

B. 卡片消息（数据录入通知）

C. Markdown消息（富文本）

测试结果记录

🚀 验证配置

步骤1：检查后端日志

步骤2：访问健康检查

步骤3：保存企业微信回调配置

👤 如何获取UserID

方法1：通过管理后台查看（推荐）

方法2：通过API获取部门成员列表

方法3：使用特殊UserID

📞 常见问题

Q1: 保存回调URL时提示"URL验证失败"

Q2: 收不到企业微信消息

Q3: 发送消息提示"invalid user"

Q4: 获取Access Token提示"60020"错误

Q5: 官方调试工具测试成功，但代码发送失败

✅ 配置检查清单

企业微信后台配置

环境变量配置 - 企业微信

数据库配置 - REDCap项目

功能测试

📚 相关文档

企业微信官方文档

项目文档

14 KiB

Raw Blame History