Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
61cdc97eeb56b1e124453326f2132a4f3fe193e0
AIclinicalresearch/backend/WECHAT_MP_CONFIG_READY.md
HaHafeng 61cdc97eeb feat(platform): Fix pg-boss queue conflict and add safety standards 
Summary:
- Fix pg-boss queue conflict (duplicate key violation on queue_pkey)
- Add global error listener to prevent process crash
- Reduce connection pool from 10 to 4
- Add graceful shutdown handling (SIGTERM/SIGINT)
- Fix researchWorker recursive call bug in catch block
- Make screeningWorker idempotent using upsert

Security Standards (v1.1):
- Prohibit recursive retry in Worker catch blocks
- Prohibit payload bloat (only store fileKey/ID in job.data)
- Require Worker idempotency (upsert + unique constraint)
- Recommend task-specific expireInSeconds settings
- Document graceful shutdown pattern

New Features:
- PKB signed URL endpoint for document preview/download
- pg_bigm installation guide for Docker
- Dockerfile.postgres-with-extensions for pgvector + pg_bigm

Documentation:
- Update Postgres-Only async task processing guide (v1.1)
- Add troubleshooting SQL queries
- Update safety checklist

Tested: Local verification passed
2026-01-23 22:07:26 +08:00

7.7 KiB
Raw Blame History

微信服务号配置完成清单

生成时间: 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
状态: ✅ 配置就绪，等待测试

Reference in New Issue View Git Blame Copy Permalink