# Flight Support Vision System

**Repository Path**: thinkerofnight/flight-support-vision-system

## Basic Information

- **Project Name**: Flight Support Vision System
- **Description**: No description available
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-18
- **Last Updated**: 2026-08-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 项目分析文档

## 1. 项目概述
本项目是一个**智能视频监控事件检测系统**，基于 Spring Boot 框架构建，主要用于机场/园区等场景下的**节点事件（如飞机入位、轮挡放置、加油等）实时识别与告警**。系统通过 Redis Stream 实现视频帧的异步传输，调用外部算法 API（FastAPI 部署的目标检测模型）进行对象识别，并利用自定义状态机判断事件的发生与结束，最终将结果存储并推送至 RabbitMQ 供前端或下游系统消费。

项目主要分为两大模块：
- **视频处理框架**（`com.ruoyi.vedioFrame`）：负责实时视频流消费、帧处理、算法调用、事件逻辑。
- **业务管理平台**（`com.ruoyi.videoAnalysisPlatform`）：负责摄像头管理、事件配置、区域标注、结果存储及错误反馈。

---

## 2. 技术栈
| 技术 | 用途 |
|------|------|
| **Spring Boot 2.x** | 应用基础框架 |
| **Redis (Stream)** | 视频帧消息队列，支持多消费者组 |
| **RabbitMQ** | 事件结果推送及错误反馈 |
| **FastAPI (Python)** | 目标检测算法服务（通过 HTTP 调用） |
| **MyBatis** | 数据库 ORM |
| **JavaCV / FFmpeg** | RTSP 流截图及处理 |
| **HttpClient** | 与算法服务通信 |
| **Lombok / SLF4J** | 日志与代码简化 |
| **ThreadPoolExecutor** | 并发帧处理 |

---

## 3. 整体架构设计

```mermaid
flowchart TB
    subgraph 视频源
        RTSP[RTSP 摄像头]
    end

    subgraph 生产者服务
        Producer[外部生产者模块] -->|推送帧| RedisStream[(Redis Stream)]
    end

    subgraph 消费者服务
        StreamConsumer[StreamConsumerService] -->|读取帧| RedisStream
        StreamConsumer -->|解码Base64| FrameProcessor[FrameProcessor]
        FrameProcessor -->|调用API| FastAPI[FastAPI 检测服务]
        FastAPI -->|返回检测结果| FrameProcessor
        FrameProcessor -->|解析结果| LogicalHandle[LogicalHandle]
    end

    subgraph 事件处理
        LogicalHandle -->|状态机判断| EventTrigger[事件触发]
        EventTrigger -->|保存图片| LocalStorage[本地存储]
        EventTrigger -->|插入数据库| DB[(MySQL)]
        EventTrigger -->|发送RabbitMQ| RabbitMQ[RabbitMQ]
    end

    subgraph 管理平台
        Web[Web管理端] -->|配置摄像头/事件/区域| DB
        Web -->|启动/停止| StreamConsumer
        RabbitMQ -->|推送事件| Web
        Feedback[反馈队列] -->|错误反馈| DB
    end
```

---

## 4. 核心模块说明

### 4.1 视频帧消费与处理
- **`StreamConsumerService`**  
  使用 Redis Stream 的消费者组机制，每个摄像头对应一个 Stream（`stream:{cameraId}`），每个消费者线程从组中读取消息，立即 ACK，再提交帧处理任务到线程池（`frameProcessingExecutor`）。支持启动/停止单个摄像头。

- **`FrameProcessor`**  
  将 Base64 编码的图像数据还原为 `BufferedImage`，调用算法 API（支持两种模式：`deployMode` 决定是 multipart 上传还是 JSON 封装），解析返回的 JSON 数据（包含目标类别、边界框、置信度），转换为统一格式后调用 `LogicalHandle.core`。

- **`LogicalHandle`**  
  核心事件判断引擎。维护每个摄像头的一组节点（飞机、轮挡、廊桥等），每个节点有固定长度的布尔队列（`queue`），记录每一帧中该目标是否在划定区域内。当队列满时，计算队列中不同分段的 true/false 数量，结合状态机规则触发开始/结束事件，并调用 `addNodeResult` 保存图片和数据库记录，同时通过 RabbitMQ 推送消息。

### 4.2 节点状态管理
- **`CommonQueues`**  
  维护一个全局 `ConcurrentHashMap`，以摄像头 ID 为键，存储该摄像头的所有节点对象（`Nodes`）。`Nodes` 包含各个具体节点（`Jiedian`）及全局计数器（`imgIndex`, `nodeId`）。
- **`Jiedian` 类**  
  每个节点包含：
  - `queue`：`ArrayBlockingQueue<Boolean>`，存储最近 N 帧的目标存在性（N 由 `maxQueueSize` 决定）。
  - `state`：当前是否处于激活状态（事件进行中）。
  - `timing`：事件开始时的帧序号，用于判断持续时间。
  - `done`：标记事件是否已结束（防止重复触发）。
  - 坐标信息 `x, y, width, height` 等。

### 4.3 事件触发与推送
- 事件触发条件示例：
  - **飞机入位**：队列中后半段 true 数量 ≥8 且前半段 false 数量 ≥8，同时当前节点未激活。
  - **飞机推出**：队列中后半段 true 数量 ≤3 且前半段 false 数量 ≤8，且距入位超过 120 帧。
- 触发后调用 `addNodeResult`：
  - 保存当前帧为 JPG 文件（路径：`static/nodeImgs/cameraId{id}/`）。
  - 插入 `xh_node_result` 表，生成唯一 `rabbitmqId`（时间戳+摄像头ID）。
  - 查询事件绑定状态（`xh_event_enable`），若开启则构造 JSON 消息，通过 RabbitMQ 发送到交换器 `send`（无 routing key）。

### 4.4 管理后台功能
- **摄像头管理**（`XhCameraController`）  
  支持 CRUD，启用/停用摄像头时会调用外部生产者服务的 HTTP 接口（`/api/video/startProducer` / `stopProducer`）以及控制本地消费者线程。
- **事件绑定**（`XhEventEnableController`）  
  管理每个摄像头开启哪些事件（通过 `event_code` 与 `enable` 字段）。
- **区域标注**（`XhNodeRegionLabelController`）  
  为摄像头设置多边形区域（坐标点），算法检测到的目标只有落入该区域才会被记录。支持从当前画面截图、绘制区域、保存并生效（文件迁移至 `readyRegionsImg` 或 `regionsImg`）。
- **结果查看**（`XhNodeResultController`）  
  展示已识别的节点事件列表，并提供图片下载。

### 4.5 错误反馈机制
- **`FeedbackQueueListener`**  
  监听 RabbitMQ 的 `feedback` 队列，接收前端或下游反馈的识别错误信息（如误报、漏报），将错误记录保存到 `xh_node_rec_error` 表，用于后续模型优化。

---

## 5. 关键流程时序图

```mermaid
sequenceDiagram
    participant Producer as 帧生产者
    participant Redis as Redis Stream
    participant Consumer as StreamConsumerService
    participant FP as FrameProcessor
    participant API as FastAPI算法
    participant LH as LogicalHandle
    participant DB as MySQL
    participant MQ as RabbitMQ

    loop 每帧
        Producer->>Redis: XADD stream:camId frameData
        Consumer->>Redis: XREADGROUP (阻塞)
        Redis-->>Consumer: 返回帧消息
        Consumer->>Redis: XACK (立即确认)
        Consumer->>FP: process(strData, camId)
        FP->>API: POST /detect (图片)
        API-->>FP: 检测结果JSON
        FP->>LH: core(result, frame)
        LH->>LH: 解析检测框，更新节点队列
        alt 队列已满
            LH->>LH: 应用状态机规则
            alt 事件触发
                LH->>LH: addNodeResult
                LH->>DB: INSERT xh_node_result
                LH->>FileSystem: 保存图片
                LH->>MQ: 发送事件消息
            end
        end
    end
```

---

## 6. 数据库设计要点（主要表）
| 表名 | 说明 |
|------|------|
| `xh_camera` | 摄像头信息（ID, 名称, RTSP地址, 启用状态, 在线状态） |
| `xh_event` | 事件字典（事件编码、名称、类型） |
| `xh_event_enable` | 摄像头-事件绑定（开启/关闭） |
| `xh_node_region_label` | 节点区域标注（多边形坐标、图片文件名） |
| `xh_node_result` | 节点事件结果（事件编码、摄像头ID、图片名、时间、rabbitmqId） |
| `xh_node_rec_error` | 节点识别错误反馈 |
| `xh_abn_*` | 异常事件相关表（类似节点，但未完全实现） |
| `xh_algorithm_para` | 算法参数配置（预留） |
| `xh_op_logs` | 操作日志 |

---

## 7. 配置与部署要点

### 7.1 配置文件（application.yml 或 properties）
```yaml
selfPara:
  fastApiIP: 10.70.18.89
  fastApiPort: 8888
  fastApiUrl: /detect/
  deployMode: true        # true: JSON body, false: multipart
  imgFormatName: jpg
  producerUrlIp: 10.70.18.89   # 生产者服务IP
  expirationTimeOfRtsp: 3000   # RTSP流验证超时(ms)
```

### 7.2 外部依赖
- **Redis**：需开启 Stream 功能，默认使用 `streamRedisTemplate`。
- **RabbitMQ**：需配置交换器 `send` 和队列 `feedback`。
- **算法服务**：需提供 `/detect` 接口，返回格式示例：
```json
{
  "result": {
    "data": [
      {
        "class_id": 2,
        "class_name": "廊桥",
        "bbox": [x1, y1, x2, y2],
        "confidence": 0.91
      }
    ]
  }
}
```
- **生产者服务**：外部独立进程，负责从 RTSP 拉流并写入 Redis Stream，提供 `/startProducer` 和 `/stopProducer` 接口。

### 7.3 启动流程
1. 项目启动时，`@PostConstruct` 自动扫描数据库中 `enable=1` 且在线状态正常的摄像头，为每个启动一个消费者线程。
2. 通过 `RtspValidator` 定期检测摄像头在线状态（定时任务未显式展示，但 `XhCameraServiceImpl.selectCameraStateById` 会实时检测并更新状态）。
3. 管理员可通过管理界面手动启用/停用摄像头。

---

## 8. 存在的问题与潜在优化点

### 8.1 性能与资源
- **帧处理使用线程池**：`frameProcessingExecutor` 大小固定为 `CPU核心数*2`，若处理速度跟不上生产速度，可能造成消息堆积（但已限制每次只读1条并快速ACK，降低了风险）。
- **图片保存频繁**：事件触发时保存图片，可能造成大量小文件 I/O，建议改用对象存储或定期清理。

### 8.2 代码质量
- **硬编码区域**：`LogicalHandle.core` 中 `regions` 被直接赋固定字符串，注释掉从数据库查询，可能为调试遗留，应改为从数据库读取。
- **异常处理**：部分 catch 块仅打印堆栈，未进行适当恢复或告警。
- **事务边界**：`addNodeResult` 标注了 `@Transactional`，但内部包含文件 I/O 操作，可能导致事务时间过长，建议将文件保存移出事务或异步处理。

### 8.3 功能完整性
- 异常事件（如反光服违规）相关代码已注释，尚未集成。
- 节点重置逻辑（`resetAllNodes`）在飞机推出时调用，但会重置所有节点状态，可能导致其他正在进行的节点事件被意外中断，需评估业务合理性。

---

## 9. 总结
本项目实现了机场停机位节点事件的自动识别与推送，通过 Redis Stream 解耦了视频生产和消费，结合自定义状态机完成了复杂事件的时序判断。系统提供了完整的后台管理功能，便于运维人员配置和监控。整体架构清晰，模块划分合理，但仍有部分代码待完善和优化。后续可考虑引入规则引擎（如 Drools）简化状态机逻辑，并增强对异常场景的容错处理。