146 lines
3.8 KiB
Markdown
146 lines
3.8 KiB
Markdown
# 任务完成图片保存功能 - 快速上手
|
||
|
||
## ✅ 功能已实现
|
||
|
||
当游戏任务完成时，系统自动保存4张图片并保留24小时。
|
||
|
||
## 📦 新增文件清单
|
||
|
||
### 1. 核心服务
|
||
- `src/main/java/com/gameplatform/server/service/image/CompletionImageService.java` - 图片保存和访问服务
|
||
|
||
### 2. 控制器
|
||
- `src/main/java/com/gameplatform/server/controller/link/CompletionImageController.java` - 图片访问API
|
||
|
||
### 3. 定时任务
|
||
- `src/main/java/com/gameplatform/server/task/CompletionImageCleanupTask.java` - 24小时自动清理
|
||
|
||
### 4. 数据库迁移
|
||
- `src/main/resources/db/migration/V20251103__add_completion_images_saved_at.sql` - 添加字段
|
||
|
||
### 5. 文档
|
||
- `docs/完成图片保存功能说明.md` - 详细功能文档
|
||
|
||
## 🔧 修改的文件
|
||
|
||
### 1. 实体类
|
||
- `src/main/java/com/gameplatform/server/model/entity/agent/LinkTask.java`
|
||
- 添加 `completionImagesSavedAt` 字段
|
||
|
||
### 2. 完成检测服务
|
||
- `src/main/java/com/gameplatform/server/service/detection/GameCompletionDetectionService.java`
|
||
- 集成图片保存功能（异步执行）
|
||
|
||
### 3. 配置文件
|
||
- `src/main/resources/application.yml`
|
||
- 添加图片存储路径配置
|
||
|
||
### 4. 安全配置
|
||
- `src/main/java/com/gameplatform/server/security/SecurityConfig.java`
|
||
- 允许公开访问完成图片
|
||
|
||
## 🚀 部署步骤
|
||
|
||
### 1. 执行数据库迁移
|
||
```sql
|
||
-- 执行 V20251103__add_completion_images_saved_at.sql
|
||
ALTER TABLE `link_task`
|
||
ADD COLUMN `completion_images_saved_at` DATETIME NULL;
|
||
```
|
||
|
||
### 2. 创建存储目录
|
||
```bash
|
||
mkdir -p /data/gameplatform/completion-images
|
||
chmod 755 /data/gameplatform/completion-images
|
||
```
|
||
|
||
### 3. 更新配置（可选）
|
||
```yaml
|
||
completion:
|
||
image:
|
||
storage:
|
||
path: "/data/gameplatform/completion-images" # 生产环境使用绝对路径
|
||
```
|
||
|
||
### 4. 重启应用
|
||
```bash
|
||
systemctl restart gameplatform-server
|
||
```
|
||
|
||
## 📡 API 使用示例
|
||
|
||
### 获取单张图片
|
||
```
|
||
GET /api/link/completion/{codeNo}/homepage.png
|
||
GET /api/link/completion/{codeNo}/first-reward.png
|
||
GET /api/link/completion/{codeNo}/mid-reward.png
|
||
GET /api/link/completion/{codeNo}/end-reward.png
|
||
```
|
||
|
||
### 获取所有图片URL
|
||
```
|
||
GET /api/link/completion/{codeNo}/images
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"homepage": "https://uzi1.cn/api/link/completion/ABC123/homepage.png",
|
||
"firstReward": "https://uzi1.cn/api/link/completion/ABC123/first-reward.png",
|
||
"midReward": "https://uzi1.cn/api/link/completion/ABC123/mid-reward.png",
|
||
"endReward": "https://uzi1.cn/api/link/completion/ABC123/end-reward.png"
|
||
}
|
||
```
|
||
|
||
## 🔍 验证功能
|
||
|
||
### 查看日志
|
||
```bash
|
||
tail -f logs/server.log | grep "完成图片"
|
||
```
|
||
|
||
### 检查文件系统
|
||
```bash
|
||
ls -lh completion-images/$(date +%Y%m%d)/
|
||
```
|
||
|
||
### 查询数据库
|
||
```sql
|
||
SELECT code_no, completion_images, completion_images_saved_at
|
||
FROM link_task
|
||
WHERE status = 'COMPLETED'
|
||
AND completion_images_saved_at IS NOT NULL
|
||
ORDER BY completion_images_saved_at DESC
|
||
LIMIT 5;
|
||
```
|
||
|
||
## ⚙️ 关键特性
|
||
|
||
- ✅ **异步保存**：不阻塞任务完成流程
|
||
- ✅ **并发下载**：4张图片同时下载，提高效率
|
||
- ✅ **智能重试**：每张图片失败后自动重试3次（间隔500ms）
|
||
- ✅ **自动清理**：超过24小时自动删除
|
||
- ✅ **容错机制**：单张图片失败不影响其他图片
|
||
- ✅ **公开访问**：无需认证即可访问图片
|
||
|
||
## 📊 存储预估
|
||
|
||
- 单个任务：约 1-2 MB（4张图片）
|
||
- 每天100个任务：约 100-200 MB
|
||
- 24小时滚动存储：约 100-200 MB
|
||
|
||
## 📖 详细文档
|
||
|
||
- **功能说明**: `docs/完成图片保存功能说明.md`
|
||
- **重试机制**: `IMAGE_SAVE_RETRY_MECHANISM.md` ⭐
|
||
- **重试快速参考**: `IMAGE_RETRY_QUICK_REF.md` ⭐
|
||
- **所有触发点**: `COMPLETION_IMAGE_ALL_TRIGGERS.md`
|
||
- **接口优化**: `GAME_INTERFACE_IMAGE_UPDATE.md`
|
||
- **时间戳说明**: `API_COMPLETION_TIMESTAMP.md`
|
||
|
||
---
|
||
|
||
**创建时间：** 2025-11-03
|
||
**状态：** ✅ 已完成并测试
|
||
|