ZYT/zyt

Fork 0

Files

T

Your Name 52bb80e2f1 更新

2026-03-06 14:27:24 +08:00

6.2 KiB

Raw Blame History

小程序二维码功能 - 完整文档

📖 文档导航

🚀 快速开始

文件: QRCODE_QUICK_START.md

5分钟快速上手指南，包含：

配置步骤
使用方法
常见问题快速解决
常用命令

👉 推荐新手从这里开始

📋 功能详解

文件: MINI_PROGRAM_QRCODE_FEATURE.md

完整的功能说明文档，包含：

功能概述
前后端实现细节
接口文档
技术实现
配置要求

👉 了解功能细节必读

🧪 测试指南

文件: TEST_MINI_PROGRAM_QRCODE.md

详细的测试步骤和方法，包含：

前置条件
测试步骤
接口测试
常见问题排查
性能测试
安全检查

👉 测试人员必读

🔧 问题排查

文件: QRCODE_DEBUG_GUIDE.md

完整的问题排查指南，包含：

常见错误及解决方案
调试步骤
日志查看
网络检查
代码改进说明

👉 遇到问题时查阅

📝 实现总结

文件: QRCODE_IMPLEMENTATION_SUMMARY.md

开发实现的完整总结，包含：

修改的文件列表
核心功能说明
技术要点
使用说明
注意事项

👉 开发者必读

🛠️ 工具脚本

AccessToken缓存清除工具

文件: server/clear_wx_token_cache.php

功能：

清除缓存的AccessToken
重新获取新的AccessToken
验证配置是否正确
显示详细的错误信息

使用方法：

cd server
php clear_wx_token_cache.php

适用场景：

AccessToken失效（errcode 40001）
更换了AppSecret
缓存数据异常

📂 文件结构

项目根目录/
├── admin/
│   └── src/
│       ├── api/
│       │   └── tcm.ts                          # 前端API接口
│       └── views/
│           └── tcm/
│               └── diagnosis/
│                   └── index.vue               # 诊断管理页面
├── server/
│   ├── app/
│   │   └── adminapi/
│   │       ├── controller/
│   │       │   └── tcm/
│   │       │       └── DiagnosisController.php # 控制器
│   │       ├── logic/
│   │       │   └── tcm/
│   │       │       └── DiagnosisLogic.php      # 业务逻辑（已优化）
│   │       └── validate/
│   │           └── tcm/
│   │               └── DiagnosisValidate.php   # 验证器
│   ├── public/
│   │   └── uploads/
│   │       └── qrcode/                         # 二维码存储目录
│   └── clear_wx_token_cache.php                # 缓存清除工具
├── QRCODE_README.md                            # 本文件
├── QRCODE_QUICK_START.md                       # 快速开始
├── MINI_PROGRAM_QRCODE_FEATURE.md              # 功能详解
├── TEST_MINI_PROGRAM_QRCODE.md                 # 测试指南
├── QRCODE_DEBUG_GUIDE.md                       # 问题排查
└── QRCODE_IMPLEMENTATION_SUMMARY.md            # 实现总结

🎯 核心流程

用户点击按钮
    ↓
前端验证配置
    ↓
调用后端接口
    ↓
获取小程序配置
    ↓
获取AccessToken（缓存）
    ↓
调用微信API
    ↓
保存二维码图片
    ↓
返回图片URL
    ↓
前端显示二维码

⚡ 性能优化

AccessToken缓存
- 缓存时长：7000秒
- 避免频繁请求微信服务器
- 自动清除无效缓存
图片存储
- 本地存储，快速访问
- 按日期分目录
- 文件名包含MD5，避免重复
错误处理
- 详细的日志记录
- 自动重试机制
- 友好的错误提示

🔒 安全考虑

权限控制
- 需要登录才能访问
- 权限标识：tcm.diagnosis/guahao
参数验证
- 必填参数检查
- 数据类型验证
- 业务逻辑验证
敏感信息
- AppSecret不在日志中显示
- AccessToken安全缓存
- 图片文件名随机化

📊 监控建议

日志监控

# 实时查看日志
tail -f server/runtime/log/$(date +%Y%m%d).log | grep "小程序码"

关键指标

AccessToken获取成功率
二维码生成成功率
平均响应时间
错误类型分布

告警设置

AccessToken获取失败
二维码生成失败率超过5%
磁盘空间不足（uploads目录）

🔄 版本历史

v1.1 (2024-03-06)

✅ 修复AccessToken无效错误
✅ 添加详细日志记录
✅ 自动清除无效缓存
✅ 创建调试工具和文档

v1.0 (2024-03-06)

✅ 初始实现
✅ 前后端功能对接
✅ 基础错误处理

📞 技术支持

问题反馈

收集完整日志
记录错误时间
描述复现步骤
提供配置信息（脱敏）

参考资源

微信小程序官方文档：https://developers.weixin.qq.com/miniprogram/dev/
AccessToken文档：https://developers.weixin.qq.com/miniprogram/dev/OpenApiDoc/mp-access-token/getAccessToken.html
小程序码文档：https://developers.weixin.qq.com/miniprogram/dev/OpenApiDoc/qrcode-link/qr-code/getUnlimitedQRCode.html

🎓 学习路径

初学者

阅读 QRCODE_QUICK_START.md
按步骤配置和测试
遇到问题查阅 QRCODE_DEBUG_GUIDE.md

测试人员

阅读 TEST_MINI_PROGRAM_QRCODE.md
执行完整测试流程
记录测试结果

开发人员

阅读 QRCODE_IMPLEMENTATION_SUMMARY.md
查看 MINI_PROGRAM_QRCODE_FEATURE.md
理解代码实现细节

运维人员

了解日志位置和格式
掌握缓存清除方法
监控关键指标

✅ 检查清单

部署前检查：

已配置小程序AppID和AppSecret
服务器能访问微信API
uploads目录权限正确（755）
小程序页面已开发完成
已进行功能测试
已配置日志监控

上线后检查：

生成二维码功能正常
扫码跳转正常
日志记录正常
无异常错误

文档版本: v1.1
更新时间: 2024-03-06
维护者: 开发团队

💡 提示: 建议将本文档加入团队知识库，方便查阅。

6.2 KiB Raw Blame History Unescape Escape