# 视频审核系统使用文档

## 1. 概述

视频审核系统是基于阿里云内容安全服务构建的一套完整的视频内容审核解决方案。该系统支持视频内容的自动审核，包括暴力、色情、政治敏感等内容的检测，并提供了完整的任务管理、结果存储和异步处理机制。

## 2. 系统架构

视频审核系统采用微服务架构，主要包括以下组件：

1. **视频审核工具类** - 封装阿里云视频审核API调用
2. **视频审核服务类** - 处理业务逻辑，包括任务提交、结果查询等
3. **数据库实体类** - 定义视频审核任务的数据结构
4. **数据库Mapper接口** - 提供数据库操作方法
5. **XXL-JOB任务处理器** - 异步拉取审核结果
6. **控制器示例** - 提供HTTP接口示例

## 3. 功能说明

### 3.1 视频审核任务提交

用户可以通过调用[VideoModerationService.submitVideoModerationTask](file:///D:/database/alien_cloud/alien-util/src/main/java/shop/alien/util/common/safe/video/VideoModerationService.java#L47-L76)方法提交视频审核任务。

#### 3.1.1 功能描述

该功能将视频URL提交给阿里云内容安全服务进行审核，并将任务信息存储到数据库中。

#### 3.1.2 使用方法

```java
@Autowired
private VideoModerationService videoModerationService;

// 提交视频审核任务
String taskId = videoModerationService.submitVideoModerationTask("https://example.com/video.mp4");
```

#### 3.1.3 处理流程

1. 生成唯一的`dataId`标识
2. 调用阿里云接口提交视频审核任务
3. 获取阿里云返回的`taskId`
4. 将任务信息保存到数据库，状态设置为`SUBMITTED`

### 3.2 视频审核结果查询

用户可以通过调用[VideoModerationService.queryVideoModerationResult](file:///D:/database/alien_cloud/alien-util/src/main/java/shop/alien/util/common/safe/video/VideoModerationService.java#L84-L118)方法查询视频审核结果。

#### 3.2.1 功能描述

该功能直接从阿里云获取指定任务的审核结果，并更新数据库中的任务状态和结果。

#### 3.2.2 使用方法

```java
@Autowired
private VideoModerationService videoModerationService;

// 查询视频审核结果
VideoModerationTask task = videoModerationService.queryVideoModerationResult("your_task_id");
```

#### 3.2.3 处理流程

1. 从数据库查询任务信息
2. 调用阿里云接口获取审核结果
3. 更新数据库中的任务状态为`SUCCESS`，并保存审核结果
4. 返回完整的任务信息

### 3.3 异步审核结果拉取

系统通过XXL-JOB定时任务自动拉取审核结果，无需用户手动查询。

#### 3.3.1 功能描述

定时任务会定期扫描数据库中状态为`SUBMITTED`或`PROCESSING`的任务，并拉取其审核结果。

#### 3.3.2 配置方法

在XXL-JOB管理界面中添加新的任务，配置如下：

- 任务名称：`videoModerationResultJobHandler`
- 任务描述：视频审核结果拉取任务
- 调度时间：建议每30秒执行一次
- 任务参数：无需填写
- 负责人：根据实际情况填写
- 报警邮件：根据实际情况填写

#### 3.3.3 处理流程

1. 查询数据库中状态为`SUBMITTED`或`PROCESSING`的任务（最多100条）
2. 遍历每个任务，调用阿里云接口获取审核结果
3. 根据结果更新数据库：
   - 审核完成：更新状态为`SUCCESS`，保存结果
   - 审核中：更新状态为`PROCESSING`
   - 审核失败：更新状态为`FAILED`
4. 对于网络异常等临时错误，增加重试次数，超过3次后标记为`FAILED`

### 3.4 重试机制

系统实现了自动重试机制，以处理网络波动等临时性问题。

#### 3.4.1 功能描述

当异步拉取审核结果失败时，系统会自动重试，最多重试3次。

#### 3.4.2 处理流程

1. 拉取审核结果失败时，增加任务的重试次数
2. 如果重试次数未超过3次，继续保留任务等待下次拉取
3. 如果重试次数超过3次，将任务状态更新为`FAILED`

## 4. 数据库设计

### 4.1 表结构

视频审核任务信息存储在`video_moderation_task`表中，包含以下字段：

- `id`: 主键ID
- `data_id`: 数据ID
- `video_url`: 视频URL
- `task_id`: 阿里云任务ID
- [status](file://D:\database\alien_cloud\alien-entity\src\main\java\shop\alien\entity\result\R.java#L202-L204): 任务状态
- `risk_level`: 风险级别
- [result](file://D:\database\alien_cloud\alien-entity\src\main\java\shop\alien\entity\VideoModerationTask.java#L53-L53): 审核结果
- `create_time`: 创建时间
- `update_time`: 更新时间
- `retry_count`: 重试次数

### 4.2 状态说明

任务状态包括：

- `SUBMITTED`: 任务已提交
- `PROCESSING`: 任务处理中
- `SUCCESS`: 任务处理成功
- `FAILED`: 任务处理失败

## 5. API接口

系统提供了示例控制器[VideoModerationController](file:///D:/database/alien_cloud/alien-util/src/main/java/shop/alien/util/common/safe/video/VideoModerationController.java#L14-L52)，包含以下HTTP接口：

### 5.1 提交视频审核任务

```
POST /video/moderation/submit?videoUrl={videoUrl}
```

#### 请求参数

| 参数名 | 类型 | 必需 | 说明 |
|--------|------|------|------|
| videoUrl | string | 是 | 视频URL |

#### 响应示例

```json
{
  "code": 200,
  "message": "任务提交成功，任务ID: task_xxxxxx",
  "data": null
}
```

### 5.2 查询视频审核结果

```
GET /video/moderation/result?taskId={taskId}
```

#### 请求参数

| 参数名 | 类型 | 必需 | 说明 |
|--------|------|------|------|
| taskId | string | 是 | 任务ID |

#### 响应示例

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 1,
    "dataId": "video_xxxxxx",
    "videoUrl": "https://example.com/video.mp4",
    "taskId": "task_xxxxxx",
    "status": "SUCCESS",
    "riskLevel": "low",
    "result": "{\"riskLevel\":\"low\",\"frameResult\":{}}",
    "createTime": "2023-01-01 12:00:00",
    "updateTime": "2023-01-01 12:05:00",
    "retryCount": 0
  }
}
```

## 6. 配置说明

### 6.1 阿里云配置

在`application.yml`或Nacos配置中心中添加以下配置：

```yaml
ali:
  yundun:
    accessKeyID: your_access_key_id
    secret: your_access_key_secret
    imgEndpoint: green-cip.cn-shanghai.aliyuncs.com
    regionId: cn-shanghai
```

### 6.2 数据库配置

确保数据库连接配置正确，并且数据库中已创建`video_moderation_task`表。

### 6.3 XXL-JOB配置

确保XXL-JOB配置正确，并且任务处理器已注册到调度中心。

## 7. 错误处理

### 7.1 提交任务失败

当提交任务失败时，系统会抛出运行时异常，需要在调用方进行捕获处理。

### 7.2 查询结果失败

当查询结果失败时，系统会抛出运行时异常，需要在调用方进行捕获处理。

### 7.3 网络异常

对于网络异常等临时性错误，系统会自动重试，最多重试3次。

## 8. 性能优化建议

1. **批量处理**: XXL-JOB任务每次最多处理100条任务，可根据实际需求调整
2. **索引优化**: 数据库表已创建必要的索引，可根据查询模式进一步优化
3. **任务清理**: 建议定期清理已完成的任务，避免数据量过大影响性能
4. **重试机制**: 合理设置重试次数，避免无效重试占用系统资源

## 9. 扩展性说明

### 9.1 增加新的审核类型

如需支持其他类型的审核（如直播流审核），可以扩展[VideoModerationUtil](file:///D:/database/alien_cloud/alien-util/src/main/java/shop/alien/util/common/safe/video/VideoModerationUtil.java#L16-L101)工具类，添加相应的方法。

### 9.2 修改审核结果处理逻辑

如需修改审核结果的处理逻辑，可以修改[VideoModerationService.processTask](file:///D:/database/alien_cloud/alien-util/src/main/java/shop/alien/util/common/safe/video/VideoModerationService.java#L126-L185)方法。

### 9.3 调整异步处理策略

如需调整异步处理策略，可以修改[VideoModerationJobHandler](file:///D:/database/alien_cloud/alien-job/src/main/java/shop/alien/job/jobhandler/VideoModerationJobHandler.java#L16-L59)类中的处理逻辑。

## 10. 监控和日志

系统集成了完整的日志记录，可以通过日志监控任务执行情况：

1. 任务提交日志
2. 任务处理日志
3. 异常日志
4. 重试日志

建议通过日志分析工具对这些日志进行集中管理和分析。