2025-08-05 11:57:14 +08:00

363 lines
7.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 前端接口开发计划
## 概述
根据前端代码分析当前后端已实现基础的CRUD接口但前端需要更多统计、监控、告警等功能的接口。以下是缺失接口的开发计划。
## 已实现接口
- ✅ 设备管理CRUD操作
- ✅ 算法管理CRUD操作
- ✅ 事件管理CRUD操作
## 缺失接口清单
### 1. 仪表板统计接口 (优先级:高)
#### 1.1 主要KPI指标
```
GET /api/dashboard/kpi
响应:
{
"total_devices": 156,
"online_devices": 142,
"total_algorithms": 8,
"active_algorithms": 6,
"total_events": 1247,
"today_events": 89,
"alert_events": 23,
"resolved_events": 66
}
```
#### 1.2 告警趋势统计
```
GET /api/dashboard/alarm-trend
参数:
- days: 7 (默认7天)
响应:
{
"dates": ["2024-01-01", "2024-01-02", ...],
"alarms": [12, 15, 8, 23, 18, 25, 20],
"resolved": [10, 12, 7, 19, 15, 22, 18]
}
```
#### 1.3 摄像头统计
```
GET /api/dashboard/camera-stats
响应:
{
"total_cameras": 156,
"online_cameras": 142,
"offline_cameras": 14,
"by_location": [
{"location": "港口区", "total": 45, "online": 42},
{"location": "码头区", "total": 38, "online": 35},
{"location": "办公区", "total": 23, "online": 21}
]
}
```
#### 1.4 算法统计
```
GET /api/dashboard/algorithm-stats
响应:
{
"total_algorithms": 8,
"active_algorithms": 6,
"by_type": [
{"type": "目标检测", "count": 3, "accuracy": 95.2},
{"type": "行为识别", "count": 2, "accuracy": 88.7},
{"type": "越界检测", "count": 3, "accuracy": 92.1}
]
}
```
#### 1.5 事件热点统计
```
GET /api/dashboard/event-hotspots
响应:
{
"hotspots": [
{
"location": "港口A区",
"event_count": 45,
"severity": "high",
"coordinates": {"lat": 31.2304, "lng": 121.4737}
}
]
}
```
### 2. 监控管理接口 (优先级:高)
#### 2.1 监控列表
```
GET /api/monitors
参数:
- page: 1
- size: 20
- status: online/offline
- location: 位置筛选
响应:
{
"monitors": [
{
"id": 1,
"name": "港口区监控1",
"location": "港口A区",
"status": "online",
"video_url": "/videos/port-1.mp4",
"detections": [
{"type": "person", "x": 25, "y": 35, "width": 40, "height": 80}
]
}
],
"total": 156,
"page": 1,
"size": 20
}
```
#### 2.2 监控详情
```
GET /api/monitors/{monitor_id}
响应:
{
"id": 1,
"name": "港口区主监控",
"location": "港口区",
"status": "online",
"video_url": "/videos/port-main.mp4",
"detections": [...],
"events": [...],
"algorithms": [...]
}
```
### 3. 告警管理接口 (优先级:中)
#### 3.1 告警列表
```
GET /api/alarms
参数:
- page: 1
- size: 20
- severity: high/medium/low
- status: pending/resolved
- start_time: 2024-01-01
- end_time: 2024-01-31
响应:
{
"alarms": [
{
"id": 1,
"type": "船舶靠泊",
"severity": "high",
"status": "pending",
"device": "港口区监控1",
"created_at": "2024-01-15T10:30:00Z",
"description": "检测到船舶靠泊行为"
}
],
"total": 89,
"page": 1,
"size": 20
}
```
#### 3.2 告警处理
```
PATCH /api/alarms/{alarm_id}/resolve
请求体:
{
"resolution_notes": "已确认船舶靠泊,无异常",
"resolved_by": "operator1"
}
```
#### 3.3 告警统计
```
GET /api/alarms/stats
响应:
{
"total_alarms": 89,
"pending_alarms": 23,
"resolved_alarms": 66,
"by_severity": [
{"severity": "high", "count": 12},
{"severity": "medium", "count": 45},
{"severity": "low", "count": 32}
]
}
```
### 4. 场景管理接口 (优先级:中)
#### 4.1 场景列表
```
GET /api/scenes
响应:
{
"scenes": [
{
"id": "scene-001",
"name": "港口区场景",
"description": "港口区监控场景",
"device_count": 45,
"algorithm_count": 3
}
]
}
```
#### 4.2 场景详情
```
GET /api/scenes/{scene_id}
响应:
{
"id": "scene-001",
"name": "港口区场景",
"description": "港口区监控场景",
"devices": [...],
"algorithms": [...],
"events": [...]
}
```
### 5. 文件上传接口 (优先级:中)
#### 5.1 视频上传
```
POST /api/upload/video
Content-Type: multipart/form-data
请求体:
- file: 视频文件
- device_id: 设备ID
- description: 描述
响应:
{
"file_id": "video_123",
"file_url": "/uploads/videos/video_123.mp4",
"file_size": 1024000,
"duration": 30.5
}
```
#### 5.2 图片上传
```
POST /api/upload/image
Content-Type: multipart/form-data
请求体:
- file: 图片文件
- event_id: 事件ID
响应:
{
"file_id": "image_456",
"file_url": "/uploads/images/image_456.jpg",
"file_size": 256000
}
```
### 6. 用户认证接口 (优先级:低)
#### 6.1 用户登录
```
POST /api/auth/login
请求体:
{
"username": "admin",
"password": "password123"
}
响应:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"token_type": "bearer",
"expires_in": 3600,
"user": {
"id": 1,
"username": "admin",
"role": "admin"
}
}
```
#### 6.2 用户信息
```
GET /api/auth/profile
响应:
{
"id": 1,
"username": "admin",
"email": "admin@example.com",
"role": "admin",
"permissions": ["read", "write", "admin"]
}
```
## 开发进度
### ✅ 已完成 (第一阶段)
1. ✅ 仪表板统计接口 (KPI、告警趋势、摄像头统计、算法统计、事件热点)
2. ✅ 监控管理接口 (监控列表、监控详情)
### ✅ 已完成 (第二阶段)
1. ✅ 告警管理接口 (告警列表、告警处理、告警统计)
2. ✅ 场景管理接口 (场景列表、场景详情)
### ✅ 已完成 (第三阶段)
1. ✅ 文件上传接口 (视频上传、图片上传)
2. ✅ 用户认证接口 (登录、用户信息)
### 🔄 待优化功能
1. 实现真实的告警趋势统计 (当前使用模拟数据)
2. 实现真实的检测数据获取 (当前使用模拟数据)
3. 实现真实的视频流URL生成
4. 实现真实的JWT验证中间件
5. 实现真实的场景管理数据库模型
6. 实现真实的文件删除逻辑
7. 添加Redis缓存支持
8. 添加WebSocket实时数据推送
## 技术实现要点
1. **数据库模型扩展**
- 添加统计相关的视图或缓存表
- 优化查询性能,添加索引
2. **缓存策略**
- 使用Redis缓存统计数据
- 设置合理的缓存过期时间
3. **文件存储**
- 配置静态文件服务
- 实现文件上传和存储逻辑
4. **权限控制**
- 实现JWT认证
- 添加角色和权限控制
5. **WebSocket支持**
- 实时监控数据推送
- 告警实时通知
## 测试计划
1. **单元测试**每个接口的CRUD操作
2. **集成测试**:前后端联调
3. **性能测试**:大数据量下的响应时间
4. **安全测试**:认证和权限验证
## 部署计划
1. **开发环境**:本地测试
2. **测试环境**:功能验证
3. **生产环境**:正式部署
## 注意事项
1. 所有接口需要添加错误处理和日志记录
2. 敏感数据需要加密存储
3. 文件上传需要限制文件大小和类型
4. 统计数据需要定期更新,避免过期数据
5. 接口文档需要及时更新