AIclinicalresearch/backend/WECHAT_MP_CONFIG_READY.md

微信服务号配置完成清单

生成时间: 2026-01-04
服务号: AI for 临床研究
AppID: wx062568ff49e4570c

---

🎯 一、立即配置（复制即用）

1.1 环境变量配置

请将以下内容添加到 backend/.env 文件：

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

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

# 微信服务号回调配置（消息加解密，安全模式）
WECHAT_MP_TOKEN=IitPatientWechat2026JanToken
WECHAT_MP_ENCODING_AES_KEY=7yK9mN4pQ2wX5vL8hG3jR6tU1nB0cF9eM7aZ4xS2dY5

# 微信小程序配置（可选，后续开发）
WECHAT_MINI_APP_ID=

1.2 微信公众平台配置

登录地址: https://mp.weixin.qq.com/
配置路径: 设置与开发 → 基本配置 → 服务器配置 → 修改配置

填写以下参数：

配置项	值
URL	https://iit.xunzhengyixue.com/api/v1/iit/patient-wechat/callback
Token	IitPatientWechat2026JanToken
EncodingAESKey	7yK9mN4pQ2wX5vL8hG3jR6tU1nB0cF9eM7aZ4xS2dY5
消息加解密方式	✅ 安全模式（推荐）
数据格式	✅ XML

本地开发URL（使用natapp）：

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

---

📋 二、配置步骤（按顺序执行）

Step 1: 更新环境变量 ✅

# 1. 打开 backend/.env 文件
# 2. 复制上面1.1节的配置内容
# 3. 粘贴到文件末尾
# 4. 保存文件

Step 2: 验证配置 ✅

cd backend
npx tsx src/modules/iit-manager/test-patient-wechat-config.ts

期望输出：

✅ 配置检查通过！可以开始配置微信公众平台

Step 3: 启动后端服务 🔥

cd backend
npm run dev

期望输出：

✅ 微信服务号回调控制器初始化成功
✅ 微信服务号服务初始化成功
Registered route: GET /api/v1/iit/patient-wechat/callback
Registered route: POST /api/v1/iit/patient-wechat/callback
Server listening on http://0.0.0.0:3001

Step 4: 本地开发启动natapp（可选）

# 如果是本地开发，需要启动natapp内网穿透
cd D:\tools\natapp
natapp.exe -authtoken=YOUR_TOKEN -subdomain=devlocal

Step 5: 测试URL验证（本地）

新开一个终端，运行：

cd backend
npx tsx src/modules/iit-manager/test-patient-wechat-url-verify.ts

期望输出：

✅ URL验证成功！
✅ 返回的echostr正确，验证通过！
🎉 测试成功！您的服务端配置正确

Step 6: 配置微信公众平台 🔥

1. 登录微信公众平台：https://mp.weixin.qq.com/
2. 进入：设置与开发 → 基本配置 → 服务器配置
3. 点击 "修改配置"
4. 填写上面1.2节的配置参数
5. 点击 "提交"（微信会自动验证URL）
6. 如果验证成功，点击 "启用"

验证成功标志：

• ✅ 页面显示 "配置成功"
• ✅ "服务器配置" 状态为 "已启用"

如果验证失败：

• 查看后端日志是否收到GET请求
• 确认Token和EncodingAESKey与.env中完全一致
• 确认服务器可以从公网访问

Step 7: 测试消息接收

1. 用测试微信号关注公众号：AI for 临床研究
2. 发送文本消息：你好
3. 查看后端日志，应该看到：

📥 收到微信服务号回调消息
🔐 检测到加密消息，开始解密...
✅ 消息解密成功
💬 处理文本消息: 你好

---

🔍 三、常见问题排查

Q1: URL验证失败，提示"Token验证失败"

原因：Token配置不一致

解决方法：

1. 确认 .env 文件中的 WECHAT_MP_TOKEN 是 IitPatientWechat2026JanToken
2. 确认微信公众平台配置的Token也是 IitPatientWechat2026JanToken
3. 注意大小写和空格

Q2: URL验证失败，提示"请求URL超时"

原因：服务器无法访问

解决方法：

1. 确认后端服务已启动：npm run dev
2. 本地开发确认natapp已启动
3. 生产环境确认SAE应用正常运行
4. 浏览器访问：https://iit.xunzhengyixue.com/api/v1/iit/health 测试连通性

Q3: 提示"配置失败(48001)"

原因：AppID或AppSecret不正确

解决方法：

1. 确认 .env 中的 WECHAT_MP_APP_ID 和 WECHAT_MP_APP_SECRET 正确
2. 登录微信公众平台 → 开发 → 基本配置 → 查看AppID和AppSecret
3. 重新复制粘贴，确保无多余空格

Q4: 消息解密失败

原因：EncodingAESKey不一致或长度错误

解决方法：

1. 确认 .env 中的 WECHAT_MP_ENCODING_AES_KEY 长度为43位
2. 确认与微信公众平台配置完全一致（包括大小写）
3. 如果还是失败，重新生成EncodingAESKey并同步更新

---

⚠️ 四、重要提示

安全提示

1. ❗ Token和EncodingAESKey不要提交到Git
2. ❗ AppSecret不要泄露，不要提交到Git
3. ❗ 生产环境配置在SAE环境变量中，不要写在代码里

配置原则

1. ✅ .env 和微信公众平台的Token/EncodingAESKey必须完全一致
2. ✅ 修改配置后需要重启服务才能生效
3. ✅ 本地开发和生产环境可以使用相同的Token（推荐）
4. ✅ 如果配置错误，可以重新生成新的Token（运行 generate-wechat-tokens.ts）

IP白名单

生产环境需要配置IP白名单：

1. 登录微信公众平台 → 基本配置 → IP白名单
2. 添加SAE应用的出口IP
3. 可以从SAE控制台查看应用的出口IP

---

📊 五、开发进度

已完成 ✅

• PatientWechatCallbackController（服务号回调控制器）
• PatientWechatService（模板消息推送服务）
• 路由配置（GET/POST /api/v1/iit/patient-wechat/callback）
• 环境变量配置文档
• 配置检查脚本
• URL验证测试脚本
• Token生成脚本
• 接入指南文档

待测试 ⏳

• URL验证（配置微信公众平台）
• 消息接收（关注事件、文本消息）
• 消息解密（安全模式）

后续开发 📝

• 患者绑定功能（数据表 + H5页面）
• 模板消息推送（访视提醒）
• 客服消息回复（智能对话）
• 微信小程序开发

---

🚀 六、现在就开始！

方案A：生产环境部署（推荐）

# 1. 更新 backend/.env 文件（复制上面的配置）

# 2. 验证配置
cd backend
npx tsx src/modules/iit-manager/test-patient-wechat-config.ts

# 3. 部署到SAE
./deploy-to-sae.ps1

# 4. 配置微信公众平台（使用生产URL）

# 5. 测试功能（关注公众号、发送消息）

方案B：本地开发测试

# 1. 更新 backend/.env 文件（复制上面的配置）

# 2. 验证配置
cd backend
npx tsx src/modules/iit-manager/test-patient-wechat-config.ts

# 3. 启动natapp
cd D:\tools\natapp
natapp.exe -authtoken=YOUR_TOKEN -subdomain=devlocal

# 4. 启动后端服务
cd D:\MyCursor\AIclinicalresearch\backend
npm run dev

# 5. 测试URL验证
npx tsx src/modules/iit-manager/test-patient-wechat-url-verify.ts

# 6. 配置微信公众平台（使用本地开发URL）

# 7. 测试功能（关注公众号、发送消息）

---

推荐：先执行方案B（本地测试），测试通过后再执行方案A（生产部署）

---

📞 需要帮助？

如有问题，可以：

1. 查看后端日志（backend/logs/）
2. 运行配置检查脚本
3. 查看接入指南文档（backend/src/modules/iit-manager/docs/微信服务号接入指南.md）
4. 联系技术负责人

---

最后更新: 2026-01-04
文档版本: v1.0
状态: ✅ 配置就绪，等待测试