# 🔧 IIT回调地址修复方案

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

---

## 📋 一、问题描述

### 1.1 当前状态

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

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

### 1.2 目标状态

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

```yaml
生产环境回调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 验证服务可访问

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

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

### 4.2 验证企业微信回调

```bash
# 企业微信调试工具会自动验证
# 或手动测试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 验证微信服务号回调

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

### 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`**：
```typescript
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 开发环境（本地调试）

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

### 6.2 SAE测试环境

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

### 6.3 SAE生产环境

```yaml
使用方式: 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  
> **维护人员**：开发团队  
> **参考文档**：  
> - [企业微信开发文档](https://developer.work.weixin.qq.com/document/)  
> - [微信公众平台开发文档](https://developers.weixin.qq.com/doc/offiaccount/Getting_Started/Overview.html)