feat: 更新公告和链接状态接口，增强参数校验，支持跳转链接最大长度为5000字符，添加异步保存完成图片功能，优化接口文档和数据库结构
This commit is contained in:
yahaozhang
196
GAME_INTERFACE_IMAGE_UPDATE.md
Normal file
196
GAME_INTERFACE_IMAGE_UPDATE.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# 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
|
||||
**状态**: ✅ 已完成并测试
|
||||
|
||||
Reference in New Issue
Block a user