# 视频审核系统数据库设计文档

## 1. 概述

本文档详细描述了视频审核系统的数据库设计方案，包括表结构设计、字段说明、状态管理、索引设计以及落库逻辑等内容。

## 2. 表结构设计

### 2.1 表名
`video_moderation_task` - 视频审核任务表

### 2.2 表结构

```sql
CREATE TABLE `video_moderation_task` (
  `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `data_id` varchar(64) NOT NULL COMMENT '数据ID',
  `video_url` varchar(512) NOT NULL COMMENT '视频URL',
  `task_id` varchar(64) NOT NULL COMMENT '任务ID',
  `status` varchar(20) NOT NULL DEFAULT 'SUBMITTED' COMMENT '任务状态 (SUBMITTED-已提交, PROCESSING-处理中, SUCCESS-成功, FAILED-失败)',
  `risk_level` varchar(10) DEFAULT NULL COMMENT '风险级别 (none-无风险, low-低风险, medium-中风险, high-高风险)',
  `result` text COMMENT '审核结果(JSON格式)',
  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `retry_count` int(11) NOT NULL DEFAULT '0' COMMENT '重试次数',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_task_id` (`task_id`),
  KEY `idx_status` (`status`),
  KEY `idx_create_time` (`create_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='视频审核任务表';
```

### 2.3 字段说明

| 字段名 | 类型 | 允许空 | 默认值 | 说明 |
|-------|------|-------|--------|------|
| id | bigint(20) | 否 | 无 | 主键ID，自增 |
| data_id | varchar(64) | 否 | 无 | 数据ID，用于标识审核的数据 |
| video_url | varchar(512) | 否 | 无 | 视频URL地址 |
| task_id | varchar(64) | 否 | 无 | 阿里云审核任务ID |
| status | varchar(20) | 否 | SUBMITTED | 任务状态 |
| risk_level | varchar(10) | 是 | NULL | 风险级别 |
| result | text | 是 | NULL | 审核结果，JSON格式存储 |
| create_time | datetime | 否 | CURRENT_TIMESTAMP | 创建时间 |
| update_time | datetime | 否 | CURRENT_TIMESTAMP | 更新时间 |
| retry_count | int(11) | 否 | 0 | 重试次数 |

## 3. 状态管理

系统中任务的状态流转如下：

- **SUBMITTED**: 任务已提交到阿里云，等待处理
- **PROCESSING**: 任务正在处理中
- **SUCCESS**: 任务处理成功，审核完成
- **FAILED**: 任务处理失败

状态流转图：
```
SUBMITTED -> PROCESSING -> SUCCESS
      |          |-> FAILED
      |-> FAILED (提交失败)
```

## 4. 索引设计

为了提高查询效率，表中设计了以下索引：

1. **主键索引**: `id` 字段，用于唯一标识每条记录
2. **唯一索引**: `task_id` 字段，确保阿里云任务ID的唯一性
3. **普通索引**: `status` 字段，提高按状态查询任务的效率
4. **普通索引**: `create_time` 字段，提高按创建时间查询任务的效率

## 5. 落库逻辑

### 5.1 提交任务时的落库逻辑

当用户提交视频审核任务时，系统会执行以下落库操作：

1. 生成唯一的数据ID (`data_id`)
2. 调用阿里云接口提交视频审核任务
3. 获取阿里云返回的`task_id`
4. 将任务信息保存到数据库中，初始状态为`SUBMITTED`

### 5.2 异步拉取结果时的落库逻辑

通过XXL-JOB定时任务定期拉取审核结果：

1. 查询数据库中状态为`SUBMITTED`或`PROCESSING`的任务
2. 调用阿里云接口获取审核结果
3. 根据结果更新数据库中的任务状态：
   - 如果审核完成，更新状态为`SUCCESS`，并保存审核结果到`result`字段
   - 如果仍在处理中，保持状态为`PROCESSING`
   - 如果审核失败，更新状态为`FAILED`
4. 对于网络异常等情况，增加重试次数，超过3次后标记为`FAILED`

### 5.3 重试机制

系统实现了重试机制来处理临时性错误：

1. 每次处理失败时，`retry_count`字段加1
2. 当重试次数超过3次时，将任务状态更新为`FAILED`
3. 重试机制避免了因网络波动等临时问题导致的任务永久失败

## 6. 示例数据

```sql
INSERT INTO `video_moderation_task` (`data_id`, `video_url`, `task_id`, `status`, `risk_level`, `result`) 
VALUES 
('video_1234567890', 'https://example.com/video.mp4', 'task_0987654321', 'SUCCESS', 'low', '{\"riskLevel\":\"low\",\"frameResult\":{}}');
```

## 7. 相关代码文件

1. 实体类: `alien-entity/src/main/java/shop/alien/entity/VideoModerationTask.java`
2. Mapper接口: `alien-entity/src/main/java/shop/alien/entity/VideoModerationTaskMapper.java`
3. Mapper XML: `alien-entity/src/main/resources/mapper/VideoModerationTaskMapper.xml`
4. 业务服务类: `alien-util/src/main/java/shop/alien/util/common/safe/video/VideoModerationService.java`
5. XXL-JOB任务类: `alien-job/src/main/java/shop/alien/job/jobhandler/VideoModerationJobHandler.java`

## 8. 注意事项

1. `result`字段存储的是JSON格式的审核结果，可根据需要进行解析
2. `video_url`字段最大长度为512字符，应确保视频URL不超过此长度
3. 定时任务会定期清理状态为`SUCCESS`或`FAILED`的旧任务，避免数据量过大
4. 重试次数限制为3次，可根据实际需求调整