docs: 加了两个计划书，后续做实现

docs/project-integration-plan.md

@@ -0,0 +1,522 @@
+# 项目整合计划书：视频检测平台功能扩展
+
+## 文档信息
+
+- **项目名称**: jc-video-recognize 视频模型检测平台
+- **模块路径**: `/Users/wwh/project/jc-video-recognize/apps/server`
+- **制定日期**: 2026-06-02
+- **文档版本**: v1.0
+
+---
+
+## 目录
+
+1. [项目概述](#1-项目概述)
+2. [视频流接入方案](#2-视频流接入方案)
+3. [MQTT预警事件消息系统](#3-mqtt预警事件消息系统)
+4. [AI分析辅助功能集成](#4-ai分析辅助功能集成)
+5. [大模型二次判断架构](#5-大模型二次判断架构)
+6. [项目管理与实施计划](#6-项目管理与实施计划)
+7. [交付成果清单](#7-交付成果清单)
+
+---
+
+## 1. 项目概述
+
+### 1.1 现有系统架构
+
+当前系统是一个基于 **FastAPI + YOLO/PaddlePaddle** 的实时视频检测平台：
+
+| 层级 | 技术栈 | 说明 |
+|------|--------|------|
+| **前端** | Vue 3 + Vite + Element Plus | 用户界面与可视化 |
+| **后端** | FastAPI + Uvicorn | REST API + WebSocket |
+| **AI推理** | YOLOv8/v10 + PaddlePaddle | 多模型检测服务 |
+| **实时通信** | WebSocket | 摄像头视频流传输 |
+| **检测模型** | 火灾/安全帽/人群/抽烟/徘徊检测 | 已集成的AI能力 |
+
+### 1.2 核心需求确认
+
+| 需求 | 确认内容 |
+|------|----------|
+| **视频流接入** | 局域网环境，RTSP协议直接接入 |
+| **消息系统** | 复用现有MQTT Broker |
+| **AI扩展** | 大模型（GPT-4V/Claude等）进行二次深度判断 |
+
+---
+
+## 2. 视频流接入方案
+
+### 2.1 系统架构图
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        局域网环境                                │
+│  ┌──────────┐    ┌──────────┐    ┌──────────┐                  │
+│  │ 摄像头-1  │    │ 摄像头-2  │    │ 摄像头-N  │                  │
+│  │ RTSP流   │    │ RTSP流   │    │ RTSP流   │                  │
+│  └────┬─────┘    └────┬─────┘    └────┬─────┘                  │
+│       │               │               │                         │
+│       └───────────────┼───────────────┘                         │
+│                       ▼                                         │
+│            ┌─────────────────────┐                              │
+│            │   Stream Manager    │                              │
+│            │  (多路流管理调度)    │                              │
+│            └──────────┬──────────┘                              │
+│                       │                                         │
+│       ┌───────────────┼───────────────┐                        │
+│       ▼               ▼               ▼                        │
+│  ┌──────────┐   ┌──────────┐   ┌──────────┐                    │
+│  │ 解码线程-1 │   │ 解码线程-2 │   │ 解码线程-N │                    │
+│  │(FFmpeg/CV2)│  │(FFmpeg/CV2)│  │(FFmpeg/CV2)│                    │
+│  └────┬─────┘   └────┬─────┘   └────┬─────┘                    │
+│       │              │              │                           │
+│       └──────────────┼──────────────┘                           │
+│                      ▼                                          │
+│           ┌──────────────────┐                                 │
+│           │   AI检测引擎      │                                 │
+│           │ YOLO/Paddle+大模型 │                                 │
+│           └────────┬─────────┘                                 │
+│                    │                                            │
+│                    ▼                                            │
+│           ┌──────────────────┐                                 │
+│           │   MQTT Publisher  │                                │
+│           │   预警事件发布     │                                │
+│           └──────────────────┘                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 2.2 技术方案选型
+
+| 组件 | 技术选型 | 说明 |
+|------|----------|------|
+| **RTSP客户端** | `opencv-python` + `ffmpeg` | 支持硬件加速解码 |
+| **流管理** | 异步线程池 | 每路流独立解码线程 |
+| **帧缓冲** | 环形缓冲区 (Ring Buffer) | 防止内存溢出，支持丢帧策略 |
+| **解码优化** | FFmpeg硬解码 (可选) | NVIDIA/Intel GPU加速 |
+
+### 2.3 关键设计决策
+
+**1. 解码方案选择**
+- **方案A**: OpenCV VideoCapture (简单，已验证)
+- **方案B**: FFmpeg子进程 (更稳定，支持更多格式)
+- **推荐**: 方案A为主，方案B作为备选
+
+**2. 多路并发策略**
+
+```python
+# 每路摄像头配置
+{
+    "camera_id": "cam_001",
+    "rtsp_url": "rtsp://192.168.1.100:554/stream",
+    "decode_fps": 5,        # 解码帧率（降低AI负载）
+    "buffer_size": 30,      # 缓冲区大小
+    "reconnect_interval": 5 # 断线重连间隔(秒)
+}
+```
+
+**3. 性能预估**
+
+| 指标 | 目标值 | 说明 |
+|------|--------|------|
+| 单路延迟 | < 300ms | 解码+AI推理 |
+| 并发路数 | 16路+ | CPU推理 |
+| CPU占用 | < 70% | 16路@720p |
+
+### 2.4 开发与集成任务
+
+- [ ] 设计视频流接收、解码、存储及转发的系统架构
+- [ ] 开发RTSP协议解析模块
+- [ ] 实现视频流数据处理管道，确保低延迟与高稳定性
+- [ ] 编写视频流接入模块的单元测试与集成测试用例
+
+### 2.5 质量保障与验收标准
+
+| 指标 | 目标值 |
+|------|--------|
+| 视频流传输延迟 | < 500ms |
+| 异常恢复时间 | < 5秒 |
+| 并发视频流支持 | ≥ 16路 |
+| 系统可用性 | 7×24小时 |
+
+---
+
+## 3. MQTT预警事件消息系统
+
+### 3.1 系统架构设计
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│  AI检测服务  │────▶│  事件处理器  │────▶│ MQTT Broker │
+└─────────────┘     └─────────────┘     └──────┬──────┘
+                                               │
+                        ┌──────────────────────┼──────────┐
+                        ▼                      ▼          ▼
+                   ┌─────────┐           ┌─────────┐  ┌─────────┐
+                   │ Web前端  │           │ 移动端   │  │ 第三方  │
+                   └─────────┘           └─────────┘  └─────────┘
+```
+
+### 3.2 消息主题设计
+
+```
+# 主题层级结构
+jc-video/
+├── alerts/
+│   ├── fire/              # 火灾预警
+│   │   └── {camera_id}    # 具体摄像头
+│   ├── smoking/           # 抽烟预警
+│   ├── loitering/         # 徘徊预警
+│   └── illegal_parking/   # 违停预警
+├── status/
+│   ├── camera/            # 摄像头状态
+│   └── system/            # 系统状态
+└── commands/
+    └── camera/            # 摄像头控制指令
+```
+
+### 3.3 预警事件消息格式
+
+```json
+{
+  "event_id": "evt_550e8400-e29b-41d4-a716-446655440000",
+  "event_type": "fire",
+  "event_level": "critical",
+  "timestamp": "2026-06-02T10:30:00.123Z",
+  "camera_id": "cam_001",
+  "camera_name": "大厅摄像头",
+  "location": {
+    "building": "A栋",
+    "floor": "1F",
+    "area": "大厅"
+  },
+  "detection": {
+    "class": "Fire",
+    "confidence": 0.95,
+    "bbox": [100, 200, 150, 180],
+    "snapshot_url": "/static/alerts/evt_550e8400.jpg"
+  },
+  "ai_analysis": {
+    "llm_verified": true,
+    "llm_confidence": 0.92,
+    "llm_reasoning": "检测到明显火焰特征，伴随烟雾..."
+  },
+  "metadata": {
+    "model_id": "fire_detection",
+    "processing_time_ms": 150
+  }
+}
+```
+
+### 3.4 QoS策略
+
+| 消息类型 | QoS等级 | 说明 |
+|----------|---------|------|
+| 预警事件 | QoS 2 | 确保只送达一次 |
+| 状态上报 | QoS 1 | 至少送达一次 |
+| 控制指令 | QoS 1 | 至少送达一次 |
+
+### 3.5 开发与集成任务
+
+- [ ] 设计预警事件消息的结构格式与传输协议
+- [ ] 配置MQTT服务器安全认证机制
+- [ ] 开发MQTT客户端模块，实现消息发布与订阅功能
+- [ ] 设计预警事件触发机制与消息路由策略
+- [ ] 实现消息持久化存储与消费确认机制
+- [ ] 开发预警消息管理后台，支持消息查询与统计分析
+
+### 3.6 质量保障与验收标准
+
+| 指标 | 目标值 |
+|------|--------|
+| 消息传输成功率 | 100% |
+| 消息丢失率 | 0 |
+| 预警消息延迟 | < 1秒 |
+| 并发客户端连接 | ≥ 100个 |
+
+---
+
+## 4. AI分析辅助功能集成
+
+### 4.1 当前已支持的检测能力
+
+- ✅ 火灾检测 (YOLOv10)
+- ✅ 安全帽检测 (YOLOv8)
+- ✅ 人群检测 (YOLOv8)
+- ✅ 抽烟检测 (YOLOv8 + PaddlePaddle)
+- ✅ 徘徊检测 (YOLOv8 + 行为分析)
+
+### 4.2 建议扩展的AI能力
+
+| 功能 | 技术方案 | 优先级 |
+|------|----------|--------|
+| 人脸识别/属性分析 | InsightFace / PaddleFace | 中 |
+| 车辆识别/车牌检测 | PP-Vehicle (已有基础) | 高 |
+| 异常行为检测 | 自定义行为分析算法 | 中 |
+| 越界/入侵检测 | 虚拟围栏算法 | 高 |
+
+### 4.3 开发与集成任务
+
+- [ ] 根据业务需求评估并选择合适的AI模型
+- [ ] 搭建AI模型训练与推理环境，配置必要的GPU资源
+- [ ] 制定AI模型性能评估指标与优化策略
+- [ ] 设计AI分析接口，实现与视频流数据的对接
+- [ ] 开发AI模型推理服务，支持实时分析与批量处理两种模式
+- [ ] 实现AI分析结果与预警系统的联动机制
+- [ ] 开发AI模型效果监控与反馈优化模块
+
+### 4.4 质量保障与验收标准
+
+| 指标 | 目标值 |
+|------|--------|
+| AI分析准确率 | ≥ 90% |
+| 单帧视频分析处理时间 | < 200ms |
+| 模型更新支持 | 定期更新与持续优化 |
+
+---
+
+## 5. 大模型二次判断架构
+
+### 5.1 架构设计
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      AI分析流程                              │
+│                                                              │
+│  视频帧 → YOLO初检 → 触发条件? ──否──→ 丢弃                   │
+│                      │                                       │
+│                     是                                       │
+│                      ▼                                       │
+│           ┌─────────────────┐                               │
+│           │  截取ROI区域     │                               │
+│           │ (目标区域放大)   │                               │
+│           └────────┬────────┘                               │
+│                    │                                         │
+│                    ▼                                         │
+│           ┌─────────────────┐                               │
+│           │  大模型视觉分析  │                               │
+│           │ (GPT-4V/Claude) │                               │
+│           │                 │                               │
+│           │ Prompt:         │                               │
+│           │ "分析图片中是否 │                               │
+│           │  存在火灾/抽烟   │                               │
+│           │  等危险行为"     │                               │
+│           └────────┬────────┘                               │
+│                    │                                         │
+│                    ▼                                         │
+│           ┌─────────────────┐                               │
+│           │  结果融合决策    │                               │
+│           │                 │                               │
+│           │  YOLO置信度 ×   │                               │
+│           │  LLM置信度 =    │                               │
+│           │  最终预警等级    │                               │
+│           └────────┬────────┘                               │
+│                    │                                         │
+│                    ▼                                         │
+│           ┌─────────────────┐                               │
+│           │  生成预警事件    │                               │
+│           │  发布MQTT       │                               │
+│           └─────────────────┘                               │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 5.2 大模型选型对比
+
+| 模型 | 优点 | 缺点 | 成本 | 适用场景 |
+|------|------|------|------|----------|
+| **GPT-4o** | 视觉能力强，响应快 | 需翻墙，成本较高 | $$$ | 高精度场景 |
+| **Claude 3.5 Sonnet** | 推理能力强，中文好 | 国内访问不稳定 | $$ | 复杂场景分析 |
+| **Qwen-VL (通义千问)** | 国内可用，成本低 | 精度略低 | $ | 成本敏感场景 |
+| **GLM-4V (智谱)** | 国内可用，中文优化 | 生态较小 | $ | 本地化部署 |
+
+### 5.3 推荐方案：多模型策略
+
+```python
+# 大模型配置
+LLM_CONFIGS = {
+    "primary": {
+        "provider": "openai",
+        "model": "gpt-4o",
+        "api_key_env": "OPENAI_API_KEY",
+        "max_tokens": 500,
+        "temperature": 0.3
+    },
+    "fallback": {
+        "provider": "dashscope",  # 阿里通义千问
+        "model": "qwen-vl-max",
+        "api_key_env": "DASHSCOPE_API_KEY",
+        "max_tokens": 500,
+        "temperature": 0.3
+    }
+}
+```
+
+### 5.4 Prompt设计模板
+
+#### 火灾检测Prompt
+
+```
+你是一位专业的消防安全分析师。请仔细分析这张图片，判断是否存在以下情况：
+
+1. **真实火焰** - 明火、燃烧现象
+2. **烟雾** - 可见烟雾
+3. **误报可能** - 红色物体、灯光、反光等非火灾情况
+
+请按以下格式回复：
+```json
+{
+  "has_fire": true/false,
+  "has_smoke": true/false,
+  "confidence": 0-1,
+  "reasoning": "详细分析说明",
+  "risk_level": "low/medium/high/critical"
+}
+```
+
+注意：必须严格区分真实火灾和视觉相似物（如红色衣服、灯光）。
+
+
+
+
+### 5.5 触发大模型的条件
+
+```python
+# 触发策略配置
+TRIGGER_CONFIG = {
+    # 条件1: YOLO置信度在模糊区间
+    "confidence_range": [0.5, 0.85],
+    
+    # 条件2: 特定场景强制触发
+    "force_trigger_scenes": ["indoor_no_smoking_area"],
+    
+    # 条件3: 时间窗口去重（避免重复调用）
+    "dedup_window_seconds": 30,
+    
+    # 条件4: 并发限制
+    "max_concurrent_llm_calls": 5
+}
+```
+
+---
+
+## 6. 项目管理与实施计划
+
+### 6.1 项目时间轴
+
+| 阶段 | 时间范围 | 主要任务 | 交付物 |
+|------|----------|----------|--------|
+| **阶段一** | 第1周 | 需求分析与技术方案确定 | 技术方案文档 |
+| **阶段二** | 第2-3周 | RTSP接入开发 | RTSP服务模块 |
+| **阶段三** | 第4周 | MQTT预警系统开发 | MQTT服务模块 |
+| **阶段四** | 第5-6周 | 大模型集成 | AI分析服务 |
+| **阶段五** | 第7周 | 系统集成与联调 | 集成测试报告 |
+| **阶段六** | 第8周 | 系统测试与性能优化 | 性能测试报告 |
+| **阶段七** | 第9周 | 部署上线与运维支持 | 生产版本 |
+
+### 6.2 资源需求
+
+#### 6.2.1 人员配置
+
+| 角色 | 人数 | 职责 |
+|------|------|------|
+| 后端开发 | 2人 | FastAPI服务、MQTT、视频流 |
+| AI算法 | 1人 | 模型优化、大模型集成 |
+| 测试 | 1人 | 功能测试、性能测试 |
+
+#### 6.2.2 硬件资源
+
+| 资源 | 数量 | 用途 |
+|------|------|------|
+| 服务器 | 2台 | 主备部署 |
+| GPU (可选) | 1块 | AI推理加速 |
+| 摄像头 | 若干 | 测试验证 |
+
+#### 6.2.3 软件资源
+
+- 开发工具：VS Code、PyCharm
+- 测试环境：Docker、Postman
+- 部署平台：Linux服务器
+
+### 6.3 风险管理
+
+| 风险点 | 影响 | 应对策略 |
+|--------|------|----------|
+| RTSP延迟过高 | 高 | 采用硬件解码、优化缓冲策略 |
+| MQTT消息丢失 | 高 | 实现QoS等级、消息持久化 |
+| AI模型性能不足 | 中 | 模型量化、批处理优化 |
+| 大模型API不稳定 | 中 | 多模型降级策略、本地缓存 |
+| 并发处理能力 | 中 | 异步架构、服务拆分 |
+
+---
+
+## 7. 交付成果清单
+
+### 7.1 文档交付物
+
+- [ ] 系统设计文档与技术方案说明书
+- [ ] 用户操作手册与开发文档
+- [ ] 系统部署包与环境配置说明
+
+### 7.2 代码交付物
+
+| 文件路径 | 功能 |
+|----------|------|
+| `services/rtsp_service.py` | RTSP流接收与解码 |
+| `services/stream_manager.py` | 多路流管理调度 |
+| `services/mqtt_service.py` | MQTT客户端连接 |
+| `services/alert_service.py` | 预警事件生成 |
+| `services/llm_analysis_service.py` | 大模型视觉分析 |
+| `models/stream_schemas.py` | 流数据模型 |
+| `models/alert_schemas.py` | 预警数据模型 |
+| `api/streaming.py` | 流管理API |
+| `api/alerts.py` | 预警查询API |
+
+### 7.3 测试交付物
+
+- [ ] 测试报告与性能评估报告
+- [ ] 单元测试用例与覆盖率报告
+- [ ] 集成测试报告
+
+### 7.4 部署交付物
+
+- [ ] 源代码与构建部署脚本
+- [ ] Docker镜像与编排文件
+- [ ] 环境变量配置模板
+
+---
+
+## 附录
+
+### A. 技术依赖清单
+
+```
+# 新增Python依赖
+paho-mqtt>=1.6.0          # MQTT客户端
+openai>=1.0.0             # OpenAI API
+httpx>=0.24.0             # 异步HTTP客户端
+aioredis>=2.0.0           # Redis缓存（可选）
+pydantic-settings>=2.0.0  # 配置管理
+```
+
+### B. 环境变量配置
+
+```bash
+# MQTT配置
+MQTT_BROKER_HOST=localhost
+MQTT_BROKER_PORT=1883
+MQTT_USERNAME=admin
+MQTT_PASSWORD=password
+
+# 大模型API配置
+OPENAI_API_KEY=sk-xxx
+DASHSCOPE_API_KEY=sk-xxx
+
+# RTSP配置
+RTSP_DEFAULT_FPS=5
+RTSP_BUFFER_SIZE=30
+RTSP_RECONNECT_INTERVAL=5
+```
+
+---
+
+*文档结束*