zyt/QRCODE_IMPLEMENTATION_SUMMARY.md

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

实现状态：✅ 完成并优化

最新更新（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

请求参数:

{
  "diagnosis_id": 123,
  "patient_id": 456,
  "share_user_id": 789
}

返回数据:

{
  "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: 使用清除脚本（推荐）

cd server
php clear_wx_token_cache.php

方法2: 手动清除缓存

rm -rf server/runtime/cache/*

方法3: 查看日志

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 无效问题