# 🚀 API接口文档

## 📋 概览

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

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

**认证方式**: Bearer Token (JWT)

---

## 🔐 认证接口 (Authentication)

### 1. 用户登录
- **POST** `/auth/login`
- **描述**: 用户登录获取token
- **请求体**:
```json
{
  "username": "admin",
  "password": "admin123"
}
```
- **响应**:
```json
{
  "code": 200,
  "data": {
    "access_token": "eyJhbGc...",
    "refresh_token": "eyJhbGc...",
    "token_type": "bearer",
    "expires_in": 1800,
    "user": {
      "id": 1,
      "username": "admin",
      "email": "admin@example.com",
      "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`
- **描述**: 创建新设备
- **需要认证**: ✅
- **请求体**:
```json
{
  "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`
- **描述**: 上报单条健康数据（设备端调用）
- **需要认证**: ✅
- **请求体**:
```json
{
  "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`
- **描述**: 获取组织实时健康统计（大屏实时数据）
- **需要认证**: ✅
- **响应示例**:
```json
{
  "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`
- **描述**: 获取告警统计（大屏展示用）
- **需要认证**: ✅
- **响应示例**:
```json
{
  "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`
- **描述**: 发送新消息
- **需要认证**: ✅
- **请求体**:
```json
{
  "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`
- **描述**: 获取消息送达报告
- **需要认证**: ✅
- **响应示例**:
```json
{
  "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接口返回统一的响应格式：

### 成功响应
```json
{
  "code": 200,
  "data": { ... },
  "message": "操作成功"
}
```

### 错误响应
```json
{
  "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. 启动后端服务
```bash
cd backend
source venv/bin/activate
python run.py
```

### 2. 测试登录接口
```bash
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123"
  }'
```

### 3. 使用Token访问其他接口
```bash
curl -X GET http://localhost:8000/api/v1/devices \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

---

## 📞 技术支持

如有问题，请查看：
- 项目文档: `MIGRATION_PROGRESS.md`
- 迁移计划: `MIGRATION_PLAN.md`
- 模型映射: `MODEL_MAPPING.md`