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:
300
backend/WECHAT_MP_CONFIG_READY.md
Normal file
300
backend/WECHAT_MP_CONFIG_READY.md
Normal file
@@ -0,0 +1,300 @@
|
||||
# 微信服务号配置完成清单
|
||||
|
||||
> **生成时间**: 2026-01-04
|
||||
> **服务号**: AI for 临床研究
|
||||
> **AppID**: wx062568ff49e4570c
|
||||
|
||||
---
|
||||
|
||||
## 🎯 一、立即配置（复制即用）
|
||||
|
||||
### 1.1 环境变量配置
|
||||
|
||||
**请将以下内容添加到 `backend/.env` 文件：**
|
||||
|
||||
```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: 更新环境变量 ✅
|
||||
|
||||
```bash
|
||||
# 1. 打开 backend/.env 文件
|
||||
# 2. 复制上面1.1节的配置内容
|
||||
# 3. 粘贴到文件末尾
|
||||
# 4. 保存文件
|
||||
```
|
||||
|
||||
### Step 2: 验证配置 ✅
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
npx tsx src/modules/iit-manager/test-patient-wechat-config.ts
|
||||
```
|
||||
|
||||
**期望输出**：
|
||||
```
|
||||
✅ 配置检查通过！可以开始配置微信公众平台
|
||||
```
|
||||
|
||||
### Step 3: 启动后端服务 🔥
|
||||
|
||||
```bash
|
||||
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（可选）
|
||||
|
||||
```bash
|
||||
# 如果是本地开发，需要启动natapp内网穿透
|
||||
cd D:\tools\natapp
|
||||
natapp.exe -authtoken=YOUR_TOKEN -subdomain=devlocal
|
||||
```
|
||||
|
||||
### Step 5: 测试URL验证（本地）
|
||||
|
||||
新开一个终端，运行：
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
---
|
||||
|
||||
## 📊 五、开发进度
|
||||
|
||||
### 已完成 ✅
|
||||
- [x] PatientWechatCallbackController（服务号回调控制器）
|
||||
- [x] PatientWechatService（模板消息推送服务）
|
||||
- [x] 路由配置（GET/POST /api/v1/iit/patient-wechat/callback）
|
||||
- [x] 环境变量配置文档
|
||||
- [x] 配置检查脚本
|
||||
- [x] URL验证测试脚本
|
||||
- [x] Token生成脚本
|
||||
- [x] 接入指南文档
|
||||
|
||||
### 待测试 ⏳
|
||||
- [ ] URL验证（配置微信公众平台）
|
||||
- [ ] 消息接收（关注事件、文本消息）
|
||||
- [ ] 消息解密（安全模式）
|
||||
|
||||
### 后续开发 📝
|
||||
- [ ] 患者绑定功能（数据表 + H5页面）
|
||||
- [ ] 模板消息推送（访视提醒）
|
||||
- [ ] 客服消息回复（智能对话）
|
||||
- [ ] 微信小程序开发
|
||||
|
||||
---
|
||||
|
||||
## 🚀 六、现在就开始！
|
||||
|
||||
### 方案A：生产环境部署（推荐）
|
||||
|
||||
```bash
|
||||
# 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：本地开发测试
|
||||
|
||||
```bash
|
||||
# 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
|
||||
**状态**: ✅ 配置就绪，等待测试
|
||||
|
||||
Reference in New Issue
Block a user