298 lines
6.2 KiB
Markdown
298 lines
6.2 KiB
Markdown
# 小程序二维码功能 - 完整文档
|
||
|
||
## 📖 文档导航
|
||
|
||
### 🚀 快速开始
|
||
**文件**: `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
|
||
**维护者**: 开发团队
|
||
|
||
---
|
||
|
||
💡 **提示**: 建议将本文档加入团队知识库，方便查阅。
|