border_Inspection/server/README_API.md

# 边检CV算法管理系统 API 文档

## 概述

本系统提供了完整的边检计算机视觉算法管理API，包括设备管理、算法管理、事件管理、监控管理、告警管理等功能。

## 快速开始

### 1. 启动服务

```bash
# 安装依赖
pip install -r requirements.txt

# 启动服务
python app.py
```

服务将在 `http://localhost:8000` 启动

### 2. API文档

访问 `http://localhost:8000/docs` 查看完整的API文档

## 核心功能模块

### 1. 仪表板统计 (`/api/dashboard`)

#### 获取KPI指标
```http
GET /api/dashboard/kpi
```

#### 获取告警趋势
```http
GET /api/dashboard/alarm-trend?days=7
```

#### 获取摄像头统计
```http
GET /api/dashboard/camera-stats
```

#### 获取算法统计
```http
GET /api/dashboard/algorithm-stats
```

#### 获取事件热点
```http
GET /api/dashboard/event-hotspots
```

### 2. 监控管理 (`/api/monitors`)

#### 获取监控列表
```http
GET /api/monitors?page=1&size=20&status=online&location=港口区
```

#### 获取监控详情
```http
GET /api/monitors/{monitor_id}
```

#### 获取监控视频流
```http
GET /api/monitors/{monitor_id}/stream
```

#### 获取检测数据
```http
GET /api/monitors/{monitor_id}/detections
```

### 3. 告警管理 (`/api/alarms`)

#### 获取告警列表
```http
GET /api/alarms?page=1&size=20&severity=high&status=pending
```

#### 获取告警详情
```http
GET /api/alarms/{alarm_id}
```

#### 处理告警
```http
PATCH /api/alarms/{alarm_id}/resolve
Content-Type: application/json

{
  "resolution_notes": "已确认船舶靠泊，无异常",
  "resolved_by": "operator1"
}
```

#### 获取告警统计
```http
GET /api/alarms/stats
```

### 4. 场景管理 (`/api/scenes`)

#### 获取场景列表
```http
GET /api/scenes
```

#### 获取场景详情
```http
GET /api/scenes/{scene_id}
```

#### 创建场景
```http
POST /api/scenes
Content-Type: application/json

{
  "name": "新场景",
  "description": "场景描述"
}
```

### 5. 文件上传 (`/api/upload`)

#### 上传视频
```http
POST /api/upload/video
Content-Type: multipart/form-data

file: [视频文件]
device_id: 1
description: "视频描述"
```

#### 上传图片
```http
POST /api/upload/image
Content-Type: multipart/form-data

file: [图片文件]
event_id: 1
description: "图片描述"
```

#### 获取文件列表
```http
GET /api/upload/files?file_type=video&page=1&size=20
```

### 6. 用户认证 (`/api/auth`)

#### 用户登录
```http
POST /api/auth/login
Content-Type: application/x-www-form-urlencoded

username=admin&password=admin123
```

#### 获取用户信息
```http
GET /api/auth/profile
Authorization: Bearer {token}
```

## 数据模型

### 设备 (Device)
```json
{
  "id": 1,
  "name": "港口区监控1",
  "device_type": "camera",
  "ip_address": "192.168.1.100",
  "location": "港口A区",
  "status": "online",
  "is_enabled": true
}
```

### 算法 (Algorithm)
```json
{
  "id": 1,
  "name": "船舶靠泊识别",
  "description": "识别船舶靠泊行为",
  "version": "1.0.0",
  "status": "active",
  "accuracy": 95.2,
  "is_enabled": true
}
```

### 事件 (Event)
```json
{
  "id": 1,
  "event_type": "船舶靠泊",
  "device_id": 1,
  "algorithm_id": 1,
  "severity": "high",
  "status": "pending",
  "is_alert": true,
  "description": "检测到船舶靠泊行为"
}
```

## 错误处理

所有API都遵循统一的错误响应格式：

```json
{
  "detail": "错误描述信息"
}
```

常见HTTP状态码：
- `200`: 成功
- `400`: 请求参数错误
- `401`: 未授权
- `404`: 资源不存在
- `500`: 服务器内部错误

## 测试

运行测试脚本验证接口：

```bash
python test_api.py
```

## 开发说明

### TODO 项目
1. 实现真实的告警趋势统计
2. 实现真实的检测数据获取
3. 实现真实的视频流URL生成
4. 实现真实的JWT验证中间件
5. 实现真实的场景管理数据库模型
6. 添加Redis缓存支持
7. 添加WebSocket实时数据推送

### 文件结构
```
server/
├── app.py              # 主应用文件
├── requirements.txt    # 依赖文件
├── test_api.py        # API测试脚本
├── routers/           # 路由模块
│   ├── dashboard.py   # 仪表板接口
│   ├── monitors.py    # 监控管理接口
│   ├── alarms.py      # 告警管理接口
│   ├── scenes.py      # 场景管理接口
│   ├── upload.py      # 文件上传接口
│   └── auth.py        # 用户认证接口
├── models/            # 数据模型
├── core/              # 核心配置
└── uploads/           # 上传文件目录
```

## 部署

### 生产环境配置
1. 修改 `SECRET_KEY` 为安全的密钥
2. 配置数据库连接
3. 设置CORS允许的域名
4. 配置静态文件服务
5. 添加日志记录
6. 配置反向代理

### Docker部署
```dockerfile
FROM python:3.9
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]
```