# AccessToken 自动重试机制说明

## 功能概述

已为小程序二维码生成功能添加了 AccessToken 失效自动检测和重试机制，确保在 Token 失效时能够自动恢复。

## 实现的功能

### 1. AccessToken 强制刷新支持

**方法**: `getWxAccessToken($appId, $appSecret, $forceRefresh = false)`

**新增参数**:
- `$forceRefresh` (bool): 是否强制刷新，不使用缓存

**功能**:
- 默认从缓存获取 AccessToken
- 当 `$forceRefresh = true` 时，清除缓存并重新获取
- 记录详细日志，便于追踪

**使用示例**:
```php
// 正常获取（使用缓存）
$token = self::getWxAccessToken($appId, $appSecret);

// 强制刷新（不使用缓存）
$token = self::getWxAccessToken($appId, $appSecret, true);
```

### 2. 自动重试机制

**方法**: `generateWxQrcode($config, $page, $scene, $retryCount = 0)`

**新增参数**:
- `$retryCount` (int): 当前重试次数，默认为 0

**工作流程**:
1. 首次调用时使用缓存的 AccessToken
2. 如果微信返回 40001 或 42001 错误（Token 失效）
3. 自动清除缓存
4. 递归调用自己，重试一次（`$retryCount + 1`）
5. 重试时强制刷新 AccessToken
6. 最多重试 1 次，避免无限循环

**错误码说明**:
- `40001`: invalid credential, access_token is invalid
- `42001`: access_token expired

## 使用场景

### 场景1: 正常生成（Token 有效）
```
用户点击生成 → 使用缓存Token → 成功生成二维码
```

### 场景2: Token 失效自动恢复
```
用户点击生成 
  → 使用缓存Token 
  → 微信返回40001错误 
  → 自动清除缓存 
  → 重新获取Token 
  → 再次调用微信API 
  → 成功生成二维码
```

### 场景3: 配置错误（无法恢复）
```
用户点击生成 
  → 使用缓存Token 
  → 微信返回40001错误 
  → 自动重试 
  → 重新获取Token失败（AppID/AppSecret错误）
  → 返回错误信息给用户
```

## 日志记录

所有关键步骤都会记录日志，便于追踪问题：

### 正常流程日志
```
[info] 使用缓存的AccessToken
[info] 开始生成小程序码 {"page":"...","scene":"...","app_id":"...","retry_count":0}
[info] 调用微信API生成小程序码 {"data":{...}}
[info] 小程序码生成成功 {"url":"...","retry_count":0}
```

### 自动重试流程日志
```
[info] 使用缓存的AccessToken
[info] 开始生成小程序码 {"page":"...","scene":"...","app_id":"...","retry_count":0}
[info] 调用微信API生成小程序码 {"data":{...}}
[error] 生成小程序码失败: errcode=40001, errmsg=invalid credential...
[info] AccessToken失效，自动重试（第1次）
[info] 强制刷新AccessToken，清除缓存
[info] 微信AccessToken响应: {"access_token":"...","expires_in":7200}
[info] AccessToken获取成功并已缓存
[info] 开始生成小程序码 {"page":"...","scene":"...","app_id":"...","retry_count":1}
[info] 调用微信API生成小程序码 {"data":{...}}
[info] 小程序码生成成功 {"url":"...","retry_count":1}
```

## 优势

### 1. 用户体验提升
- 无需手动清除缓存
- 无需重新点击按钮
- 自动恢复，对用户透明

### 2. 系统稳定性
- 自动处理 Token 失效
- 避免因缓存问题导致的失败
- 限制重试次数，防止无限循环

### 3. 问题排查
- 详细的日志记录
- 记录重试次数
- 便于追踪问题根源

## 注意事项

### 1. 重试限制
- 最多重试 1 次
- 避免无限递归
- 如果重试后仍失败，返回错误

### 2. 性能考虑
- 首次调用使用缓存，性能最优
- 重试时才强制刷新，影响可控
- 缓存时长 7000 秒，减少请求频率

### 3. 错误处理
- 配置错误（AppID/AppSecret）无法通过重试解决
- 网络问题可能导致重试失败
- 需要查看日志确定具体原因

## 测试建议

### 测试1: 正常流程
1. 配置正确的小程序信息
2. 首次生成二维码
3. 查看日志确认使用缓存
4. 验证生成成功

### 测试2: Token 失效恢复
1. 手动清除 AccessToken 缓存
   ```bash
   php server/clear_wx_token_cache.php
   ```
2. 立即生成二维码
3. 查看日志确认自动重试
4. 验证生成成功

### 测试3: 配置错误
1. 故意配置错误的 AppSecret
2. 尝试生成二维码
3. 查看日志确认重试流程
4. 验证返回正确的错误信息

## 相关文档

- `QRCODE_README.md` - 完整文档导航
- `QRCODE_DEBUG_GUIDE.md` - 问题排查指南
- `QRCODE_QUICK_START.md` - 快速开始

## 版本信息

- 实现时间: 2024-03-06
- 版本: v1.1
- 状态: ✅ 已完成并测试

---

**重要提示**: 此机制大大提升了系统的健壮性，但不能解决配置错误问题。请确保 AppID 和 AppSecret 配置正确！