AIclinicalresearch/backend/WECHAT_MP_PLAIN_MODE.md

微信服务号明文模式配置指南

目标: 先用明文模式验证基础功能，成功后再升级到安全模式
优势: 明文模式更简单，无需处理AES加解密，便于调试
安全性: 明文模式不加密消息内容，仅用于开发测试，生产环境建议使用安全模式

---

📋 配置步骤（10分钟）

Step 1: 确认环境变量（1分钟）

确保 .env 文件中已配置Token：

# 微信服务号配置
WECHAT_MP_APP_ID=wx062568ff49e4570c
WECHAT_MP_APP_SECRET=c0d19435d1a1e948939c16d767ec0faf
WECHAT_MP_TOKEN=IitPatientWechat2026JanToken

# 注意：明文模式不需要 WECHAT_MP_ENCODING_AES_KEY

Step 2: 启动服务（1分钟）

cd D:\MyCursor\AIclinicalresearch\backend
npm run dev

期望日志：

✅ 微信服务号回调控制器已初始化（明文模式）
Registered route: GET /wechat/patient/callback-plain (明文模式)
Registered route: POST /wechat/patient/callback-plain (明文模式)

Step 3: 本地测试（2分钟）

运行测试脚本：

cd D:\MyCursor\AIclinicalresearch\backend\src\modules\iit-manager
.\test-wechat-mp-plain.ps1

期望输出：

🔐 计算签名...
  SHA1签名: xxx...
  
🌐 测试1: 本地服务器（通过natapp）
  ✅ 请求成功 (200 OK)
  ✅ echostr 匹配成功！
  
🖥️ 测试2: 直接本地（localhost:3001）
  ✅ 请求成功 (200 OK)
  ✅ echostr 匹配成功！

Step 4: 配置微信公众平台（5分钟）

1. 登录微信公众平台
   访问：https://mp.weixin.qq.com/

2. 进入服务器配置
   左侧菜单 → 设置与开发 → 基本配置 → 服务器配置 → 修改配置

3. 填写配置信息

配置项	值
URL	https://devlocal.xunzhengyixue.com/wechat/patient/callback-plain
Token	IitPatientWechat2026JanToken
EncodingAESKey	留空（明文模式不需要）
消息加解密方式	明文模式 ⚠️ 重要！
数据格式	XML ⚠️ 必须选择XML！

4. 提交验证
   点击"提交"，微信会发送GET请求验证

5. 查看服务器日志
   应该看到：

   📥 收到微信服务号 URL 验证请求（明文模式）
   ✅ URL 验证成功，返回 echostr
   

6. 启用配置
   验证成功后，点击"启用"

---

✅ 验证成功标志

1. ✅ 微信公众平台显示"配置成功"
2. ✅ 服务器日志显示"URL 验证成功"
3. ✅ 配置已启用

---

🧪 测试功能

测试1: 关注事件

1. 用微信扫码关注公众号：AI for 临床研究
2. 查看服务器日志：

期望日志：

📥 收到微信服务号回调消息（明文模式）
✅ 签名验证成功
📝 开始异步处理消息
🎯 处理事件消息: subscribe
👤 用户关注公众号: oXXXXXXX

测试2: 文本消息

1. 在公众号对话框发送：你好
2. 查看服务器日志：

期望日志：

📥 收到微信服务号回调消息（明文模式）
✅ 签名验证成功
💬 处理文本消息: 你好

---

🔄 升级到安全模式

明文模式验证成功后，可以升级到安全模式：

Step 1: 生成EncodingAESKey

使用微信公众平台的"随机生成"按钮，或运行：

cd D:\MyCursor\AIclinicalresearch\backend\src\modules\iit-manager
npx tsx generate-wechat-tokens.ts

Step 2: 更新环境变量

在 .env 中添加：

WECHAT_MP_ENCODING_AES_KEY=VIzwMGRG4Ll8Sd7fPxPXLlBaWdsh2rK2qIGpyaEoc1v

Step 3: 重启服务

# 停止当前服务（Ctrl+C）
npm run dev

Step 4: 修改微信公众平台配置

将URL从明文模式切换到安全模式：

配置项	修改前（明文模式）	修改后（安全模式）
URL	/wechat/patient/callback-plain	/wechat/patient/callback
EncodingAESKey	留空	VIzwMGRG4...
消息加解密方式	明文模式	安全模式（推荐）

Step 5: 提交验证

点击"提交"，验证成功后点击"启用"

---

🔍 故障排查

问题1: 本地测试失败（400 Bad Request）

原因: Fastify Schema校验失败

解决:

• 检查路由配置是否添加了 additionalProperties: true
• 查看服务器日志详细错误信息

问题2: 微信平台配置失败（200002）

原因: 入参错误

检查项：

1. ✅ URL是否正确（是否包含 -plain 后缀）
2. ✅ Token是否与环境变量一致
3. ✅ 消息加解密方式是否选择"明文模式"
4. ✅ natapp是否正常运行
5. ✅ 服务器是否正常运行

问题3: 服务器日志无响应

可能原因：

1. ❌ natapp未启动或配置错误
2. ❌ 服务器未启动
3. ❌ 路由未注册
4. ❌ 防火墙拦截

排查步骤：

# 1. 测试健康检查接口
curl https://devlocal.xunzhengyixue.com/api/v1/iit/health

# 2. 测试明文模式路由（通过natapp）
.\test-wechat-mp-plain.ps1

# 3. 测试直接访问localhost
curl http://localhost:3001/api/v1/iit/health

---

📊 明文模式 vs 安全模式对比

特性	明文模式	安全模式
配置复杂度	⭐ 简单	⭐⭐⭐ 复杂
调试难度	⭐ 容易	⭐⭐⭐ 困难
安全性	⚠️ 低（消息明文传输）	✅ 高（AES加密）
是否需要EncodingAESKey	❌ 不需要	✅ 需要
消息加解密	❌ 无加密	✅ AES加密
适用场景	🧪 开发测试	🚀 生产环境
推荐度	⚠️ 仅测试用	✅ 强烈推荐

---

🎯 建议的开发流程

1. 明文模式（开发测试）
   ↓
   验证基础功能正常
   ↓
2. 安全模式（生产环境）
   ↓
   验证加解密正常
   ↓
3. 部署到SAE
   ↓
   使用生产域名 iit.xunzhengyixue.com

---

📝 相关文档

• 微信服务号接入指南
• 环境变量配置
• SAE部署步骤

---

创建时间: 2026-01-04
文档版本: v1.0
模式: 明文模式（Plain Text Mode）