# Game Interface 接口图片URL优化

## 📋 修改说明

修改了 `/api/link/{codeNo}/game-interface` 接口，使其在任务完成后返回保存的完成图片URL，而不是实时图片URL。

## 🔄 修改逻辑

### 之前（所有状态都使用实时图片）
```java
response.setHomepageUrl(appBaseUrl + "/api/link/image/" + codeNo + "/homepage.png");
response.setFirstRewardUrl(appBaseUrl + "/api/link/image/" + codeNo + "/first-reward.png");
response.setMidRewardUrl(appBaseUrl + "/api/link/image/" + codeNo + "/mid-reward.png");
response.setEndRewardUrl(appBaseUrl + "/api/link/image/" + codeNo + "/end-reward.png");
```

### 现在（根据状态智能切换）
```java
// 根据任务状态决定使用哪个图片源
boolean isCompleted = "COMPLETED".equals(linkTask.getStatus());
String imageUrlPrefix = isCompleted ? "/api/link/completion/" : "/api/link/image/";

// 二维码始终使用实时的（不保存）
response.setQrCodeUrl(appBaseUrl + "/api/link/image/" + codeNo + "/qr.png");

// 4张游戏图片：如果任务完成，使用保存的图片；否则使用实时图片
response.setHomepageUrl(appBaseUrl + imageUrlPrefix + codeNo + "/homepage.png");
response.setFirstRewardUrl(appBaseUrl + imageUrlPrefix + codeNo + "/first-reward.png");
response.setMidRewardUrl(appBaseUrl + imageUrlPrefix + codeNo + "/mid-reward.png");
response.setEndRewardUrl(appBaseUrl + imageUrlPrefix + codeNo + "/end-reward.png");
```

## 🎯 行为对比

### 任务进行中（NEW / USING / LOGGED_IN）

**请求**: `GET /api/link/MYNM5JHA/game-interface`

**响应**:
```json
{
  "qrCodeUrl": "https://uzi1.cn/api/link/image/MYNM5JHA/qr.png",
  "homepageUrl": "https://uzi1.cn/api/link/image/MYNM5JHA/homepage.png",
  "firstRewardUrl": "https://uzi1.cn/api/link/image/MYNM5JHA/first-reward.png",
  "midRewardUrl": "https://uzi1.cn/api/link/image/MYNM5JHA/mid-reward.png",
  "endRewardUrl": "https://uzi1.cn/api/link/image/MYNM5JHA/end-reward.png",
  "machineId": "rr3",
  "totalPoints": 1000,
  "completedPoints": null
}
```

**说明**: 使用 `/api/link/image/` 前缀，图片来自脚本端实时数据

---

### 任务已完成（COMPLETED）✨

**请求**: `GET /api/link/MYNM5JHA/game-interface`

**响应**:
```json
{
  "qrCodeUrl": "https://uzi1.cn/api/link/image/MYNM5JHA/qr.png",
  "homepageUrl": "https://uzi1.cn/api/link/completion/MYNM5JHA/homepage.png",
  "firstRewardUrl": "https://uzi1.cn/api/link/completion/MYNM5JHA/first-reward.png",
  "midRewardUrl": "https://uzi1.cn/api/link/completion/MYNM5JHA/mid-reward.png",
  "endRewardUrl": "https://uzi1.cn/api/link/completion/MYNM5JHA/end-reward.png",
  "machineId": "rr3",
  "totalPoints": 1000,
  "completedPoints": 1000
}
```

**说明**: 
- ✅ 4张游戏图片使用 `/api/link/completion/` 前缀，来自完成时保存的图片
- ✅ 二维码仍使用 `/api/link/image/` 前缀（二维码不保存）
- ✅ 图片保存24小时后自动清理

---

## 🔍 URL格式对比

| 图片类型 | 任务进行中 | 任务完成后 |
|---------|-----------|-----------|
| 首次主页 | `/api/link/image/{code}/homepage.png` | `/api/link/completion/{code}/homepage.png` ✨ |
| 首次赏金 | `/api/link/image/{code}/first-reward.png` | `/api/link/completion/{code}/first-reward.png` ✨ |
| 中途赏金 | `/api/link/image/{code}/mid-reward.png` | `/api/link/completion/{code}/mid-reward.png` ✨ |
| 结束赏金 | `/api/link/image/{code}/end-reward.png` | `/api/link/completion/{code}/end-reward.png` ✨ |
| 二维码 | `/api/link/image/{code}/qr.png` | `/api/link/image/{code}/qr.png` |

## ✅ 优势

### 1. 性能优化
- **完成后不再请求脚本端**：减轻脚本服务器压力
- **本地文件系统读取**：更快的响应速度
- **缓存友好**：已完成的图片不会变化

### 2. 数据稳定性
- **固定快照**：保存完成时刻的准确数据
- **防止脚本端数据变化**：设备被其他任务使用后，图片依然可用
- **24小时可用**：完成后24小时内都能查看

### 3. 一致性
- **任务完成证明**：展示的图片就是完成时的真实状态
- **避免数据不一致**：不会因为设备被复用而显示错误数据

## 📊 日志增强

修改后的日志会显示是否使用完成图片：

```
游戏界面数据构建完成: codeNo=MYNM5JHA, totalPoints=1000, status=COMPLETED, useCompletionImages=true
```

## 🧪 测试验证

### 测试步骤

1. **任务进行中**
```bash
# 请求接口
curl http://localhost:18080/api/link/MYNM5JHA/game-interface

# 验证返回的URL包含 /api/link/image/
```

2. **任务完成后**
```bash
# 等待任务完成并保存图片
# 再次请求接口
curl http://localhost:18080/api/link/MYNM5JHA/game-interface

# 验证返回的URL包含 /api/link/completion/
```

3. **访问图片**
```bash
# 任务完成后，访问保存的图片
curl https://uzi1.cn/api/link/completion/MYNM5JHA/homepage.png
curl https://uzi1.cn/api/link/completion/MYNM5JHA/first-reward.png
curl https://uzi1.cn/api/link/completion/MYNM5JHA/mid-reward.png
curl https://uzi1.cn/api/link/completion/MYNM5JHA/end-reward.png
```

## 🔧 修改的文件

- `src/main/java/com/gameplatform/server/controller/link/QrProxyController.java`
  - 方法: `getGameInterface()`
  - 行号: ~270-289

## 🎓 前端集成建议

前端无需修改代码，接口会自动根据任务状态返回正确的URL：

```javascript
// 无论任务状态如何，都使用同一个接口
fetch(`/api/link/${codeNo}/game-interface`)
  .then(res => res.json())
  .then(data => {
    // 直接使用返回的URL即可
    console.log('首次主页:', data.homepageUrl);
    console.log('首次赏金:', data.firstRewardUrl);
    console.log('中途赏金:', data.midRewardUrl);
    console.log('结束赏金:', data.endRewardUrl);
    
    // 如果是完成状态，这些URL会自动指向保存的图片
  });
```

## ⚠️ 注意事项

1. **二维码不保存**：二维码始终使用实时图片（因为每次扫码都不同）
2. **24小时有效期**：完成图片保存24小时后会自动清理
3. **兼容性**：旧的 `/api/link/image/` URL 依然可用，不影响现有功能

## 📈 性能影响

### 脚本端
- ✅ **减少请求**：完成后的任务不再频繁请求图片
- ✅ **降低负载**：减轻脚本服务器压力

### 应用服务器
- ✅ **本地读取**：从文件系统读取，速度更快
- ✅ **缓存优化**：静态文件容易缓存

### 存储空间
- ⚠️ **额外占用**：每个完成任务约 1-2 MB（4张图片）
- ✅ **自动清理**：24小时后自动删除，不会无限增长

---

**更新时间**: 2025-11-03  
**版本**: v1.2.0  
**状态**: ✅ 已完成并测试