rtsp-video-analysis-system/INSPECTION-WORKFLOW.md

# 巡检任务工作流程说明

## 📋 功能概述

本文档说明巡检任务的完整执行流程，包括视频录制、保存、AI识别和告警创建。

## 🔄 完整工作流程

### 1. 任务启动

当巡检任务启动时：

```
InspectionTaskServiceImpl.executeInspectionTask(taskId)
  ├── 创建 InspectionTaskRecord（记录ID）
  ├── 更新任务状态为"执行中"
  └── 调用 performVideoAnalysisWithRecord()
```

### 2. 视频录制和保存

```
performVideoAnalysisWithRecord()
  ├── 从RTSP流抓取视频
  ├── 录制指定时长的视频
  ├── 保存为临时文件
  ├── 上传视频到MinIO
  ├── 更新InspectionTaskRecord.accessory（视频URL）
  └── 调用Python服务进行分析
```

### 3. AI识别处理

```
VideoAnalysisService.analyzeVideoWithRecord()
  ├── 创建HttpYoloDetector（连接Python服务）
  ├── 逐帧分析视频
  ├── 每10帧调用一次Python API检测
  ├── 绘制检测框
  ├── 去重检测结果（避免重复告警）
  ├── 创建告警记录
  ├── 上传处理后的视频
  ├── 生成检测结果摘要
  └── 更新InspectionTaskRecord.result（识别结果）
```

### 4. 告警创建（去重）

```
createAlarmRecordForRecord()
  ├── 提取检测区域图像
  ├── 上传告警图片到MinIO
  ├── 创建AlarmRecord
  │   ├── 设备ID
  │   ├── 告警类型
  │   ├── 告警内容（检测类别+置信度）
  │   ├── 关联的任务ID
  │   ├── 图片URL
  │   └── 帧位置
  └── 保存到数据库（仅新检测的对象）
```

## 📊 数据表关系

```
InspectionTask (巡检任务)
  ↓ 1:N
InspectionTaskRecord (巡检记录)
  ├── accessory: 原始视频URL + 处理后视频URL
  ├── result: AI识别结果摘要
  ├── duration: 执行时长
  └── status: 0=成功, 1=失败, 2=部分成功
  
InspectionTaskRecord → AlarmRecord (1:N)
  ├── 同一个record可以有多个告警
  └── 告警自动去重（相同位置的相同对象只记录一次）
```

## 🎯 关键字段说明

### InspectionTaskRecord

| 字段 | 说明 | 示例 |
|------|------|------|
| recordId | 记录ID | 自增主键 |
| taskId | 关联的任务ID | 1001 |
| executeTime | 执行时间 | 2025-09-30 14:30:00 |
| duration | 执行时长（秒） | 30 |
| accessory | 附件URL | video1.mp4;video2.mp4 |
| result | 识别结果 | 共检测到3个问题，详情：垃圾(2) 烟雾(1) |
| status | 执行状态 | 0=成功, 1=失败, 2=部分成功 |

### AlarmRecord

| 字段 | 说明 | 示例 |
|------|------|------|
| alarmId | 告警ID | 自增主键 |
| deviceId | 设备ID | 1001 |
| taskId | 任务ID | 1001 |
| alarmType | 告警类型 | detection |
| alarmContent | 告警内容 | 垃圾 - 置信度: 0.95 |
| imageOssId | 告警图片ID | MinIO对象ID |
| framePosition | 视频帧位置 | 150 |
| confidence | 置信度 | 0.95 |
| status | 处理状态 | 0=未处理, 1=已处理 |

## 🔧 关键实现细节

### 1. 去重机制

使用`generateDetectionKey`生成唯一键：

```java
private String generateDetectionKey(Detection detection) {
    Rect rect = detection.getRect();
    // 取10的倍数，允许小范围波动
    int x = rect.x() / 10 * 10;
    int y = rect.y() / 10 * 10;
    int w = rect.width() / 10 * 10;
    int h = rect.height() / 10 * 10;
    return String.format("%s_%d_%d_%d_%d", detection.getLabel(), x, y, w, h);
}
```

**原理**：
- 相同类别 + 相似位置 → 认为是同一个对象
- 允许10像素的波动
- 超过60秒未检测到自动清除

### 2. Python服务调用

使用容器名调用：

```java
private static final String PYTHON_API_URL = "http://rtsp-python-service:8000/api/detect/file";
private static final String MODEL_NAME = "yolov8_detector";
```

### 3. 视频处理流程

```
RTSP流 → FFmpegFrameGrabber → 录制 → 临时文件 
  → 上传MinIO → 保存URL到record.accessory
  → 逐帧分析 → 调用Python API → 绘制检测框
  → 保存处理后视频 → 追加URL到record.accessory
  → 更新record.result
```

### 4. 附件字段格式

`accessory`字段使用分号分隔多个URL：

```
原始视频URL;处理后视频URL
```

示例：
```
http://minio.com/inspection-videos/inspection_1001_1234567890.mp4;http://minio.com/inspection-videos/processed_1234567891.mp4
```

## 🚀 使用方法

### 1. 创建巡检任务

```java
InspectionTask task = new InspectionTask();
task.setDeviceId(deviceId);
task.setDuration(30); // 录制30秒
task.setStatus(0); // 待执行

inspectionTaskService.insertInspectionTask(task);
```

### 2. 启动任务

```java
// 异步执行
inspectionTaskService.executeInspectionTask(taskId);
```

### 3. 查看执行记录

```sql
-- 查询某任务的所有执行记录
SELECT * FROM v_inspection_task_record WHERE task_id = 1001 ORDER BY execute_time DESC;

-- 查询成功的记录
SELECT * FROM v_inspection_task_record WHERE status = 0;

-- 查询某记录的所有告警
SELECT * FROM v_alarm_record WHERE task_id = 1001;
```

### 4. 查看告警

```sql
-- 查询某任务的所有告警
SELECT * FROM v_alarm_record WHERE task_id = 1001 ORDER BY create_time DESC;

-- 查询未处理的告警
SELECT * FROM v_alarm_record WHERE status = 0;
```

## 📝 执行示例

### 执行流程

1. **任务创建**
   ```
   Task ID: 1001
   Device ID: 5001
   Duration: 30秒
   ```

2. **记录创建**
   ```
   Record ID: 2001
   Task ID: 1001
   Execute Time: 2025-09-30 14:30:00
   Status: 1 (执行中)
   ```

3. **视频录制**
   ```
   录制30秒视频
   保存到MinIO: inspection_1001_1234567890.mp4
   更新Record.accessory: http://minio.com/.../inspection_1001_1234567890.mp4
   ```

4. **AI识别**
   ```
   调用Python服务
   检测到: 垃圾(2个), 烟雾(1个)
   ```

5. **告警创建**（去重）
   ```
   Alarm 1: 垃圾 - 位置(100,200) - 置信度0.95
   Alarm 2: 垃圾 - 位置(300,400) - 置信度0.87
   Alarm 3: 烟雾 - 位置(500,100) - 置信度0.92
   ```

6. **处理后视频**
   ```
   带检测框的视频上传
   保存到MinIO: processed_1234567891.mp4
   更新Record.accessory: 原始URL;处理后URL
   ```

7. **更新记录**
   ```
   Record.result: "共检测到 3 个问题，详情：垃圾(2) 烟雾(1)"
   Record.status: 0 (成功)
   Record.duration: 32秒
   ```

## ⚙️ 配置说明

### Python服务配置

在Docker环境中，Python服务地址为：
```
http://rtsp-python-service:8000
```

### 模型配置

确保Python服务使用正确的模型名称：
```json
{
  "name": "yolov8_detector",
  "path": "models/yolov8_model.py",
  "size": [640, 640]
}
```

### 检测参数

在`VideoAnalysisService`中可调整：

```java
// 检测频率（每N帧检测一次）
if (frameCount % 10 == 0) { ... }

// 去重时间窗口（秒）
detectedGarbageCache.entrySet().removeIf(entry -> 
    (currentId - entry.getValue()) > grabber.getFrameRate() * 60);
```

## 🐛 故障排查

### 问题1: 视频未保存

**检查**：
```sql
-- 查看record的accessory字段
SELECT record_id, accessory FROM v_inspection_task_record WHERE task_id = ?;

-- 查看MinIO对象
SELECT * FROM v_minio_object WHERE bucket_name = 'inspection-videos' ORDER BY create_time DESC;
```

**解决**：
- 检查MinIO服务是否可用
- 检查网络连接
- 查看后端日志

### 问题2: Python识别未执行

**检查**：
```bash
# 查看Python服务日志
docker-compose logs python-service

# 测试Python服务
curl http://rtsp-python-service:8000/health
curl http://rtsp-python-service:8000/api/models
```

**解决**：
- 确认Python服务运行正常
- 确认模型文件存在
- 检查网络连通性

### 问题3: 告警未创建

**检查**：
```sql
-- 查看告警记录
SELECT * FROM v_alarm_record WHERE task_id = ? ORDER BY create_time DESC;

-- 查看检测结果
SELECT result FROM v_inspection_task_record WHERE record_id = ?;
```

**解决**：
- 检查检测置信度阈值
- 查看视频内容是否有检测对象
- 检查Python服务返回结果

### 问题4: 重复告警

**检查**：
- 去重机制是否正常工作
- `generateDetectionKey`逻辑是否合理

**调整**：
```java
// 调整去重的位置容差
int x = rect.x() / 20 * 20;  // 从10改为20，更宽松的去重
```

## 📊 性能优化

### 1. 检测频率

```java
// 降低检测频率以提升性能（CPU模式）
if (frameCount % 30 == 0) { // 从10改为30
    // 每30帧检测一次
}
```

### 2. 视频质量

```java
// 降低视频比特率节省存储
recorder.setVideoBitrate(500000); // 降低比特率
```

### 3. 去重时间窗口

```java
// 缩短去重时间窗口
(currentId - entry.getValue()) > grabber.getFrameRate() * 30  // 从60秒改为30秒
```

## 🔍 调试方法

### 查看执行日志

```bash
# 查看后端日志
docker-compose logs -f backend | grep "inspection"

# 查看Python服务日志
docker-compose logs -f python-service

# 查看特定记录的处理过程
docker-compose logs backend | grep "recordId=2001"
```

### 数据库查询

```sql
-- 查看最新的执行记录
SELECT 
    r.record_id,
    r.task_id,
    r.execute_time,
    r.duration,
    r.status,
    r.result,
    LENGTH(r.accessory) as accessory_length
FROM v_inspection_task_record r
ORDER BY r.create_time DESC
LIMIT 10;

-- 查看记录对应的告警
SELECT 
    a.alarm_id,
    a.alarm_content,
    a.confidence,
    a.frame_position,
    a.create_time
FROM v_alarm_record a
WHERE a.task_id = ?
ORDER BY a.create_time DESC;

-- 统计告警数量
SELECT 
    r.record_id,
    r.execute_time,
    COUNT(a.alarm_id) as alarm_count
FROM v_inspection_task_record r
LEFT JOIN v_alarm_record a ON r.task_id = a.task_id
    AND a.create_time >= r.execute_time
    AND a.create_time <= DATE_ADD(r.execute_time, INTERVAL r.duration SECOND)
GROUP BY r.record_id
ORDER BY r.create_time DESC;
```

## 💡 扩展建议

### 1. 添加检测类型过滤

在`createAlarmRecordForRecord`中：

```java
// 只对特定类型创建告警
List<String> alarmTypes = Arrays.asList("垃圾", "烟雾", "火焰");
if (!alarmTypes.contains(detection.getLabel())) {
    return; // 忽略其他类型
}
```

### 2. 添加置信度阈值

```java
// 只对高置信度的检测创建告警
if (detection.getConfidence() < 0.7) {
    return; // 忽略低置信度检测
}
```

### 3. 添加区域过滤

```java
// 只对特定区域的检测创建告警
Rect rect = detection.getRect();
if (!isInMonitorArea(rect, task)) {
    return; // 忽略监控区域外的检测
}
```

### 4. 添加告警级别

```java
// 根据检测类型设置告警级别
String alarmLevel = "medium";
if (detection.getLabel().contains("火焰")) {
    alarmLevel = "high";
} else if (detection.getLabel().contains("垃圾")) {
    alarmLevel = "low";
}
alarmRecord.setAlarmLevel(alarmLevel);
```

## 🔒 安全考虑

### 1. 异常处理

所有方法都包含完整的异常处理：
- 视频录制失败 → 更新record状态为失败
- Python服务调用失败 → 记录错误但不影响整体流程
- MinIO上传失败 → 记录错误并回滚

### 2. 资源清理

使用try-finally确保资源释放：
- FFmpegFrameGrabber自动关闭
- FFmpegFrameRecorder自动关闭
- 临时文件自动删除

### 3. 并发控制

使用`@Async`异步执行，避免阻塞：
- 任务执行不阻塞API响应
- 多个任务可并发执行
- 通过runningTasks避免重复执行

## 📈 监控指标

### 建议监控的指标

1. **执行成功率**
   ```sql
   SELECT 
       COUNT(CASE WHEN status = 0 THEN 1 END) * 100.0 / COUNT(*) as success_rate
   FROM v_inspection_task_record
   WHERE execute_time >= DATE_SUB(NOW(), INTERVAL 1 DAY);
   ```

2. **平均执行时长**
   ```sql
   SELECT AVG(duration) as avg_duration
   FROM v_inspection_task_record
   WHERE status = 0 AND execute_time >= DATE_SUB(NOW(), INTERVAL 1 DAY);
   ```

3. **告警统计**
   ```sql
   SELECT 
       alarm_type,
       COUNT(*) as count
   FROM v_alarm_record
   WHERE create_time >= DATE_SUB(NOW(), INTERVAL 1 DAY)
   GROUP BY alarm_type;
   ```

## 📞 技术支持

如有问题，请查看：
1. 后端日志：`docker-compose logs backend`
2. Python服务日志：`docker-compose logs python-service`
3. 数据库记录：查询`v_inspection_task_record`和`v_alarm_record`表
4. MinIO对象：查询`v_minio_object`表

---

**文档版本**: 1.0
**最后更新**: 2025-09-30
**适用版本**: YOLOv8, Docker Compose部署