HaHafeng
5a17d096a7
Summary: - Implement PKB Dashboard and Workspace pages based on V3 prototype - Add single-layer header with integrated Tab navigation - Implement 3 work modes: Full Text, Deep Read, Batch Processing - Integrate Ant Design X Chat component for AI conversations - Create BatchModeComplete with template selection and document processing - Add compact work mode selector with dropdown design Backend: - Migrate PKB controllers and services to /modules/pkb structure - Register v2 API routes at /api/v2/pkb/knowledge - Maintain dual API routes for backward compatibility Technical details: - Use Zustand for state management - Handle SSE streaming responses for AI chat - Support document selection for Deep Read mode - Implement batch processing with progress tracking Known issues: - Batch processing API integration pending - Knowledge assets page navigation needs optimization Status: Frontend functional, pending refinement
263 lines
6.2 KiB
Markdown
263 lines
6.2 KiB
Markdown
# 微信服务号明文模式配置指南
|
||
|
||
> **目标**: 先用明文模式验证基础功能，成功后再升级到安全模式
|
||
> **优势**: 明文模式更简单，无需处理AES加解密，便于调试
|
||
> **安全性**: 明文模式不加密消息内容，仅用于开发测试，生产环境建议使用安全模式
|
||
|
||
---
|
||
|
||
## 📋 配置步骤（10分钟）
|
||
|
||
### Step 1: 确认环境变量（1分钟）
|
||
|
||
确保 `.env` 文件中已配置Token：
|
||
|
||
```bash
|
||
# 微信服务号配置
|
||
WECHAT_MP_APP_ID=wx062568ff49e4570c
|
||
WECHAT_MP_APP_SECRET=c0d19435d1a1e948939c16d767ec0faf
|
||
WECHAT_MP_TOKEN=IitPatientWechat2026JanToken
|
||
|
||
# 注意：明文模式不需要 WECHAT_MP_ENCODING_AES_KEY
|
||
```
|
||
|
||
### Step 2: 启动服务（1分钟）
|
||
|
||
```powershell
|
||
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分钟）
|
||
|
||
运行测试脚本：
|
||
|
||
```powershell
|
||
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
|
||
|
||
使用微信公众平台的"随机生成"按钮，或运行：
|
||
|
||
```powershell
|
||
cd D:\MyCursor\AIclinicalresearch\backend\src\modules\iit-manager
|
||
npx tsx generate-wechat-tokens.ts
|
||
```
|
||
|
||
### Step 2: 更新环境变量
|
||
|
||
在 `.env` 中添加：
|
||
|
||
```bash
|
||
WECHAT_MP_ENCODING_AES_KEY=VIzwMGRG4Ll8Sd7fPxPXLlBaWdsh2rK2qIGpyaEoc1v
|
||
```
|
||
|
||
### Step 3: 重启服务
|
||
|
||
```powershell
|
||
# 停止当前服务（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. ❌ 防火墙拦截
|
||
|
||
**排查步骤**：
|
||
```powershell
|
||
# 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
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 相关文档
|
||
|
||
- [微信服务号接入指南](./src/modules/iit-manager/docs/微信服务号接入指南.md)
|
||
- [环境变量配置](./WECHAT_ENV_CONFIG.md)
|
||
- [SAE部署步骤](./SAE_WECHAT_MP_DEPLOY_STEPS.md)
|
||
|
||
---
|
||
|
||
**创建时间**: 2026-01-04
|
||
**文档版本**: v1.0
|
||
**模式**: 明文模式（Plain Text Mode）
|
||
|