# 小程序二维码功能 - 完整文档 ## 📖 文档导航 ### 🚀 快速开始 **文件**: `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 - 验证配置是否正确 - 显示详细的错误信息 **使用方法**： ```bash 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 ↓ 前端显示二维码 ``` --- ## ⚡ 性能优化 1. **AccessToken缓存** - 缓存时长：7000秒 - 避免频繁请求微信服务器 - 自动清除无效缓存 2. **图片存储** - 本地存储，快速访问 - 按日期分目录 - 文件名包含MD5，避免重复 3. **错误处理** - 详细的日志记录 - 自动重试机制 - 友好的错误提示 --- ## 🔒 安全考虑 1. **权限控制** - 需要登录才能访问 - 权限标识：`tcm.diagnosis/guahao` 2. **参数验证** - 必填参数检查 - 数据类型验证 - 业务逻辑验证 3. **敏感信息** - AppSecret不在日志中显示 - AccessToken安全缓存 - 图片文件名随机化 --- ## 📊 监控建议 ### 日志监控 ```bash # 实时查看日志 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) - ✅ 初始实现 - ✅ 前后端功能对接 - ✅ 基础错误处理 --- ## 📞 技术支持 ### 问题反馈 1. 收集完整日志 2. 记录错误时间 3. 描述复现步骤 4. 提供配置信息（脱敏） ### 参考资源 - 微信小程序官方文档：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 --- ## 🎓 学习路径 ### 初学者 1. 阅读 `QRCODE_QUICK_START.md` 2. 按步骤配置和测试 3. 遇到问题查阅 `QRCODE_DEBUG_GUIDE.md` ### 测试人员 1. 阅读 `TEST_MINI_PROGRAM_QRCODE.md` 2. 执行完整测试流程 3. 记录测试结果 ### 开发人员 1. 阅读 `QRCODE_IMPLEMENTATION_SUMMARY.md` 2. 查看 `MINI_PROGRAM_QRCODE_FEATURE.md` 3. 理解代码实现细节 ### 运维人员 1. 了解日志位置和格式 2. 掌握缓存清除方法 3. 监控关键指标 --- ## ✅ 检查清单 部署前检查： - [ ] 已配置小程序AppID和AppSecret - [ ] 服务器能访问微信API - [ ] uploads目录权限正确（755） - [ ] 小程序页面已开发完成 - [ ] 已进行功能测试 - [ ] 已配置日志监控 上线后检查： - [ ] 生成二维码功能正常 - [ ] 扫码跳转正常 - [ ] 日志记录正常 - [ ] 无异常错误 --- **文档版本**: v1.1 **更新时间**: 2024-03-06 **维护者**: 开发团队 --- 💡 **提示**: 建议将本文档加入团队知识库，方便查阅。