feat(pkb): Complete PKB module frontend migration with V3 design
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
This commit is contained in:
262
backend/WECHAT_MP_PLAIN_MODE.md
Normal file
262
backend/WECHAT_MP_PLAIN_MODE.md
Normal file
@@ -0,0 +1,262 @@
|
||||
# 微信服务号明文模式配置指南
|
||||
|
||||
> **目标**: 先用明文模式验证基础功能，成功后再升级到安全模式
|
||||
> **优势**: 明文模式更简单，无需处理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）
|
||||
|
||||
Reference in New Issue
Block a user