game_server/GAME_INTERFACE_IMAGE_UPDATE.md

Game Interface 接口图片URL优化

📋 修改说明

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

🔄 修改逻辑

之前（所有状态都使用实时图片）

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");

现在（根据状态智能切换）

// 根据任务状态决定使用哪个图片源
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

响应:

{
  "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

响应:

{
  "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. 任务进行中

# 请求接口
curl http://localhost:18080/api/link/MYNM5JHA/game-interface

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

2. 任务完成后

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

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

3. 访问图片

# 任务完成后，访问保存的图片
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：

// 无论任务状态如何，都使用同一个接口
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
状态: ✅ 已完成并测试