# jc-video-recognize 项目现状与功能梳理

> 基于 `event-judgment-algorithm-architecture.md` 和 `project-integration-plan.md` 两份架构设计文档，
> 结合三个 MVP 迭代的实际代码实现，对项目当前已实现功能的全面梳理。

---

## 文档信息

- **项目名称**: jc-video-recognize 视频模型检测平台
- **文档版本**: v2.0
- **更新日期**: 2026-06-16
- **覆盖范围**: MVP-1（事件判断管道）+ MVP-2（RTSP/MQTT/实时推送）+ MVP-3（LLM 二次判断）

---

## 1. 项目概述

本项目是一个全栈视频智能检测平台，集成了多种 AI 检测模型（YOLO 系列 + PaddlePaddle 系列），覆盖火灾、安全帽、人群、抽烟、徘徊、车辆违停、打架斗殴等场景。系统在原始检测能力基础上，构建了完整的事件判断管道、RTSP 视频流接入、MQTT 预警发布、WebSocket 实时推送、以及大模型二次判断等企业级能力。

### 1.1 技术栈

| 层级 | 技术栈 | 说明 |
|------|--------|------|
| **前端** | Vue 3 + Vite 5 + Element Plus + Pinia | 暗色主题 UI，4 个核心页面 |
| **后端** | FastAPI + Uvicorn | REST API + WebSocket |
| **AI 推理** | YOLOv8/v10 (Ultralytics) + PaddlePaddle 3.0 | 多模型检测服务 |
| **视频流** | OpenCV + RTSP | 多路摄像头实时接入 |
| **消息系统** | MQTT (paho-mqtt) | 预警事件发布 |
| **大模型** | OpenAI 兼容协议 (GPT-4V/Qwen-VL/GLM-4V) | 二次判断与结果融合 |
| **目标跟踪** | ByteTrack (纯 Python) | 稳定跟踪 ID 分配 |
| **构建部署** | pnpm + Turborepo + Docker + Nginx | Monorepo 管理 |

### 1.2 整体架构图

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           前端 (Vue 3)                                      │
│  ┌──────────┐ ┌──────────────┐ ┌──────────┐ ┌──────────────┐              │
│  │ 模型检测  │ │ 摄像头管理    │ │ 规则配置  │ │ 预警列表     │              │
│  │ Home.vue │ │ CameraMgmt   │ │ RuleConfig│ │ AlertList    │              │
│  └────┬─────┘ └──────┬───────┘ └────┬─────┘ └──────┬───────┘              │
│       │               │              │               │                      │
│       └───────────────┴──────────────┴───────────────┘                      │
│                       │ HTTP/REST + WebSocket                              │
└───────────────────────┼─────────────────────────────────────────────────────┘
                        │
┌───────────────────────┼─────────────────────────────────────────────────────┐
│                       ▼                                                     │
│                  后端 (FastAPI)                                              │
│  ┌──────────────────────────────────────────────────────────────────────┐  │
│  │                         API 层                                       │  │
│  │  /api/detect/*  /api/models/*  /api/rtsp/*  /api/rules/*  /api/llm/*│  │
│  │  /ws/camera    /ws/alerts                                           │  │
│  └──────────────────────────┬───────────────────────────────────────────┘  │
│                             │                                              │
│  ┌──────────────────────────▼───────────────────────────────────────────┐  │
│  │                      服务层                                          │  │
│  │                                                                      │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌────────────┐ │  │
│  │  │ DetectionSvc │  │ RTSPService │  │ StreamMgr   │  │ MQTTService│ │  │
│  │  │ (检测核心)   │  │ (流接入)    │  │ (多路调度)  │  │ (消息发布) │ │  │
│  │  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────┬─────┘ │  │
│  │         │                │                │                │        │  │
│  │  ┌──────▼────────────────▼────────────────▼────────────────▼─────┐ │  │
│  │  │                    事件判断管道                                 │ │  │
│  │  │                                                                │ │  │
│  │  │  DecisionEngine → AlertRuleEngine → EventAggregator            │ │  │
│  │  │       │                                              │         │ │  │
│  │  │       ▼                                              ▼         │ │  │
│  │  │  ┌──────────────────────────────────────────────────────┐     │ │  │
│  │  │  │              LLM 二次判断管道                         │     │ │  │
│  │  │  │  FrameAccumulator → LLMTrigger → LLMAnalysisService  │     │ │  │
│  │  │  │  ResultFusion + LLMCostTracker (熔断降级)             │     │ │  │
│  │  │  └──────────────────────────────────────────────────────┘     │ │  │
│  │  └───────────────────────────────────────────────────────────────┘ │  │
│  │                                                                    │  │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐    │  │
│  │  │ ByteTracker  │  │ AlertPublisher│  │ DetectionAdapter    │    │  │
│  │  │ (目标跟踪)   │  │ (MQTT发布)   │  │ (结果格式统一)       │    │  │
│  │  └──────────────┘  └──────────────┘  └──────────────────────┘    │  │
│  └───────────────────────────────────────────────────────────────────┘  │
│                                                                          │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │                      推理引擎层                                    │  │
│  │  ┌─────────┐  ┌──────────────┐  ┌────────────┐                  │  │
│  │  │  YOLO   │  │ PaddlePaddle │  │ Docker API │                  │  │
│  │  │(Ultralytics) │(PP-YOLOE)  │  │ (ppTSM)    │                  │  │
│  │  └─────────┘  └──────────────┘  └────────────┘                  │  │
│  └───────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────────┘
```

---

## 2. 已实现功能清单

### 2.1 AI 检测能力（原始功能）

| 模型 ID | 名称 | 框架 | 检测类别 | 图片检测 | 视频检测 |
|---------|------|------|----------|---------|---------|
| `fire_detection` | 火灾检测 | YOLOv10 | 火焰、烟雾 | ✅ | ❌ |
| `helmet_detection` | 安全帽检测 | YOLOv8 | 人员、安全帽 | ✅ | ❌ |
| `crowd_detection` | 人群检测 | YOLOv8 | 人员 | ✅ | ❌ |
| `smoking_detection` | 抽烟检测 | YOLOv8 | 香烟、烟雾 | ✅ | ❌ |
| `smoking_detection_paddle` | 抽烟检测 (Paddle) | PP-YOLOE-s | 香烟 | ✅ | ❌ |
| `loitering_detection` | 徘徊检测 | YOLOv8 | 人员（含行为分析） | ✅ | ❌ |
| `vehicle_detection` | 车辆检测 | PP-YOLOE-l | 车辆 | ✅ | ❌ |
| `illegal_parking_detection` | 违停检测 | PP-YOLOE-l | 车辆（含违停判断） | ✅ | ❌ |
| `fight_detection` | 打架斗殴检测 | YOLOv8 | 暴力行为、正常 | ✅ | ✅ |
| `action_detection` | 打架检测 (Docker) | ppTSM | 打架、正常 | ✅ | ❌ |

**行为分析算法**（集成在 `loitering_detection` 下）：

| 算法 | 说明 | 参数 |
|------|------|------|
| 静止检测 | 基于位置匹配，检测人员静止停留 | 静止阈值(秒)、位置容差(像素) |
| 徘徊检测 | 基于跟踪ID，检测人员长时间停留 | 徘徊阈值(秒)、移动阈值(像素) |

**检测适配器**：通过 `DetectionAdapter` 将 YOLO、PaddlePaddle、Docker 三种不同输出格式统一为 `UnifiedDetection` / `DetectionResult`，为后续事件管道提供一致的数据入口。

---

### 2.2 事件判断管道（MVP-1 已实现）

对应设计文档 `event-judgment-algorithm-architecture.md` 中的「决策层」。

#### 2.2.1 事件决策引擎 (`EventDecisionEngine`)

**文件**: `services/event/decision_engine.py`

- 根据置信度阈值过滤检测结果
- 将底层 class_name 映射为统一 `EventType` 枚举（fire/smoke/smoking/fight/loitering/illegal_parking 等）
- 生成 `CandidateEvent` 候选事件，附带严重性级别、来源信息、检测详情

#### 2.2.2 预警规则引擎 (`AlertRuleEngine`)

**文件**: `services/event/rule_engine.py`

- 从 YAML 配置目录加载规则（`config/rules/*.yaml`）
- 支持规则类型：置信度阈值、事件类型、最小边界框面积、限定摄像头来源、必备标签
- 每条规则可配置严重性级别（info/low/medium/high/critical）
- 支持热重载（无需重启服务即可更新规则）
- 已内置规则文件：`fire.yaml`、`smoking.yaml`、`loitering.yaml`、`fight.yaml`、`vehicle.yaml`

#### 2.2.3 事件聚合器 (`EventAggregator`)

**文件**: `services/event/aggregator.py`

- 基于时间窗口去重：同一 (source_id, event_type, track_id) 在窗口内只产生一条预警
- 空间邻近合并：IOU 超过阈值的同类事件自动合并
- 置信度加权融合：历史置信度按衰减因子递减，新检测加权更新
- 输出 `AlertEvent`，包含首次/末次出现时间、触发次数、关联检测列表

#### 2.2.4 统一事件数据契约 (`event_schemas.py`)

**文件**: `models/event_schemas.py`

定义了完整的事件数据模型体系：

| 模型 | 说明 |
|------|------|
| `EventType` | 统一事件类型枚举（11 种） |
| `SeverityLevel` | 严重性级别枚举（5 级） |
| `DetectionSource` | 检测来源枚举（YOLO/Paddle/Docker/Behavior/Composite） |
| `BBox` | 边界框 (xyxy) |
| `UnifiedDetection` | 统一检测结果（含 track_id） |
| `DetectionResult` | 单帧检测结果集合 |
| `CandidateEvent` | 候选事件（决策引擎输出） |
| `AlertEvent` | 预警事件（聚合器输出，最终发布格式） |

---

### 2.3 RTSP 视频流接入（MVP-2 已实现）

对应设计文档 `project-integration-plan.md` 中的「视频流接入方案」。

#### 2.3.1 RTSP 流接入服务 (`RTSPService`)

**文件**: `services/rtsp_service.py`

- 基于 OpenCV VideoCapture 的 RTSP 接入，兼容主流 IP 摄像头
- 后台线程解码帧，避免阻塞事件循环
- 自动重连：断线后按指数退避策略重试（可配置最大次数、间隔、退避因子）
- 帧回调机制：每解码一帧触发回调，由 StreamManager 分发到检测管道
- 优雅关闭：stop() 等待解码线程退出，释放资源
- 流状态管理：idle → connecting → connected → reconnecting → stopped → error

#### 2.3.2 多路流调度管理器 (`StreamManager`)

**文件**: `services/stream_manager.py`

- 统一管理多路 RTSPService 实例（最大 16 路，可配置）
- 每路流对应一个 `FrameBuffer`（环形缓冲区），解耦解码与检测
- 检测调度：轮询帧缓冲区，按流配置的模型和参数执行检测
- 状态监控：汇总所有流状态，提供健康检查接口
- RESTful API 管理：添加/移除/启动/停止/配置更新

#### 2.3.3 帧缓冲区 (`FrameBuffer`)

**文件**: `services/frame_buffer.py`

- 环形缓冲区设计，防止内存溢出
- 支持丢帧策略（最新帧优先 / 均匀采样）
- 线程安全：解码线程写入、检测线程读取

#### 2.3.4 RTSP 管理 API

**文件**: `api/rtsp.py`

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/rtsp/streams` | 获取所有流状态列表 |
| `GET` | `/api/rtsp/streams/{stream_id}` | 获取单路流详情 |
| `POST` | `/api/rtsp/streams` | 添加新摄像头流 |
| `DELETE` | `/api/rtsp/streams/{stream_id}` | 移除摄像头流 |
| `POST` | `/api/rtsp/streams/{stream_id}/start` | 启动指定流 |
| `POST` | `/api/rtsp/streams/{stream_id}/stop` | 停止指定流 |
| `PUT` | `/api/rtsp/streams/{stream_id}/config` | 更新流检测配置 |
| `POST` | `/api/rtsp/start-all` | 启动全部流 |
| `POST` | `/api/rtsp/stop-all` | 停止全部流 |
| `GET` | `/api/rtsp/health` | 健康检查 |

---

### 2.4 MQTT 预警消息系统（MVP-2 已实现）

对应设计文档 `project-integration-plan.md` 中的「MQTT预警事件消息系统」。

#### 2.4.1 MQTT 客户端服务 (`MQTTService`)

**文件**: `services/mqtt_service.py`

- 基于 paho-mqtt 的 MQTT 客户端封装
- 支持用户名/密码认证
- 自动重连：按指数退避策略重试（可配置最小/最大延迟）
- QoS 等级可配置（默认 QoS 1，确保至少送达一次）
- 消息保留（retain）可配置

#### 2.4.2 预警发布器 (`AlertPublisher`)

**文件**: `services/alert_publisher.py`

- 将 `AlertEvent` 格式化为标准 JSON 消息
- 主题命名规则：`{prefix}/{event_type}/{source_id}`（单流单类型）、`{prefix}/all`（全量订阅）
- 同时触发 WebSocket 广播（通过 AlertBroadcaster）
- 消息包含：alert_id、event_type、severity、confidence、source_id、rule_name、detections 等

#### 2.4.3 MQTT 配置

通过环境变量或 `.env` 文件配置：

| 配置项 | 环境变量 | 默认值 | 说明 |
|--------|----------|--------|------|
| 启用 | `MQTT_ENABLED` | `false` | 是否启用 MQTT |
| Broker 地址 | `MQTT_BROKER_HOST` | `localhost` | MQTT 服务器 |
| Broker 端口 | `MQTT_BROKER_PORT` | `1883` | 端口 |
| 客户端 ID | `MQTT_CLIENT_ID` | `jc-video-recognize` | 客户端标识 |
| QoS | `MQTT_QOS` | `1` | 消息质量等级 |
| 主题前缀 | `MQTT_ALERT_TOPIC_PREFIX` | `video/alerts` | 主题前缀 |

---

### 2.5 目标跟踪服务（MVP-2 已实现）

对应设计文档 `event-judgment-algorithm-architecture.md` 中的「目标轨迹关联」。

#### 2.5.1 ByteTracker (`tracking_service.py`)

**文件**: `services/tracking_service.py`

- 基于 ByteTrack 论文的简化跟踪器，纯 Python 实现
- 按置信度将检测分为 high/low 两组
- 先用 high 检测与现有 tracks 进行 IOU 匹配
- 未匹配的 tracks 再与 low 检测匹配（拯救低置信度真实目标）
- 未匹配的 high 检测创建新 track
- 超过 `max_lost_frames` 的 tracks 移除
- 为每个检测目标分配稳定的 `track_id`，支持目标轨迹关联

---

### 2.6 WebSocket 实时推送（MVP-2 已实现）

对应设计文档 `project-integration-plan.md` 中的「实时通信」。

#### 2.6.1 预警 WebSocket (`/ws/alerts`)

**文件**: `api/alerts.py`

- `AlertBroadcaster` 维护 WebSocket 连接池
- 支持按事件类型、source_id 过滤订阅
- 心跳机制：前端每 30 秒发送 ping，后端回复 pong
- 预警事件通过 MQTT 发布的同时广播到所有 WebSocket 订阅者
- 消息格式：`{"type": "alert", "data": {...}}`

#### 2.6.2 摄像头 WebSocket (`/ws/camera`)

**文件**: `main.py` → `CameraService`

- 实时视频流传输（原始帧 + 标注帧双路）
- 支持动态切换模型、调整置信度/IOU 阈值
- 自动清理摄像头资源

---

### 2.7 LLM 大模型二次判断（MVP-3 已实现）

对应设计文档 `event-judgment-algorithm-architecture.md` 中的「AI增强层」和 `project-integration-plan.md` 中的「大模型二次判断架构」。

#### 2.7.1 多帧累积器 (`MultiFrameAccumulator`)

**文件**: `services/event/frame_accumulator.py`

- 累积同一目标在时间窗口内的候选事件
- 统计连续命中帧数、平均置信度、首次/末次出现时间
- LRU 淘汰机制：超出最大容量时淘汰最久未更新的条目
- 过期淘汰：超出时间窗口的条目自动清理
- 为 LLM 触发器提供累积统计数据

#### 2.7.2 LLM 触发器 (`LLMTrigger`)

**文件**: `services/event/llm_trigger.py`

- 基于累积统计决定是否触发 LLM 二次判断
- 触发条件：连续命中帧数 ≥ `min_consecutive_hits` 且平均置信度 ≥ `min_avg_confidence`
- 严重性旁路：`critical` 级别事件无需累积，立即触发 LLM
- 冷却机制：同一目标在冷却时间内不重复触发
- 输出 `TriggerDecision`，包含是否触发、累积帧列表、触发原因

#### 2.7.3 LLM 分析服务 (`LLMAnalysisService`)

**文件**: `services/llm_analysis_service.py`

- **Provider 抽象**：`BaseLLMProvider` 抽象基类，支持多种 LLM 后端
  - `MockLLMProvider`：离线测试用，返回模拟结果
  - `OpenAICompatibleProvider`：支持 OpenAI 兼容协议（GPT-4V/Qwen-VL/GLM-4V 等）
- 并发控制：`asyncio.Semaphore` 限制同时进行的 LLM 调用数
- 图像预处理：自动缩放到 `image_max_side` 以节省 token
- 结构化输出解析：从 LLM 响应中提取 confirmed/confidence/reasoning
- 调用统计：记录调用次数、成功/失败数、总延迟

#### 2.7.4 结果融合器 (`ResultFusion`)

**文件**: `services/result_fusion.py`

三种融合策略：

| 策略 | 说明 |
|------|------|
| `weighted` | 加权融合：YOLO 权重 × YOLO 置信度 + LLM 权重 × LLM 置信度 |
| `conservative` | 保守策略：LLM 明确否决时直接抑制预警 |
| `llm_priority` | LLM 优先：LLM 给出明确判定时以 LLM 为准 |

关键行为：
- LLM 不可用/未触发时，可配置是否回退到 YOLO 结果（`fallback_to_yolo`）
- LLM 明确否决时，可配置是否抑制预警（`suppress_on_llm_negative`）
- 高融合置信度时可自动提升严重性级别（`promote_severity_on_high_confidence`）

#### 2.7.5 LLM 成本追踪与熔断降级 (`LLMCostTracker`)

**文件**: `services/llm_cost_tracker.py`

- **成本追踪**：记录每次 LLM 调用的 token 用量、费用、延迟
- **日预算控制**：超过日预算自动拒绝调用
- **熔断降级**：
  - 状态机：CLOSED → OPEN → HALF_OPEN → CLOSED
  - 触发条件：最近 N 次调用错误率超过阈值
  - 冷却恢复：OPEN 状态持续 `cooldown_seconds` 后进入 HALF_OPEN，允许一次试探
  - 手动控制：支持紧急停用 / 重新启用 / 重置统计
- **定价表**：内置主流模型定价，支持自定义覆盖
- **统计接口**：提供日级统计、历史趋势、最近调用记录

#### 2.7.6 LLM 管理 API

**文件**: `api/llm.py`

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/llm/status` | 获取 LLM 运行状态（provider/模型/触发配置/融合配置/成本） |
| `GET` | `/api/llm/cost` | 获取当前成本统计 |
| `GET` | `/api/llm/cost/history` | 获取历史成本趋势（按天） |
| `GET` | `/api/llm/cost/records` | 获取最近调用记录 |
| `POST` | `/api/llm/disable` | 紧急停用 LLM |
| `POST` | `/api/llm/enable` | 重新启用 LLM |
| `POST` | `/api/llm/reset` | 重置成本统计与熔断状态 |

---

### 2.8 规则配置管理（MVP-3 已实现）

#### 2.8.1 规则管理 API

**文件**: `api/rules.py`

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/rules` | 获取所有规则列表 |
| `GET` | `/api/rules/{name}` | 获取单条规则详情 |
| `POST` | `/api/rules` | 新增规则（写入 custom.yaml） |
| `PUT` | `/api/rules/{name}` | 更新规则 |
| `DELETE` | `/api/rules/{name}` | 删除规则 |
| `POST` | `/api/rules/reload` | 热重载规则（从 YAML 重新加载） |
| `GET` | `/api/rules/_stats` | 获取规则统计信息 |

---

### 2.9 统一配置管理（MVP-1/2/3 已实现）

**文件**: `core/settings.py`

基于 `pydantic-settings` 的多环境配置管理，支持环境变量、`.env` 文件、默认值三级加载。

| 子配置 | 环境变量前缀 | 覆盖范围 |
|--------|-------------|---------|
| `APISettings` | `API_` | 服务端口、CORS |
| `DetectionSettings` | `DETECTION_` | 默认置信度、IOU、最低置信度 |
| `ActionDetectionSettings` | `ACTION_DETECTION_` | Docker 行为识别服务 |
| `EventEngineSettings` | `EVENT_` | 去重窗口、规则目录、最大事件数 |
| `RTSPSettings` | `RTSP_` | 最大流数、缓冲区、重连策略 |
| `MQTTSettings` | `MQTT_` | Broker 配置、QoS、主题 |
| `TrackingSettings` | `TRACKING_` | ByteTrack 参数 |
| `AggregatorSettings` | `AGGREGATOR_` | 空间合并、置信度融合 |
| `LLMSettings` | `LLM_` | Provider、模型、API Key、并发 |
| `LLMTriggerSettings` | `LLM_TRIGGER_` | 触发阈值、冷却、严重性旁路 |
| `FusionSettings` | `FUSION_` | 融合策略、权重、回退 |
| `LLMCostSettings` | `LLM_COST_` | 日预算、熔断阈值、冷却 |
| `LoggingSettings` | `LOG_` | 日志级别、格式 |
| `PathSettings` | `PATH_` | 静态资源、模型路径 |

---

## 3. 前端功能清单

### 3.1 页面结构

| 页面 | 路径 | 组件 | 功能 |
|------|------|------|------|
| 模型检测 | `/` | `Home.vue` + `ImageDetection.vue` + `VideoDetection.vue` | 图片/视频/摄像头实时检测 |
| 摄像头管理 | `/cameras` | `CameraManagement.vue` | RTSP 流增删改查、启停控制 |
| 规则配置 | `/rules` | `RuleConfiguration.vue` | 规则 CRUD + LLM 状态面板 |
| 预警列表 | `/alerts` | `AlertList.vue` | 实时预警展示、过滤、LLM 结果展示 |

### 3.2 全局功能

- **暗色主题 UI**：统一深色设计风格
- **可折叠侧边栏**：4 个导航菜单项
- **实时连接状态**：显示 WebSocket 连接状态（已连接/连接中/未连接）
- **预警铃铛**：顶部显示未读预警数量，点击跳转预警列表
- **全局预警弹窗**：`AlertNotification.vue` 收到新预警时弹出桌面通知
- **WebSocket 自动重连**：指数退避策略，最多重试 10 次
- **心跳保活**：每 30 秒发送 ping

### 3.3 摄像头管理页面功能

- 统计卡片：摄像头总数、运行中、重连中、故障
- 搜索过滤：按 ID/URL 搜索、按状态过滤
- 摄像头操作：启动/停止/配置/移除
- 批量操作：全部启动/全部停止
- 添加/编辑弹窗：配置 RTSP URL、检测模型、置信度/IOU 阈值、帧采样间隔
- 自动刷新：每 5 秒轮询状态

### 3.4 规则配置页面功能

- **LLM 状态面板**：
  - Provider/模型/融合策略/触发阈值展示
  - 今日调用次数/成功/失败/费用/预算使用率
  - 最近错误率/熔断状态
  - 紧急停用/重新启用/重置统计操作
- **规则列表**：
  - 按规则名/描述搜索、按事件类型过滤
  - 规则卡片：严重级别标签、事件类型、启停开关、编辑/删除
  - 规则元数据：最低置信度、最小边界框面积、限定摄像头、必备标签
- **新增/编辑规则弹窗**：
  - 规则名称、事件类型、严重级别
  - 最低置信度滑块、最小边界框面积
  - 限定摄像头 ID（多选）、必备标签（多选）
  - 描述、启用开关

### 3.5 预警列表页面功能

- 统计卡片：预警总数、未读、严重预警、订阅状态
- 过滤工具栏：按严重级别/事件类型/摄像头 ID 过滤
- 预警卡片：
  - 严重性色条（红/橙/蓝/灰/绿）
  - 未读标记（绿色圆点）
  - 事件类型、置信度、触发次数、规则名称
  - 检测标签（含 track_id）
  - **LLM 二次判断结果**：LLM 确认/否决标签、LLM 置信度、推理摘要
- 操作：全部标为已读、清空记录、单条删除

---

## 4. 完整 API 接口一览

### 4.1 检测接口

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/detect/image` | 图片检测（支持所有模型） |
| `POST` | `/api/detect/video` | 视频检测（仅 YOLO 模型，主要面向打架斗殴） |
| `GET` | `/api/algorithms/config` | 获取算法配置选项 |

### 4.2 模型管理

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/models` | 获取可用模型列表 |
| `GET` | `/api/models/{model_id}` | 获取单个模型信息 |
| `POST` | `/api/models/{model_id}/load` | 加载指定模型 |

### 4.3 RTSP 流管理

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/rtsp/streams` | 获取所有流状态 |
| `GET` | `/api/rtsp/streams/{stream_id}` | 获取单路流详情 |
| `POST` | `/api/rtsp/streams` | 添加新摄像头流 |
| `DELETE` | `/api/rtsp/streams/{stream_id}` | 移除摄像头流 |
| `POST` | `/api/rtsp/streams/{stream_id}/start` | 启动指定流 |
| `POST` | `/api/rtsp/streams/{stream_id}/stop` | 停止指定流 |
| `PUT` | `/api/rtsp/streams/{stream_id}/config` | 更新流检测配置 |
| `POST` | `/api/rtsp/start-all` | 启动全部流 |
| `POST` | `/api/rtsp/stop-all` | 停止全部流 |
| `GET` | `/api/rtsp/health` | 健康检查 |

### 4.4 规则配置

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/rules` | 获取所有规则 |
| `GET` | `/api/rules/{name}` | 获取单条规则 |
| `POST` | `/api/rules` | 新增规则 |
| `PUT` | `/api/rules/{name}` | 更新规则 |
| `DELETE` | `/api/rules/{name}` | 删除规则 |
| `POST` | `/api/rules/reload` | 热重载规则 |
| `GET` | `/api/rules/_stats` | 规则统计 |

### 4.5 LLM 管理

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/llm/status` | LLM 运行状态 |
| `GET` | `/api/llm/cost` | 当前成本统计 |
| `GET` | `/api/llm/cost/history` | 历史成本趋势 |
| `GET` | `/api/llm/cost/records` | 最近调用记录 |
| `POST` | `/api/llm/disable` | 紧急停用 LLM |
| `POST` | `/api/llm/enable` | 重新启用 LLM |
| `POST` | `/api/llm/reset` | 重置统计与熔断 |

### 4.6 WebSocket

| 路径 | 说明 |
|------|------|
| `/ws/camera` | 摄像头实时视频流 |
| `/ws/alerts` | 预警事件实时推送（支持过滤订阅） |

### 4.7 系统

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/` | 服务信息 |
| `GET` | `/api/health` | 健康检查 |

---

## 5. 数据流全景

### 5.1 实时检测管道（RTSP → 预警）

```
RTSP 摄像头
    │
    ▼
RTSPService (解码线程)
    │
    ▼
FrameBuffer (环形缓冲区)
    │
    ▼
StreamManager (检测调度)
    │
    ├──▶ ModelService (YOLO/Paddle 推理)
    │        │
    │        ▼
    │    DetectionAdapter (格式统一)
    │        │
    │        ▼
    │    ByteTracker (目标跟踪, 分配 track_id)
    │
    ▼
DetectionResult (统一检测结果)
    │
    ▼
EventDecisionEngine (置信度过滤 + 类型映射)
    │
    ▼
CandidateEvent[]
    │
    ├──▶ AlertRuleEngine (规则匹配)
    │        │
    │        ▼
    │    AlertEvent[] (规则过滤后)
    │
    ├──▶ MultiFrameAccumulator (多帧累积)
    │        │
    │        ▼
    │    LLMTrigger (触发判定)
    │        │
    │        ▼ (触发时)
    │    LLMAnalysisService (大模型分析)
    │        │
    │        ▼
    │    ResultFusion (YOLO + LLM 融合)
    │        │
    │        ▼
    │    LLMCostTracker (成本追踪 + 熔断)
    │
    ▼
EventAggregator (去重 + 空间合并 + 置信度融合)
    │
    ▼
AlertEvent (最终预警)
    │
    ├──▶ AlertPublisher → MQTT (外部系统)
    ├──▶ AlertBroadcaster → WebSocket (前端实时推送)
    └──▶ 前端 AlertList / 桌面通知
```

### 5.2 图片/视频检测管道（上传 → 结果）

```
用户上传图片/视频
    │
    ▼
POST /api/detect/image 或 /api/detect/video
    │
    ▼
DetectionService
    │
    ├──▶ ModelService (推理)
    │        │
    │        ▼
    │    检测结果 + 标注图/视频
    │
    ├──▶ 事件管道 (同上，但仅图片检测触发)
    │
    ▼
返回检测结果 (含标注图/视频 URL/关键帧)
```

---

## 6. 测试覆盖

项目包含完整的单元测试和集成测试：

### 6.1 单元测试

| 测试文件 | 覆盖模块 |
|----------|---------|
| `test_decision_engine.py` | 事件决策引擎 |
| `test_rule_engine.py` | 预警规则引擎 |
| `test_aggregator.py` / `test_aggregator_v2.py` | 事件聚合器 |
| `test_event_schemas.py` | 事件数据模型 |
| `test_detection_adapter.py` | 检测适配器 |
| `test_frame_accumulator.py` | 多帧累积器 |
| `test_llm_trigger.py` | LLM 触发器 |
| `test_llm_analysis_service.py` | LLM 分析服务 |
| `test_llm_cost_tracker.py` | LLM 成本追踪 |
| `test_result_fusion.py` | 结果融合器 |
| `test_rtsp_service.py` | RTSP 流服务 |
| `test_stream_manager.py` | 多路流管理器 |
| `test_tracking_service.py` | 目标跟踪 |
| `test_mqtt_service.py` | MQTT 服务 |
| `test_alert_publisher.py` | 预警发布器 |
| `test_frame_buffer.py` | 帧缓冲区 |
| `test_settings.py` | 配置管理 |

### 6.2 集成测试

| 测试文件 | 覆盖场景 |
|----------|---------|
| `test_detect_image_integration.py` | 图片检测端到端 |
| `test_detection_service_pipeline.py` | 检测服务管道 |
| `test_event_pipeline.py` | 事件管道端到端 |

---

## 7. 设计文档对照：已实现 vs 待实现

### 7.1 `event-judgment-algorithm-architecture.md` 对照

| 设计模块 | 设计内容 | 实现状态 | 说明 |
|----------|---------|---------|------|
| 事件决策引擎 | 置信度评估、场景识别、初步筛选 | ✅ 已实现 | 置信度过滤 + 类型映射，场景识别暂未实现 |
| 预警规则引擎 | 规则匹配、时间窗口、区域规则 | ✅ 已实现 | 置信度/面积/来源/标签规则已实现，时间窗口规则暂未实现 |
| 事件聚合器 | 去重合并、时间窗口、事件关联 | ✅ 已实现 | 时间窗口去重 + 空间合并 + 置信度融合 |
| 大模型触发器 | 智能决策、优先级排序、并发控制 | ✅ 已实现 | 多帧累积 + 冷却 + 严重性旁路 |
| LLM 视觉分析 | 图像理解、场景分析、推理验证 | ✅ 已实现 | OpenAI 兼容协议 + Mock Provider |
| 结果融合 | 置信融合、决策输出 | ✅ 已实现 | weighted/conservative/llm_priority 三策略 |
| 严重性评估器 | 风险等级、优先级计算 | ⚠️ 部分实现 | 规则引擎指定严重性，动态评估暂未实现 |
| 事件格式化 | 标准格式、元数据填充 | ✅ 已实现 | AlertEvent 统一格式 |
| MQTT 发布 | 消息发布、QoS 管理 | ✅ 已实现 | AlertPublisher + MQTTService |

### 7.2 `project-integration-plan.md` 对照

| 设计模块 | 设计内容 | 实现状态 | 说明 |
|----------|---------|---------|------|
| RTSP 流接入 | 解码、缓冲、重连 | ✅ 已实现 | RTSPService + FrameBuffer + 指数退避重连 |
| 多路流管理 | 调度、状态监控 | ✅ 已实现 | StreamManager + REST API |
| MQTT 预警系统 | 消息发布、QoS、主题设计 | ✅ 已实现 | MQTTService + AlertPublisher |
| AI 模型扩展 | 车辆/打架检测 | ✅ 已实现 | fight_detection + vehicle_detection_paddle |
| 大模型二次判断 | 多模型策略、Prompt 设计 | ✅ 已实现 | Provider 抽象 + 结构化输出解析 |
| 触发条件 | 置信度区间、去重窗口、并发限制 | ✅ 已实现 | LLMTrigger + MultiFrameAccumulator |
| 成本控制 | 日预算、熔断降级 | ✅ 已实现 | LLMCostTracker (CLOSED/OPEN/HALF_OPEN) |
| WebSocket 实时推送 | 预警订阅、过滤 | ✅ 已实现 | AlertBroadcaster + 前端 WebSocket 客户端 |
| 消息持久化 | 存储与消费确认 | ❌ 未实现 | 当前仅内存存储，未做持久化 |
| 人脸识别/属性分析 | InsightFace / PaddleFace | ❌ 未实现 | — |
| 越界/入侵检测 | 虚拟围栏算法 | ❌ 未实现 | — |
| 异常行为检测 | 自定义行为分析 | ⚠️ 部分实现 | 已有静止/徘徊检测，通用异常行为未实现 |

---

## 8. 项目文件结构

```
jc-video-recognize/
├── apps/
│   ├── web/                              # 前端 (Vue 3 + Vite 5)
│   │   └── src/
│   │       ├── api/detection.js          # API 请求封装 (检测/摄像头/规则/LLM)
│   │       ├── components/
│   │       │   ├── AlertNotification.vue # 全局预警弹窗
│   │       │   ├── AlgorithmConfig.vue   # 行为分析算法配置
│   │       │   ├── DetectionConfig.vue   # 检测参数配置
│   │       │   ├── ImageDetection.vue    # 图片检测模块
│   │       │   └── VideoDetection.vue    # 视频/摄像头检测模块
│   │       ├── layouts/MainLayout.vue    # 主布局 (侧边栏+顶栏+预警铃铛)
│   │       ├── router/index.js           # 路由 (4 个页面)
│   │       ├── services/mqtt.client.js   # WebSocket 预警客户端
│   │       ├── stores/alertStore.js      # Pinia 预警状态管理
│   │       └── views/
│   │           ├── Home.vue              # 模型检测首页
│   │           ├── CameraManagement.vue  # 摄像头管理
│   │           ├── RuleConfiguration.vue # 规则配置 + LLM 面板
│   │           └── AlertList.vue         # 预警列表
│   └── server/                           # 后端 (FastAPI)
│       ├── main.py                       # 服务入口 + 生命周期管理
│       ├── api/
│       │   ├── detection.py              # 检测 API
│       │   ├── models.py                 # 模型管理 API
│       │   ├── rtsp.py                   # RTSP 流管理 API
│       │   ├── alerts.py                 # 预警 WebSocket API
│       │   ├── rules.py                  # 规则配置 API
│       │   └── llm.py                    # LLM 管理 API
│       ├── config/rules/                 # 规则 YAML 配置
│       │   ├── fire.yaml
│       │   ├── smoking.yaml
│       │   ├── loitering.yaml
│       │   ├── fight.yaml
│       │   └── vehicle.yaml
│       ├── core/settings.py              # 统一配置管理 (14 个子配置)
│       ├── models/
│       │   ├── event_schemas.py          # 统一事件数据契约
│       │   └── schemas.py               # 检测请求/响应模型
│       ├── services/
│       │   ├── detection_service.py      # 检测核心 (管道编排)
│       │   ├── model_service.py          # 模型加载与管理
│       │   ├── rtsp_service.py           # RTSP 流接入
│       │   ├── stream_manager.py         # 多路流调度
│       │   ├── frame_buffer.py           # 帧缓冲区
│       │   ├── mqtt_service.py           # MQTT 客户端
│       │   ├── alert_publisher.py        # 预警发布器
│       │   ├── tracking_service.py       # ByteTrack 目标跟踪
│       │   ├── llm_analysis_service.py   # LLM 分析服务
│       │   ├── llm_cost_tracker.py       # LLM 成本追踪 + 熔断
│       │   ├── result_fusion.py          # 结果融合器
│       │   ├── loitering_service.py      # 徘徊检测服务
│       │   ├── camera_service.py         # 摄像头 WebSocket 服务
│       │   ├── action_detection_service.py   # Docker 行为识别适配器
│       │   ├── paddle_detection_service.py   # PaddlePaddle 抽烟检测适配器
│       │   ├── vehicle_detection_service.py  # 车辆/违停检测适配器
│       │   ├── adapters/detection_adapter.py # 检测结果格式统一适配器
│       │   └── event/
│       │       ├── decision_engine.py    # 事件决策引擎
│       │       ├── rule_engine.py        # 预警规则引擎
│       │       ├── aggregator.py         # 事件聚合器
│       │       ├── frame_accumulator.py  # 多帧累积器
│       │       └── llm_trigger.py        # LLM 触发器
│       └── tests/                        # 测试 (17 单元 + 3 集成)
├── models/                               # AI 模型文件
│   ├── fire_detection/                   # YOLOv10 火灾检测
│   ├── helmet_detection/                 # YOLOv8 安全帽检测
│   ├── crowd_detection/                  # YOLOv8 人群检测
│   ├── smoking_detection/                # YOLOv8 抽烟检测
│   ├── smoking_detection_paddle/         # PaddlePaddle 抽烟检测
│   ├── loitering_detection/              # YOLOv8 徒步检测
│   ├── fight_detection/                  # YOLOv8 打架斗殴检测
│   └── vehicle_detection_paddle/         # PaddlePaddle 车辆检测
├── docs/                                 # 项目文档
└── docker/                               # Docker 部署配置
```

---

## 9. 待完善功能

基于两份设计文档的对照，以下功能尚未实现：

| 优先级 | 功能 | 来源文档 | 说明 |
|--------|------|---------|------|
| 高 | 预警事件持久化存储 | project-integration-plan | 当前仅内存存储，重启后丢失 |
| 高 | 时间窗口规则 | event-judgment-algorithm | 规则引擎暂不支持工作时间/非工作时间过滤 |
| 中 | 场景识别 | event-judgment-algorithm | 决策引擎暂未实现室内/室外/禁区场景分类 |
| 中 | 动态严重性评估 | event-judgment-algorithm | 当前严重性由规则静态指定，未实现动态计算 |
| 中 | 越界/入侵检测 | project-integration-plan | 虚拟围栏算法未实现 |
| 中 | 人脸识别/属性分析 | project-integration-plan | InsightFace / PaddleFace 未集成 |
| 低 | 区域规则 | event-judgment-algorithm | 规则引擎暂不支持区域（禁区/普通区域）过滤 |
| 低 | 组合规则 | event-judgment-algorithm | 多条件组合规则未实现 |
| 低 | 消息消费确认机制 | project-integration-plan | MQTT 消息持久化与消费确认未实现 |
| 低 | 预警消息管理后台 | project-integration-plan | 消息查询与统计分析页面未实现 |