bigscreen/API_DOCUMENTATION.md

🚀 API接口文档

📋 概览

本文档描述了健康监测大屏系统的所有RESTful API接口。

Base URL: http://localhost:8000/api/v1

认证方式: Bearer Token (JWT)

---

🔐 认证接口 (Authentication)

1. 用户登录

• POST /auth/login
• 描述: 用户登录获取token
• 请求体:

{
  "username": "admin",
  "password": "admin123"
}

• 响应:

{
  "code": 200,
  "data": {
    "access_token": "eyJhbGc...",
    "refresh_token": "eyJhbGc...",
    "token_type": "bearer",
    "expires_in": 1800,
    "user": {
      "id": 1,
      "username": "admin",
      "email": "[email protected]",
      "org_id": 1,
      "roles": ["admin"],
      "permissions": ["user:read", "user:write"]
    }
  },
  "message": "登录成功"
}

2. 刷新Token

• POST /auth/refresh
• 描述: 使用refresh_token刷新access_token

3. 用户注册

• POST /auth/register
• 描述: 新用户注册

4. 获取当前用户信息

• GET /auth/me
• 描述: 获取当前登录用户信息
• 需要认证: ✅

---

📱 设备管理接口 (Device Management)

1. 获取设备列表

• GET /api/v1/devices
• 描述: 获取设备列表，支持分页和筛选
• 需要认证: ✅
• 查询参数:
  • page - 页码 (默认: 1)
  • page_size - 每页数量 (默认: 20, 最大: 100)
  • serial_number - 设备序列号 (可选)
  • device_type - 设备类型 (可选)
  • status - 设备状态 (可选)
  • user_id - 用户ID (可选)
  • org_id - 组织ID (可选)

2. 获取设备详情

• GET /api/v1/devices/{device_id}
• 描述: 根据ID获取设备详情
• 需要认证: ✅

3. 根据序列号获取设备

• GET /api/v1/devices/sn/{serial_number}
• 描述: 根据序列号获取设备详情
• 需要认证: ✅

4. 创建设备

• POST /api/v1/devices
• 描述: 创建新设备
• 需要认证: ✅
• 请求体:

{
  "serial_number": "SN123456789",
  "customer_id": 1,
  "org_id": 100,
  "user_id": "user001",
  "device_model": "Health-Watch-Pro",
  "device_type": "SMARTWATCH",
  "firmware_version": "1.0.5",
  "hardware_version": "2.0",
  "battery_level": 85,
  "status": "ACTIVE"
}

5. 更新设备信息

• PUT /api/v1/devices/{device_id}
• 描述: 更新设备信息
• 需要认证: ✅

6. 删除设备

• DELETE /api/v1/devices/{device_id}
• 描述: 删除设备（软删除）
• 需要认证: ✅

7. 设备绑定申请

• POST /api/v1/devices/bind/request
• 描述: 创建设备绑定申请
• 需要认证: ✅

8. 审批通过绑定申请

• PUT /api/v1/devices/bind/request/{request_id}/approve
• 描述: 审批通过设备绑定申请
• 需要认证: ✅

9. 审批拒绝绑定申请

• PUT /api/v1/devices/bind/request/{request_id}/reject
• 描述: 审批拒绝设备绑定申请
• 需要认证: ✅

10. 获取设备用户列表

• GET /api/v1/devices/{device_sn}/users
• 描述: 获取设备绑定的用户列表
• 需要认证: ✅

11. 解绑设备用户

• POST /api/v1/devices/{device_sn}/unbind/{user_id}
• 描述: 解绑设备和用户
• 需要认证: ✅

---

💓 健康数据接口 (Health Data)

1. 上报健康数据

• POST /api/v1/health/data
• 描述: 上报单条健康数据（设备端调用）
• 需要认证: ✅
• 请求体:

{
  "customer_id": 1,
  "org_id": 100,
  "user_id": "user001",
  "device_sn": "SN123456789",
  "heart_rate": 75,
  "blood_oxygen": 98,
  "body_temperature": 36.5,
  "systolic_pressure": 120,
  "diastolic_pressure": 80,
  "blood_sugar": 5.5,
  "steps": 8500,
  "distance": 6.2,
  "calories": 320,
  "sleep_duration": 450,
  "data_timestamp": "2024-12-03T14:30:00"
}

2. 批量上报健康数据

• POST /api/v1/health/data/batch
• 描述: 批量上报健康数据（最多100条）
• 需要认证: ✅

3. 获取健康数据列表

• GET /api/v1/health/data
• 描述: 获取健康数据列表，支持分页和筛选
• 需要认证: ✅
• 查询参数:
  • page - 页码
  • page_size - 每页数量
  • user_id - 用户ID
  • device_sn - 设备序列号
  • org_id - 组织ID
  • start_time - 开始时间
  • end_time - 结束时间
  • is_abnormal - 是否异常

4. 获取健康数据详情

• GET /api/v1/health/data/{data_id}
• 描述: 根据ID获取健康数据详情
• 需要认证: ✅

5. 获取最新健康数据

• GET /api/v1/health/data/latest/{user_id}
• 描述: 获取用户最新的健康数据
• 需要认证: ✅
• 查询参数:
  • limit - 返回数据条数 (默认: 10)

6. 获取实时健康数据

• GET /api/v1/health/data/realtime/{device_sn}
• 描述: 获取设备实时健康数据（最近5分钟内）
• 需要认证: ✅

7. 获取健康数据统计

• GET /api/v1/health/data/statistics
• 描述: 获取健康数据统计
• 需要认证: ✅
• 查询参数:
  • user_id - 用户ID (可选)
  • org_id - 组织ID (可选)
  • start_date - 开始日期 (可选)
  • end_date - 结束日期 (可选)

8. 获取每日健康汇总

• GET /api/v1/health/data/daily/{user_id}
• 描述: 获取用户每日健康数据汇总
• 需要认证: ✅

9. 获取每周健康汇总

• GET /api/v1/health/data/weekly/{user_id}
• 描述: 获取用户每周健康数据汇总
• 需要认证: ✅

10. 获取组织健康汇总

• GET /api/v1/health/org/summary
• 描述: 获取组织级健康数据汇总（大屏展示用）
• 需要认证: ✅

11. 获取最新组织健康汇总

• GET /api/v1/health/org/summary/latest
• 描述: 获取组织最新健康数据汇总（大屏实时显示）
• 需要认证: ✅

12. 获取组织实时统计

• GET /api/v1/health/org/realtime-stats
• 描述: 获取组织实时健康统计（大屏实时数据）
• 需要认证: ✅
• 响应示例:

{
  "code": 200,
  "data": {
    "total_devices": 150,
    "active_users": 142,
    "abnormal_users": 3,
    "avg_heart_rate": 72.5,
    "avg_blood_oxygen": 97.8,
    "avg_temperature": 36.6,
    "last_update_time": "2024-12-03T14:30:00"
  },
  "message": "获取组织实时统计成功"
}

13. 获取健康趋势

• GET /api/v1/health/data/trend/{user_id}
• 描述: 获取健康数据趋势（用于图表展示）
• 需要认证: ✅
• 查询参数:
  • metric - 指标类型 (heart_rate/blood_oxygen/temperature/steps)
  • days - 天数 (默认: 7)

---

🚨 告警管理接口 (Alert Management)

1. 获取告警列表

• GET /api/v1/alerts
• 描述: 获取告警列表，支持分页和筛选
• 需要认证: ✅
• 查询参数:
  • page - 页码
  • page_size - 每页数量
  • alert_type - 告警类型
  • severity_level - 严重级别 (LOW/MEDIUM/HIGH/CRITICAL)
  • alert_status - 告警状态 (PENDING/CONFIRMED/HANDLED/CLOSED)
  • user_id - 用户ID
  • device_sn - 设备序列号
  • start_time - 开始时间
  • end_time - 结束时间

2. 获取告警详情

• GET /api/v1/alerts/{alert_id}
• 描述: 根据ID获取告警详情
• 需要认证: ✅

3. 创建告警

• POST /api/v1/alerts
• 描述: 创建新告警（系统或设备调用）
• 需要认证: ✅

4. 确认告警

• PUT /api/v1/alerts/{alert_id}/acknowledge
• 描述: 确认告警
• 需要认证: ✅

5. 处理告警

• PUT /api/v1/alerts/{alert_id}/handle
• 描述: 处理告警
• 需要认证: ✅

6. 关闭告警

• PUT /api/v1/alerts/{alert_id}/close
• 描述: 关闭告警
• 需要认证: ✅

7. 获取告警统计

• GET /api/v1/alerts/statistics
• 描述: 获取告警统计（大屏展示用）
• 需要认证: ✅
• 响应示例:

{
  "code": 200,
  "data": {
    "total_alerts": 150,
    "pending_alerts": 12,
    "handled_alerts": 138,
    "critical_alerts": 5,
    "high_alerts": 25,
    "medium_alerts": 60,
    "low_alerts": 60
  },
  "message": "获取告警统计成功"
}

8. 获取告警规则列表

• GET /api/v1/alert-rules
• 描述: 获取告警规则列表
• 需要认证: ✅

9. 创建告警规则

• POST /api/v1/alert-rules
• 描述: 创建告警规则
• 需要认证: ✅

10. 更新告警规则

• PUT /api/v1/alert-rules/{rule_id}
• 描述: 更新告警规则
• 需要认证: ✅

11. 删除告警规则

• DELETE /api/v1/alert-rules/{rule_id}
• 描述: 删除告警规则（软删除）
• 需要认证: ✅

12. 获取健康异常列表

• GET /api/v1/health-anomalies
• 描述: 获取健康异常列表
• 需要认证: ✅

13. 标记健康异常已处理

• PUT /api/v1/health-anomalies/{anomaly_id}/handle
• 描述: 标记健康异常为已处理
• 需要认证: ✅

---

📬 消息推送接口 (Message & Notification)

1. 获取消息列表

• GET /api/v1/messages
• 描述: 获取消息列表，支持分页和筛选
• 需要认证: ✅
• 查询参数:
  • page - 页码
  • page_size - 每页数量
  • message_type - 消息类型
  • urgency - 紧急程度 (LOW/MEDIUM/HIGH/CRITICAL)
  • message_status - 消息状态
  • user_id - 用户ID
  • device_sn - 设备序列号
  • start_time - 开始时间
  • end_time - 结束时间

2. 获取消息详情

• GET /api/v1/messages/{message_id}
• 描述: 根据ID获取消息详情
• 需要认证: ✅

3. 发送消息

• POST /api/v1/messages
• 描述: 发送新消息
• 需要认证: ✅
• 请求体:

{
  "message_id": "MSG20241203001",
  "customer_id": 1,
  "org_id": 100,
  "user_id": "user001",
  "device_sn": "SN123456789",
  "title": "设备电量低告警",
  "message": "您的设备电量已低于20%，请及时充电",
  "message_type": "ALERT",
  "urgency": "HIGH",
  "channels": {
    "device": true,
    "sms": true,
    "wechat": true
  },
  "require_ack": true,
  "expires_at": "2024-12-04T14:30:00"
}

4. 群发消息

• POST /api/v1/messages/broadcast
• 描述: 群发消息（最多1000个目标）
• 需要认证: ✅

5. 更新消息状态

• PUT /api/v1/messages/{message_id}/status
• 描述: 更新消息状态
• 需要认证: ✅

6. 获取消息统计

• GET /api/v1/messages/statistics
• 描述: 获取消息统计
• 需要认证: ✅

7. 获取消息送达详情

• GET /api/v1/messages/{message_id}/details
• 描述: 获取消息送达详情
• 需要认证: ✅

8. 获取消息送达报告

• GET /api/v1/messages/{message_id}/delivery-report
• 描述: 获取消息送达报告
• 需要认证: ✅
• 响应示例:

{
  "code": 200,
  "data": {
    "message_id": 1,
    "total_targets": 100,
    "delivered_count": 95,
    "acknowledged_count": 85,
    "failed_count": 5,
    "pending_count": 0,
    "delivery_rate": 95.0,
    "acknowledgment_rate": 85.0,
    "by_channel": {
      "DEVICE": {"sent": 100, "delivered": 95, "failed": 5},
      "SMS": {"sent": 50, "delivered": 48, "failed": 2}
    }
  },
  "message": "获取送达报告成功"
}

9. 更新消息详情状态

• PUT /api/v1/messages/details/{detail_id}/status
• 描述: 更新消息详情状态（设备端回调）
• 需要认证: ✅

---

📊 统一响应格式

所有API接口返回统一的响应格式：

成功响应

{
  "code": 200,
  "data": { ... },
  "message": "操作成功"
}

错误响应

{
  "code": 400,
  "error": "Bad Request",
  "message": "参数错误",
  "details": { ... }
}

HTTP状态码

• 200 - 成功
• 400 - 请求参数错误
• 401 - 未认证
• 403 - 权限不足
• 404 - 资源不存在
• 500 - 服务器内部错误

---

🔧 开发工具

Swagger UI

访问 http://localhost:8000/docs 查看交互式API文档

ReDoc

访问 http://localhost:8000/redoc 查看ReDoc风格的API文档

---

📝 注意事项

1. 认证: 除了登录和注册接口外，所有接口都需要在请求头中携带Bearer Token
2. 多租户: 所有数据都基于customer_id进行隔离
3. 分页: 列表接口默认分页，page从1开始
4. 软删除: 删除操作为软删除，is_deleted=1
5. 时间格式: 统一使用ISO 8601格式（例如: 2024-12-03T14:30:00）
6. 批量操作: 批量接口有数量限制，注意查看接口描述

---

🚀 快速开始

1. 启动后端服务

cd backend
source venv/bin/activate
python run.py

2. 测试登录接口

curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123"
  }'

3. 使用Token访问其他接口

curl -X GET http://localhost:8000/api/v1/devices \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

---

📞 技术支持

如有问题，请查看：

• 项目文档: MIGRATION_PROGRESS.md
• 迁移计划: MIGRATION_PLAN.md
• 模型映射: MODEL_MAPPING.md