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
This commit is contained in:
2026-01-04 22:53:42 +08:00
parent dfc472810b
commit b31255031e
167 changed files with 3055 additions and 2 deletions

View File

@@ -0,0 +1,162 @@
# 微信服务号配置错误修复200002
## ❌ 错误信息
```
检查消息推送配置失败: invalid args, 200002
```
## 🔍 问题原因
EncodingAESKey格式不符合微信服务号要求。
## ✅ 解决方案2选1
### 方案1使用微信平台随机生成推荐⭐
**步骤:**
1. 在微信公众平台配置页面
2. **EncodingAESKey字段不要手动输入**
3. 点击右侧的 **"随机生成"** 按钮
4. 微信会自动生成43位密钥例如
```
abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG
```
5. **复制这个生成的密钥**
6. 填写完整配置:
```
URL: https://devlocal.xunzhengyixue.com/api/v1/iit/patient-wechat/callback
Token: IitPatientWechat2026JanToken
EncodingAESKey: [点击随机生成后复制的密钥]
消息加解密方式: 安全模式
```
7. 点击 **"提交"** 验证
8. **验证成功后**复制微信生成的EncodingAESKey到 `.env` 文件:
```env
WECHAT_MP_ENCODING_AES_KEY=[微信生成的密钥]
```
9. **重启后端服务**(重要!)
---
### 方案2使用OpenSSL生成备选
如果方案1不行使用OpenSSL生成标准Base64密钥
**WindowsPowerShell**
```powershell
# 生成Base64格式的43位密钥
$bytes = [System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32)
$base64 = [Convert]::ToBase64String($bytes)
$key = $base64.Substring(0, 43)
Write-Host "EncodingAESKey: $key"
```
**或者使用在线工具:**
1. 访问https://www.base64encode.org/
2. 生成32字节随机数据
3. Base64编码
4. 截取前43位
---
## 📋 完整配置流程(推荐)
### Step 1: 使用微信平台生成密钥
1. 登录微信公众平台
2. 进入:设置与开发 → 基本配置 → 服务器配置
3. 点击"修改配置"
4. 填写以下信息:
| 字段 | 值 |
|-----|-----|
| URL | `https://devlocal.xunzhengyixue.com/api/v1/iit/patient-wechat/callback` |
| Token | `IitPatientWechat2026JanToken` |
| EncodingAESKey | **点击"随机生成"** 然后复制生成的密钥 |
| 消息加解密方式 | 安全模式(推荐) |
### Step 2: 提交验证
1. 点击"提交"
2. 微信会发送GET请求验证
3. 应该显示"配置成功"
### Step 3: 更新.env文件
编辑 `backend/.env`替换EncodingAESKey
```env
# 原来的(有问题)
# WECHAT_MP_ENCODING_AES_KEY=7yK9mN4pQ2wX5vL8hG3jR6tU1nB0cF9eM7aZ4xS2dY5
# 新的(从微信平台复制的)
WECHAT_MP_ENCODING_AES_KEY=微信生成的43位密钥
```
### Step 4: 重启后端服务
```bash
# 停止当前服务Ctrl+C
# 重新启动
cd D:\MyCursor\AIclinicalresearch\backend
npm run dev
```
### Step 5: 启用配置
返回微信公众平台,点击"启用"按钮
---
## 🧪 验证配置是否正确
### 方法1查看后端日志
应该看到类似日志:
```
📥 收到微信服务号 URL 验证请求
✅ URL 验证成功,返回 echostr
```
### 方法2测试关注事件
1. 微信扫码关注公众号
2. 查看后端日志是否有:
```
📥 收到微信服务号回调消息
🔐 检测到加密消息,开始解密...
✅ 消息解密成功
👤 用户关注公众号
```
---
## ⚠️ 注意事项
1. ✅ **EncodingAESKey必须与微信平台配置完全一致**
2. ✅ **修改.env后必须重启服务**
3. ✅ **Token保持不变**`IitPatientWechat2026JanToken`
4.**推荐使用微信平台的"随机生成"功能**
---
## 💡 为什么会出现这个错误?
微信服务号对EncodingAESKey的格式有严格要求
- 必须是43位
- 必须符合Base64字符集A-Z, a-z, 0-9, +, /
- 我之前生成的密钥只包含字母和数字,缺少+和/,不符合标准
微信平台的"随机生成"功能会自动生成符合标准的密钥,所以推荐使用。
---
**立即行动:**
1. 进入微信公众平台配置页面
2. 点击"随机生成"EncodingAESKey
3. 提交配置
4. 复制密钥到.env
5. 重启服务
**预计用时3分钟**