# 前端接口开发计划

## 概述
根据前端代码分析，当前后端已实现基础的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. 接口文档需要及时更新