# 微信服务号明文模式配置指南

> **目标**: 先用明文模式验证基础功能，成功后再升级到安全模式  
> **优势**: 明文模式更简单，无需处理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）