AIclinicalresearch/docs/05-部署文档/0126部署/06-IIT回调地址修复方案.md

🔧 IIT回调地址修复方案

文档版本：v1.0
创建日期：2026-01-26
适用范围：IIT Manager Agent模块
变更类型：配置修复 + 地址变更

---

📋 一、问题描述

1.1 当前状态

IIT Manager Agent模块目前使用 natapp内网穿透 进行开发调试：

开发环境回调URL: https://devlocal.xunzhengyixue.com/api/v1/iit/patient-wechat/callback
使用方式: natapp内网穿透映射到本地127.0.0.1:3001
适用场景: 本地开发调试

1.2 目标状态

部署到SAE生产环境后，需要使用真实生产域名：

生产环境回调URL: https://iit.xunzhengyixue.com/api/v1/iit/patient-wechat/callback
使用方式: 直接访问SAE服务
适用场景: 生产环境

1.3 涉及的回调类型

回调类型	开发环境URL	生产环境URL
企业微信回调	https://devlocal.xunzhengyixue.com/api/v1/iit/wechat/callback	https://iit.xunzhengyixue.com/api/v1/iit/wechat/callback
微信服务号回调	https://devlocal.xunzhengyixue.com/api/v1/iit/patient-wechat/callback	https://iit.xunzhengyixue.com/api/v1/iit/patient-wechat/callback
REDCap DET Webhook	http://localhost:3001/api/v1/iit/webhooks/redcap	https://iit.xunzhengyixue.com/api/v1/iit/webhooks/redcap

---

🔍 二、代码中的地址检查

2.1 已确认的地址引用位置

通过代码搜索，发现以下位置涉及回调地址：

1. 文档中的地址（需要更新）：

• backend/WECHAT_MP_CONFIG_READY.md
• backend/WECHAT_ENV_CONFIG.md
• backend/src/modules/iit-manager/docs/微信服务号接入指南.md
• backend/DEPLOY_TO_SAE_FOR_WECHAT_MP.md

2. 测试脚本中的地址（保持开发地址，用于本地测试）：

• backend/src/modules/iit-manager/test-wechat-mp-local.ps1
• backend/src/modules/iit-manager/test-wechat-mp-plain.ps1
• backend/src/modules/iit-manager/test-patient-wechat-config.ts

3. 代码生成工具中的地址（需要更新提示信息）：

• backend/src/modules/iit-manager/generate-wechat-tokens.ts

2.2 代码本身无需修改

重要发现：代码本身没有硬编码回调地址！

回调处理是被动接收的，URL配置在：

• 企业微信后台
• 微信服务号后台
• REDCap系统设置

代码只需要正确响应请求即可。

---

🔧 三、配置修复步骤

3.1 企业微信回调配置

登录企业微信管理后台：

1. 访问：https://work.weixin.qq.com/wework_admin/loginpage_wx
2. 使用管理员账号登录

修改应用回调URL：

1. 进入【应用管理】→【IIT Manager Agent】
2. 找到【接收消息】配置
3. 修改URL：

   旧：https://devlocal.xunzhengyixue.com/api/v1/iit/wechat/callback
   新：https://iit.xunzhengyixue.com/api/v1/iit/wechat/callback
   

4. 保持Token和EncodingAESKey不变：

   Token: oXlRBm1YnvMy2SbDLbvAdDd5Gq3oBGq
   EncodingAESKey: v88eT3O9bMW897h4btr7v7qvQImlMf31edTQCmuhOhO
   

5. 点击【保存】
6. 等待企业微信验证回调URL

3.2 微信服务号回调配置

登录微信公众平台：

1. 访问：https://mp.weixin.qq.com/
2. 使用管理员账号登录

修改服务器配置：

1. 进入【设置与开发】→【基本配置】
2. 找到【服务器配置】
3. 点击【修改配置】
4. 修改服务器地址(URL)：

   旧：https://devlocal.xunzhengyixue.com/api/v1/iit/patient-wechat/callback
   新：https://iit.xunzhengyixue.com/api/v1/iit/patient-wechat/callback
   

5. 保持Token和EncodingAESKey不变
6. 点击【提交】
7. 等待微信验证服务器配置

3.3 REDCap DET配置（如使用）

在REDCap管理后台配置：

1. 登录REDCap Control Center
2. 进入项目设置
3. 找到Data Entry Trigger (DET)配置
4. 修改Webhook URL：

   旧：http://localhost:3001/api/v1/iit/webhooks/redcap
   新：https://iit.xunzhengyixue.com/api/v1/iit/webhooks/redcap
   

---

✅ 四、验证步骤

4.1 验证服务可访问

# 1. 验证健康检查端点
curl https://iit.xunzhengyixue.com/api/v1/iit/health

# 预期返回：{ "status": "ok", ... }

4.2 验证企业微信回调

# 企业微信调试工具会自动验证
# 或手动测试GET请求（URL验证）

curl "https://iit.xunzhengyixue.com/api/v1/iit/wechat/callback?msg_signature=test&timestamp=123&nonce=abc&echostr=hello"

# 如果返回echostr内容（hello），说明验证通过

4.3 验证微信服务号回调

# 微信平台会自动发送验证请求
# 验证成功后状态显示"已启用"

4.4 端到端测试

1. 企业微信测试：

   • 在企业微信中向IIT Manager Agent发送消息
   • 确认收到AI回复

2. 微信服务号测试：

   • 关注服务号并发送消息
   • 确认收到回复

3. REDCap测试（如配置）：

   • 在REDCap中保存一条记录
   • 确认触发Webhook并处理成功

---

📝 五、文档更新清单

5.1 需要更新的文档

以下文档中的地址引用需要更新或添加说明：

文档路径	更新内容
backend/WECHAT_MP_CONFIG_READY.md	添加生产环境URL说明
backend/WECHAT_ENV_CONFIG.md	更新URL配置说明
backend/DEPLOY_TO_SAE_FOR_WECHAT_MP.md	确认生产URL正确
docs/03-业务模块/IIT Manager Agent/00-模块当前状态与开发指南.md	更新回调URL状态

5.2 代码文件更新（可选）

更新提示信息，帮助开发者区分环境：

generate-wechat-tokens.ts：

console.log('回调URL配置：');
console.log('  开发环境：https://devlocal.xunzhengyixue.com/api/v1/iit/patient-wechat/callback');
console.log('  生产环境：https://iit.xunzhengyixue.com/api/v1/iit/patient-wechat/callback');

---

🔄 六、环境切换说明

6.1 开发环境（本地调试）

使用方式: natapp内网穿透
启动命令: natapp.exe -authtoken=YOUR_TOKEN -subdomain=devlocal
回调URL: https://devlocal.xunzhengyixue.com/...
后端地址: 127.0.0.1:3001

6.2 SAE测试环境

使用方式: SAE服务 + 测试数据库
回调URL: https://iit.xunzhengyixue.com/...（可配置测试域名）
后端地址: SAE内网IP:3001

6.3 SAE生产环境

使用方式: SAE服务 + 生产数据库
回调URL: https://iit.xunzhengyixue.com/...
后端地址: SAE内网IP:3001
公网访问: https://iit.xunzhengyixue.com/

---

⚠️ 七、注意事项

7.1 域名备案

iit.xunzhengyixue.com 域名必须已完成ICP备案，否则无法在微信平台使用。

确认状态：✅ 已备案（根据历史记录）

7.2 SSL证书

回调URL必须使用HTTPS，确认SSL证书：

• 证书有效期
• 证书链完整
• 域名匹配

7.3 防火墙/安全组

确保SAE服务可以接收来自：

• 企业微信服务器的请求
• 微信公众平台服务器的请求
• REDCap服务器的请求

7.4 Token和密钥管理

切勿泄露：

• Token
• EncodingAESKey
• Corp Secret

这些密钥在开发和生产环境可以相同，但要确保安全存储。

---

📊 八、检查清单

部署前

• 确认SAE后端服务已部署并正常运行
• 确认 https://iit.xunzhengyixue.com/api/v1/iit/health 可访问
• 确认域名SSL证书有效

配置修改

• 企业微信回调URL已更新
• 微信服务号回调URL已更新
• REDCap DET URL已更新（如使用）

验证

• 企业微信URL验证通过
• 微信服务号URL验证通过
• 企业微信消息收发正常
• 微信服务号消息收发正常
• REDCap Webhook触发正常（如使用）

---

📞 九、问题排查

问题1：URL验证失败

可能原因：

• 后端服务未启动
• SSL证书问题
• 回调路由未注册

排查步骤：

1. 检查健康端点：curl https://iit.xunzhengyixue.com/api/v1/iit/health
2. 检查回调端点：curl https://iit.xunzhengyixue.com/api/v1/iit/wechat/callback
3. 查看SAE日志

问题2：消息无响应

可能原因：

• 消息加解密配置错误
• AI服务调用超时
• 数据库连接问题

排查步骤：

1. 检查SAE日志中的错误信息
2. 确认环境变量配置正确
3. 测试AI服务连接

问题3：超时错误

可能原因：

• 微信要求5秒内响应
• AI处理时间过长

解决方案：

• 代码已使用异步回复模式（setImmediate）
• 确保先返回空字符串，再异步推送消息

---

最后更新：2026-01-26
维护人员：开发团队
参考文档：

• 企业微信开发文档
• 微信公众平台开发文档