# TOS上传集成说明

## 功能概述

现在图片和视频生成完成后，会自动将原始URL的文件上传到TOS对象存储，并返回TOS地址。

## 修改内容

### 1. 图片功能改进

**文件路径**: `src/api/routes/images.ts`

- 增加了 `uploadImagesToTOS()` 函数
- 修改了 `/query` 接口，当任务完成时自动处理TOS上传
- 增加了缓存机制，避免重复上传

### 2. 视频功能改进

**文件路径**: `src/api/routes/video.ts`

- 增加了 `uploadVideosToTOS()` 函数
- 修改了 `/query` 接口，当任务完成时自动处理TOS上传
- 增加了缓存机制，避免重复上传

### 3. 任务缓存改进

**文件路径**: 
- `src/api/ImagesTaskCache.ts`
- `src/api/VideoTaskCache.ts`

增加了TOS处理状态跟踪：
- `isTosProcessed(taskId)`: 检查任务是否已处理TOS上传
- `markTosProcessed(taskId)`: 标记任务为已处理TOS上传

### 4. TOS服务配置

**文件路径**: `src/lib/tos/tos-service.ts`

- 支持通过环境变量配置TOS参数
- 增强了错误处理和日志记录

## 使用流程

### 图片生成流程

1. **发起生成请求**
   ```
   POST /v1/images/generations
   {
     "task_id": "task_123",
     "prompt": "一只可爱的猫",
     "width": 1024,
     "height": 1024
   }
   ```

2. **查询任务状态**
   ```
   GET /v1/images/query?task_id=task_123
   ```

3. **第一次查询**（任务完成时）
   - 自动上传图片到TOS
   - 返回TOS地址
   ```json
   {
     "created": 1703123456,
     "data": {
       "task_id": "task_123",
       "url": "https://your-domain.com/images/image-1703123456-abc123.png",
       "status": -1
     }
   }
   ```

4. **后续查询**
   - 直接返回缓存的TOS地址
   - 不会重复上传

### 视频生成流程

1. **发起生成请求**
   ```
   POST /v1/video/generations
   {
     "task_id": "video_123",
     "prompt": "一只猫在草地上奔跑",
     "duration": 5,
     "ratio": "16:9"
   }
   ```

2. **查询任务状态**
   ```
   GET /v1/video/query?task_id=video_123
   ```

3. **处理流程同图片**
   - 自动上传视频到TOS
   - 返回TOS地址

## 环境变量配置

需要在环境变量中配置以下TOS参数：

```env
# TOS对象存储配置
TOS_ACCESS_KEY_ID=your_access_key_id
TOS_ACCESS_KEY_SECRET=your_access_key_secret
TOS_BUCKET_NAME=your_bucket_name
TOS_SELF_DOMAIN=your_custom_domain.com
TOS_REGION=cn-beijing
TOS_ENDPOINT=tos-cn-beijing.volces.com
```

## 文件存储路径

- **图片**: `jimeng_free/images/{taskId}/image-{timestamp}-{random}.png`
- **视频**: `jimeng_free/videos/{taskId}/video-{timestamp}-{random}.mp4`

## 错误处理

- 如果TOS上传失败，会返回原始URL
- 错误信息会记录到日志中
- 不会影响原有功能的正常使用

## 日志记录

相关日志会记录在：
- `logs/images_task_cache.log` - 图片任务缓存日志
- `logs/video_task_cache.log` - 视频任务缓存日志
- 应用主日志 - TOS上传成功/失败日志

## 性能优化

1. **缓存机制**: 避免重复上传相同文件
2. **异步处理**: TOS上传不阻塞API响应
3. **错误兜底**: 上传失败时返回原始URL
4. **日志记录**: 便于监控和调试

## 注意事项

1. 确保TOS服务配置正确
2. 确保网络可以访问TOS服务
3. 监控TOS存储容量和费用
4. 定期清理过期文件（可选）

## 测试验证

可以通过以下方式验证功能：

1. 生成一张图片，检查返回的URL是否为TOS地址
2. 多次查询同一个task_id，确认不会重复上传
3. 检查TOS存储中是否有对应的文件
4. 测试TOS上传失败的情况下是否正常兜底