# 微信服务号配置完成清单

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