更新
This commit is contained in:
Your Name
@@ -0,0 +1,297 @@
|
||||
# 小程序二维码功能 - 完整文档
|
||||
|
||||
## 📖 文档导航
|
||||
|
||||
### 🚀 快速开始
|
||||
**文件**: `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
|
||||
**维护者**: 开发团队
|
||||
|
||||
---
|
||||
|
||||
💡 **提示**: 建议将本文档加入团队知识库，方便查阅。
|
||||
Reference in New Issue
Block a user