HaHafeng
40c2f8e148
Major Features: - Created ekb_schema (13th schema) with 3 tables: KB/Document/Chunk - Implemented EmbeddingService (text-embedding-v4, 1024-dim vectors) - Implemented ChunkService (smart Markdown chunking) - Implemented VectorSearchService (multi-query + hybrid search) - Implemented RerankService (qwen3-rerank) - Integrated DeepSeek V3 QueryRewriter for cross-language search - Python service: Added pymupdf4llm for PDF-to-Markdown conversion - PKB: Dual-mode adapter (pgvector/dify/hybrid) Architecture: - Brain-Hand Model: Business layer (DeepSeek) + Engine layer (pgvector) - Cross-language support: Chinese query matches English documents - Small Embedding (1024) + Strong Reranker strategy Performance: - End-to-end latency: 2.5s - Cost per query: 0.0025 RMB - Accuracy improvement: +20.5% (cross-language) Tests: - test-embedding-service.ts: Vector embedding verified - test-rag-e2e.ts: Full pipeline tested - test-rerank.ts: Rerank quality validated - test-query-rewrite.ts: Cross-language search verified - test-pdf-ingest.ts: Real PDF document tested (Dongen 2003.pdf) Documentation: - Added 05-RAG-Engine-User-Guide.md - Added 02-Document-Processing-User-Guide.md - Updated system status documentation Status: Production ready
326 lines
7.7 KiB
Markdown
326 lines
7.7 KiB
Markdown
# 微信服务号配置完成清单
|
||
|
||
> **生成时间**: 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
|
||
**状态**: ✅ 配置就绪，等待测试
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|