将检测任务迁移python

2025-09-30 14:23:33 +08:00
parent 3fe5f8083d
commit 39d39a7a24
69 changed files with 7921 additions and 1836 deletions
--- a/INSPECTION-WORKFLOW.md
+++ b/INSPECTION-WORKFLOW.md
@@ -0,0 +1,544 @@
+# 巡检任务工作流程说明
+
+## 📋 功能概述
+
+本文档说明巡检任务的完整执行流程，包括视频录制、保存、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部署