206 lines
5.2 KiB
Markdown
206 lines
5.2 KiB
Markdown
# 小程序二维码功能实现总结
|
||
|
||
## 实现状态：✅ 完成并优化
|
||
|
||
## 最新更新（2024-03-06）
|
||
|
||
### 问题修复
|
||
- ✅ 修复 AccessToken 无效错误（errcode 40001）
|
||
- ✅ 添加详细的日志记录
|
||
- ✅ 自动清除无效的 AccessToken 缓存
|
||
- ✅ 改进错误提示信息
|
||
- ✅ 添加保存图片失败检测
|
||
|
||
### 新增工具
|
||
- ✅ 创建缓存清除脚本：`server/clear_wx_token_cache.php`
|
||
- ✅ 创建调试指南：`QRCODE_DEBUG_GUIDE.md`
|
||
|
||
## 修改的文件
|
||
|
||
### 前端文件
|
||
1. `admin/src/views/tcm/diagnosis/index.vue`
|
||
- 添加小程序二维码按钮点击事件
|
||
- 实现二维码生成逻辑
|
||
- 添加二维码显示弹窗
|
||
- 集成加载状态和错误处理
|
||
|
||
2. `admin/src/api/tcm.ts`
|
||
- 已存在 `generateMiniProgramQrcode()` 接口（无需修改）
|
||
|
||
### 后端文件
|
||
1. `server/app/adminapi/controller/tcm/DiagnosisController.php`
|
||
- `generateMiniProgramQrcode()` 方法（已存在）
|
||
|
||
2. `server/app/adminapi/logic/tcm/DiagnosisLogic.php` ⭐ 已优化
|
||
- `generateMiniProgramQrcode()` - 主方法
|
||
- `getMiniProgramConfig()` - 获取配置
|
||
- `generateWxQrcode()` - 生成二维码（已优化）
|
||
- ✅ 添加详细日志记录
|
||
- ✅ 改进错误处理
|
||
- ✅ 自动清除无效缓存
|
||
- `getWxAccessToken()` - 获取Token（已优化）
|
||
- ✅ 添加错误检测
|
||
- ✅ 记录原始响应
|
||
- ✅ 详细的错误信息
|
||
- `httpGet()` / `httpPost()` - HTTP工具
|
||
|
||
3. `server/app/adminapi/validate/tcm/DiagnosisValidate.php`
|
||
- `sceneGenerateQrcode()` - 验证规则（已存在）
|
||
|
||
### 新增文件
|
||
1. `server/clear_wx_token_cache.php` - AccessToken缓存清除工具
|
||
2. `QRCODE_DEBUG_GUIDE.md` - 问题排查指南
|
||
|
||
## 核心功能
|
||
|
||
### 1. 前端功能
|
||
- ✅ 点击按钮触发生成
|
||
- ✅ 验证小程序配置
|
||
- ✅ 调用后端接口
|
||
- ✅ 显示加载状态
|
||
- ✅ 展示二维码图片
|
||
- ✅ 错误提示
|
||
- ✅ 支持重新生成
|
||
|
||
### 2. 后端功能
|
||
- ✅ 获取小程序配置（AppID、AppSecret）
|
||
- ✅ 获取微信AccessToken（带缓存）
|
||
- ✅ 调用微信API生成小程序码
|
||
- ✅ 保存二维码图片到本地
|
||
- ✅ 返回图片URL
|
||
- ✅ 参数验证
|
||
- ✅ 错误处理
|
||
- ✅ 详细日志记录
|
||
- ✅ 自动缓存清除
|
||
|
||
## 技术要点
|
||
|
||
### 微信小程序码生成
|
||
- API: `https://api.weixin.qq.com/wxa/getwxacodeunlimit`
|
||
- 方式: 无限制生成（通过scene参数）
|
||
- 参数传递: `id={诊单ID}&share_user={分享用户ID}`
|
||
- 跳转页面: `pages/order/monad/monad`
|
||
|
||
### AccessToken管理（已优化）
|
||
- 自动获取并缓存
|
||
- 缓存时长: 7000秒
|
||
- 避免频繁请求微信服务器
|
||
- ✅ 错误时自动清除缓存
|
||
- ✅ 详细的日志记录
|
||
|
||
### 图片存储
|
||
- 路径: `public/uploads/qrcode/{日期}/`
|
||
- 命名: `qrcode_{appId}_{md5}_{timestamp}.png`
|
||
- 自动创建目录
|
||
- ✅ 保存失败检测
|
||
|
||
### 日志记录（新增）
|
||
- 记录所有关键步骤
|
||
- 记录微信API响应
|
||
- 记录错误详情
|
||
- 日志位置: `server/runtime/log/`
|
||
|
||
## 接口信息
|
||
|
||
**接口**: `/adminapi/tcm.diagnosis/generateMiniProgramQrcode`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"diagnosis_id": 123,
|
||
"patient_id": 456,
|
||
"share_user_id": 789
|
||
}
|
||
```
|
||
|
||
**返回数据**:
|
||
```json
|
||
{
|
||
"code": 1,
|
||
"msg": "success",
|
||
"data": {
|
||
"qrcode_url": "http://domain.com/uploads/qrcode/20240306/xxx.png",
|
||
"diagnosis_id": 123,
|
||
"patient_id": 456
|
||
}
|
||
}
|
||
```
|
||
|
||
## 使用说明
|
||
|
||
### 配置步骤
|
||
1. 进入后台：渠道设置 -> 微信小程序设置
|
||
2. 填写 AppID 和 AppSecret
|
||
3. 保存配置
|
||
|
||
### 使用步骤
|
||
1. 进入：中医管理 -> 诊断管理
|
||
2. 找到患者记录
|
||
3. 点击"小程序二维码"按钮
|
||
4. 查看生成的二维码
|
||
5. 使用微信扫描
|
||
|
||
## 问题排查
|
||
|
||
### 遇到 AccessToken 错误时
|
||
|
||
#### 方法1: 使用清除脚本（推荐）
|
||
```bash
|
||
cd server
|
||
php clear_wx_token_cache.php
|
||
```
|
||
|
||
#### 方法2: 手动清除缓存
|
||
```bash
|
||
rm -rf server/runtime/cache/*
|
||
```
|
||
|
||
#### 方法3: 查看日志
|
||
```bash
|
||
tail -f server/runtime/log/$(date +%Y%m%d).log
|
||
```
|
||
|
||
### 常见错误
|
||
- **40001**: AccessToken无效 → 清除缓存重试
|
||
- **40013**: AppID无效 → 检查配置
|
||
- **40125**: AppSecret无效 → 重置AppSecret
|
||
- **40164**: IP不在白名单 → 添加服务器IP
|
||
|
||
详细排查步骤请参考：`QRCODE_DEBUG_GUIDE.md`
|
||
|
||
## 权限要求
|
||
- 权限标识: `tcm.diagnosis/guahao`
|
||
|
||
## 注意事项
|
||
1. ⚠️ 必须先配置小程序 AppID 和 AppSecret
|
||
2. ⚠️ 服务器需要能访问微信API
|
||
3. ⚠️ uploads 目录需要写入权限
|
||
4. ⚠️ 小程序中需要存在对应页面
|
||
5. ⚠️ Scene参数最大32个字符
|
||
6. ⚠️ 如遇到AccessToken错误，使用清除脚本
|
||
|
||
## 测试建议
|
||
1. ✅ 测试正常生成流程
|
||
2. ✅ 测试未配置小程序的情况
|
||
3. ✅ 测试重新生成功能
|
||
4. ✅ 测试扫码跳转
|
||
5. ✅ 测试并发生成
|
||
6. ✅ 测试AccessToken缓存
|
||
7. ✅ 测试错误恢复（清除缓存后重试）
|
||
|
||
## 相关文档
|
||
- `MINI_PROGRAM_QRCODE_FEATURE.md` - 详细功能说明
|
||
- `TEST_MINI_PROGRAM_QRCODE.md` - 测试指南
|
||
- `QRCODE_DEBUG_GUIDE.md` - 问题排查指南（新增）
|
||
|
||
## 完成时间
|
||
- 初始实现: 2024-03-06
|
||
- 优化更新: 2024-03-06
|
||
|
||
## 开发者备注
|
||
1. 后端功能已经完整实现
|
||
2. 本次主要完善前端调用逻辑
|
||
3. 添加详细日志和错误处理
|
||
4. 提供问题排查工具和文档
|
||
5. 修复 AccessToken 无效问题
|