# 任务清理系统实现说明

## 功能概述

本系统实现了定期清理任务列表的功能，将成功的任务导出到专门的归档表中，失败的任务记录到清理日志后删除。

## 系统架构

### 1. 数据库表结构

#### 成功任务归档表 (`completed_tasks_archive`)
```sql
CREATE TABLE completed_tasks_archive (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    task_id VARCHAR(255) NOT NULL,
    username VARCHAR(255) NOT NULL,
    task_type VARCHAR(50) NOT NULL,
    prompt TEXT,
    aspect_ratio VARCHAR(20),
    duration INT,
    hd_mode BOOLEAN DEFAULT FALSE,
    result_url TEXT,
    real_task_id VARCHAR(255),
    progress INT DEFAULT 100,
    created_at TIMESTAMP NOT NULL,
    completed_at TIMESTAMP NOT NULL,
    archived_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    points_cost INT DEFAULT 0
);
```

#### 失败任务清理日志表 (`failed_tasks_cleanup_log`)
```sql
CREATE TABLE failed_tasks_cleanup_log (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    task_id VARCHAR(255) NOT NULL,
    username VARCHAR(255) NOT NULL,
    task_type VARCHAR(50) NOT NULL,
    error_message TEXT,
    created_at TIMESTAMP NOT NULL,
    failed_at TIMESTAMP NOT NULL,
    cleaned_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

### 2. 核心组件

#### TaskCleanupService
- **功能**: 执行任务清理的核心服务
- **主要方法**:
  - `performFullCleanup()`: 执行完整清理
  - `cleanupTextToVideoTasks()`: 清理文生视频任务
  - `cleanupImageToVideoTasks()`: 清理图生视频任务
  - `cleanupTaskQueue()`: 清理任务队列
  - `cleanupExpiredArchives()`: 清理过期归档
  - `cleanupUserTasks()`: 清理指定用户任务

#### TaskQueueScheduler
- **功能**: 定时调度器
- **调度任务**:
  - 每天凌晨4点执行任务清理 (`@Scheduled(cron = "0 0 4 * * ?")`)

#### CleanupController
- **功能**: 提供手动清理的API接口
- **接口**:
  - `POST /api/cleanup/full-cleanup`: 执行完整清理
  - `POST /api/cleanup/user-tasks/{username}`: 清理指定用户任务
  - `GET /api/cleanup/cleanup-stats`: 获取清理统计信息

## 清理流程

### 1. 成功任务处理
1. 查找所有状态为 `COMPLETED` 的任务
2. 将任务信息导出到 `completed_tasks_archive` 表
3. 从原始任务表中删除记录

### 2. 失败任务处理
1. 查找所有状态为 `FAILED` 的任务
2. 将任务信息记录到 `failed_tasks_cleanup_log` 表
3. 从原始任务表中删除记录

### 3. 任务队列清理
1. 删除状态为 `COMPLETED` 和 `FAILED` 的任务队列记录

### 4. 过期归档清理
1. 删除超过保留期的归档记录和清理日志

## 配置参数

```properties
# 任务保留天数（默认30天）
task.cleanup.retention-days=30

# 归档保留天数（默认365天）
task.cleanup.archive-retention-days=365
```

## 使用方法

### 1. 自动清理
系统每天凌晨4点自动执行清理任务，无需人工干预。

### 2. 手动清理
```bash
# 执行完整清理
curl -X POST "http://localhost:8080/api/cleanup/full-cleanup"

# 清理指定用户任务
curl -X POST "http://localhost:8080/api/cleanup/user-tasks/admin"

# 获取清理统计信息
curl "http://localhost:8080/api/cleanup/cleanup-stats"
```

### 3. PowerShell测试脚本
```powershell
# 运行测试脚本
.\test-cleanup.ps1
```

## 监控和统计

### 清理统计信息
- 当前任务数量（按状态分类）
- 归档任务数量
- 清理日志数量
- 配置参数

### 日志记录
- 清理操作的详细日志
- 错误处理和异常记录
- 性能监控信息

## 安全考虑

1. **事务处理**: 所有清理操作都在事务中执行，确保数据一致性
2. **错误处理**: 完善的异常处理机制，避免清理过程中的数据丢失
3. **权限控制**: API接口需要适当的权限验证
4. **数据备份**: 建议在清理前进行数据备份

## 扩展功能

### 1. 自定义清理策略
- 支持按任务类型设置不同的保留期
- 支持按用户等级设置不同的清理策略

### 2. 清理报告
- 生成清理操作的详细报告
- 支持邮件通知清理结果

### 3. 数据导出
- 支持将归档数据导出为CSV或Excel格式
- 支持按时间范围导出数据

## 注意事项

1. **数据恢复**: 清理后的数据无法直接恢复，需要从归档表中查找
2. **性能影响**: 大量数据清理可能影响系统性能，建议在低峰期执行
3. **存储空间**: 归档表会占用额外的存储空间，需要定期清理过期数据
4. **备份策略**: 建议定期备份归档表数据

---
*文档生成时间: 2025-01-24*
*版本: 1.0*