197 lines
6.5 KiB
Markdown
197 lines
6.5 KiB
Markdown
# 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
|
||
**状态**: ✅ 已完成并测试
|
||
|