feat: 更新公告和链接状态接口，增强参数校验，支持跳转链接最大长度为5000字符，添加异步保存完成图片功能，优化接口文档和数据库结构

2025-11-03 20:56:34 +08:00
parent f43320138a
commit cadf8d98cb
40 changed files with 3148 additions and 17 deletions
--- a/docs/完成图片保存功能说明.md
+++ b/docs/完成图片保存功能说明.md
@@ -0,0 +1,384 @@
+# 完成图片保存功能说明
+
+## 📋 功能概述
+
+当游戏任务完成时，系统会自动保存4张关键截图到本地文件系统，并保留24小时。这些图片可以作为任务完成的证明和记录。
+
+## 🎯 保存的图片
+
+任务完成时会保存以下4张图片：
+
+1. **首次主页.png** (homepage)
+2. **首次赏金.png** (first-reward)
+3. **中途赏金.png** (mid-reward)
+4. **结束赏金.png** (end-reward)
+
+## 🔧 技术实现
+
+### 1. 核心服务组件
+
+#### **CompletionImageService**
+- 负责从脚本端下载图片并保存到本地文件系统
+- 并发下载4张图片，提高效率
+- 提供图片访问和清理功能
+
+#### **GameCompletionDetectionService**
+- 在任务完成时触发图片保存
+- 异步执行，不阻塞主流程
+- 保存成功后更新数据库记录
+
+#### **CompletionImageController**
+- 提供HTTP接口访问已保存的图片
+- 支持单张图片访问和批量URL获取
+
+#### **CompletionImageCleanupTask**
+- 定时清理任务（每小时执行）
+- 自动删除超过24小时的图片文件夹
+
+### 2. 文件存储结构
+
+```
+completion-images/
+├── 20251103/              # 日期文件夹（yyyyMMdd）
+│   ├── ABC123XYZ/         # 链接编号（codeNo）
+│   │   ├── homepage.png
+│   │   ├── first-reward.png
+│   │   ├── mid-reward.png
+│   │   └── end-reward.png
+│   └── DEF456UVW/
+│       └── ...
+└── 20251104/
+    └── ...
+```
+
+### 3. 数据库字段
+
+在 `link_task` 表中新增两个字段：
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| `completion_images` | TEXT | JSON格式存储图片信息 |
+| `completion_images_saved_at` | DATETIME | 图片保存时间 |
+
+**completion_images JSON 示例：**
+```json
+{
+  "saveTime": "2025-11-03T10:30:45",
+  "codeNo": "ABC123XYZ",
+  "machineId": "f1",
+  "dateFolder": "20251103",
+  "images": {
+    "homepage": "20251103/ABC123XYZ/homepage.png",
+    "first-reward": "20251103/ABC123XYZ/first-reward.png",
+    "mid-reward": "20251103/ABC123XYZ/mid-reward.png",
+    "end-reward": "20251103/ABC123XYZ/end-reward.png"
+  },
+  "totalCount": 4
+}
+```
+
+## 📡 API 接口
+
+### 1. 获取单张图片
+
+**首次主页图片**
+```http
+GET /api/link/completion/{codeNo}/homepage.png
+```
+
+**首次赏金图片**
+```http
+GET /api/link/completion/{codeNo}/first-reward.png
+```
+
+**中途赏金图片**
+```http
+GET /api/link/completion/{codeNo}/mid-reward.png
+```
+
+**结束赏金图片**
+```http
+GET /api/link/completion/{codeNo}/end-reward.png
+```
+
+**响应示例：**
+- 成功：返回图片数据（image/png）
+- 失败：404 Not Found
+
+### 2. 获取所有图片URL列表
+
+```http
+GET /api/link/completion/{codeNo}/images
+```
+
+**响应示例：**
+```json
+{
+  "homepage": "https://uzi1.cn/api/link/completion/ABC123XYZ/homepage.png",
+  "firstReward": "https://uzi1.cn/api/link/completion/ABC123XYZ/first-reward.png",
+  "midReward": "https://uzi1.cn/api/link/completion/ABC123XYZ/mid-reward.png",
+  "endReward": "https://uzi1.cn/api/link/completion/ABC123XYZ/end-reward.png"
+}
+```
+
+## ⚙️ 配置说明
+
+在 `application.yml` 中配置：
+
+```yaml
+# 完成图片存储配置
+completion:
+  image:
+    storage:
+      path: "./completion-images"  # 图片存储路径
+      retention-hours: 24          # 图片保留时间（小时）
+```
+
+### 配置项说明
+
+| 配置项 | 说明 | 默认值 |
+|--------|------|--------|
+| `path` | 图片存储路径，支持相对路径和绝对路径 | `./completion-images` |
+| `retention-hours` | 图片保留时间（小时） | 24 |
+
+### 生产环境建议
+
+**推荐配置绝对路径：**
+```yaml
+completion:
+  image:
+    storage:
+      path: "/data/gameplatform/completion-images"
+```
+
+**磁盘空间预估：**
+- 单个任务：4张图片，约 800KB - 2MB
+- 每天100个任务：约 80MB - 200MB
+- 24小时滚动：约 80MB - 200MB
+
+## 🔄 执行流程
+
+### 1. 图片保存流程
+
+```mermaid
+sequenceDiagram
+    participant Detection as 完成检测服务
+    participant ImageService as 图片服务
+    participant ScriptClient as 脚本客户端
+    participant FileSystem as 文件系统
+    participant Database as 数据库
+
+    Detection->>Detection: 检测到任务完成
+    Detection->>ImageService: 异步保存图片
+    ImageService->>ScriptClient: 并发下载4张图片
+    ScriptClient-->>ImageService: 返回图片数据
+    ImageService->>FileSystem: 保存到本地
+    FileSystem-->>ImageService: 保存成功
+    ImageService->>Database: 更新图片信息
+    Database-->>ImageService: 更新完成
+```
+
+### 2. 清理流程
+
+```
+每小时第5分钟执行
+    ↓
+计算过期时间（当前时间 - 24小时）
+    ↓
+查找过期的日期文件夹
+    ↓
+递归删除过期文件夹
+    ↓
+记录清理日志
+```
+
+## 🔒 安全配置
+
+在 `SecurityConfig.java` 中已配置公开访问权限：
+
+```java
+.pathMatchers(HttpMethod.GET, "/api/link/completion/**").permitAll()
+.pathMatchers(HttpMethod.HEAD, "/api/link/completion/**").permitAll()
+```
+
+**说明：**
+- 完成图片可以公开访问（无需认证）
+- 图片URL包含链接编号，具有一定的私密性
+- 24小时后自动删除，减少泄露风险
+
+## 📊 监控和日志
+
+### 关键日志
+
+**图片保存成功：**
+```
+INFO  - 完成图片保存成功: codeNo=ABC123XYZ, imageInfo={...}
+```
+
+**图片保存失败：**
+```
+ERROR - 完成图片保存失败: codeNo=ABC123XYZ, error=...
+```
+
+**定时清理：**
+```
+INFO  - === 完成图片清理任务完成：删除文件夹数=5, 耗时=234ms ===
+```
+
+### 监控指标
+
+- 图片保存成功率
+- 图片下载耗时
+- 磁盘空间使用
+- 清理任务执行情况
+
+## 🚀 部署步骤
+
+### 1. 数据库迁移
+
+执行迁移脚本：
+```bash
+# 文件位置: src/main/resources/db/migration/V20251103__add_completion_images_saved_at.sql
+mysql -u username -p database_name < V20251103__add_completion_images_saved_at.sql
+```
+
+或者使用 Flyway 自动迁移（推荐）。
+
+### 2. 创建存储目录
+
+```bash
+# 创建图片存储目录
+mkdir -p /data/gameplatform/completion-images
+
+# 设置权限
+chown -R app_user:app_group /data/gameplatform/completion-images
+chmod 755 /data/gameplatform/completion-images
+```
+
+### 3. 更新配置文件
+
+修改 `application.yml`：
+```yaml
+completion:
+  image:
+    storage:
+      path: "/data/gameplatform/completion-images"
+```
+
+### 4. 重启应用
+
+```bash
+systemctl restart gameplatform-server
+```
+
+### 5. 验证功能
+
+查看日志确认功能正常：
+```bash
+tail -f logs/server.log | grep "完成图片"
+```
+
+## 🔍 故障排查
+
+### 问题1：图片保存失败
+
+**可能原因：**
+1. 存储目录不存在或无写权限
+2. 脚本端图片不存在
+3. 网络连接问题
+
+**排查步骤：**
+```bash
+# 1. 检查目录权限
+ls -la /data/gameplatform/completion-images
+
+# 2. 检查磁盘空间
+df -h
+
+# 3. 查看详细日志
+grep "完成图片保存失败" logs/server.log
+```
+
+### 问题2：图片无法访问
+
+**可能原因：**
+1. 图片已被清理（超过24小时）
+2. 图片保存时失败
+3. 文件路径错误
+
+**排查步骤：**
+```bash
+# 查找特定任务的图片
+find /data/gameplatform/completion-images -name "*ABC123XYZ*"
+
+# 检查数据库记录
+SELECT code_no, completion_images, completion_images_saved_at 
+FROM link_task 
+WHERE code_no = 'ABC123XYZ';
+```
+
+### 问题3：磁盘空间不足
+
+**解决方案：**
+1. 调整保留时间（减少到12小时）
+2. 增加磁盘空间
+3. 配置日志轮转和压缩
+
+## 📝 注意事项
+
+1. **异步执行**：图片保存是异步的，不会阻塞任务完成流程
+2. **容错机制**：单张图片下载失败不影响其他图片
+3. **自动清理**：超过24小时的图片会自动删除，无需手动维护
+4. **并发安全**：使用日期文件夹隔离，避免并发冲突
+5. **存储规划**：建议预留至少 500MB 磁盘空间
+
+## 🎓 使用示例
+
+### 前端获取完成图片
+
+```javascript
+// 获取所有图片URL
+fetch('/api/link/completion/ABC123XYZ/images')
+  .then(res => res.json())
+  .then(urls => {
+    console.log('首次主页:', urls.homepage);
+    console.log('首次赏金:', urls.firstReward);
+    console.log('中途赏金:', urls.midReward);
+    console.log('结束赏金:', urls.endReward);
+  });
+
+// 直接显示图片
+<img src="/api/link/completion/ABC123XYZ/homepage.png" alt="首次主页" />
+```
+
+### 查询数据库中的图片信息
+
+```sql
+-- 查询最近完成且有图片的任务
+SELECT 
+    code_no,
+    status,
+    completed_points,
+    completion_images_saved_at,
+    JSON_EXTRACT(completion_images, '$.totalCount') as image_count
+FROM link_task
+WHERE status = 'COMPLETED'
+  AND completion_images IS NOT NULL
+  AND completion_images_saved_at > DATE_SUB(NOW(), INTERVAL 24 HOUR)
+ORDER BY completion_images_saved_at DESC
+LIMIT 10;
+```
+
+## 🔮 未来优化方向
+
+1. **CDN 集成**：将图片上传到 CDN，提高访问速度
+2. **压缩优化**：自动压缩图片，减少存储空间
+3. **备份机制**：定期备份重要图片到对象存储
+4. **统计分析**：添加图片访问统计和热度分析
+5. **批量下载**：支持批量导出完成图片
+
+---
+
+**最后更新时间：** 2025-11-03  
+**版本：** v1.0.0
+