# 小程序二维码功能实现总结

## 实现状态：✅ 完成并优化

## 最新更新（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 无效问题