border_Inspection/server/todo.md

前端接口开发计划

概述

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