yl-frontend/api-docs/device-api.txt

穿戴设备模块接口文档
================

基础信息
-------
- 基础路径: /api/v1/devices
- 请求方式: REST
- 数据格式: JSON
- 认证方式: Bearer Token

数据结构
-------

Device 设备对象:
{
  id: number,          // 设备ID
  name: string,        // 设备名称
  type: string,        // 设备类型
  model: string,       // 设备型号
  status: string,      // 设备状态(online/offline)
  battery: number,     // 电量百分比
  lastUpdate: string,  // 最后更新时间
  bindTime: string,    // 绑定时间
  settings: {          // 设备设置
    [key: string]: any
  }
}

HealthData 健康数据:
{
  id: number,          // 数据ID
  deviceId: number,    // 设备ID
  type: string,        // 数据类型
  value: number,       // 数据值
  unit: string,        // 单位
  time: string,        // 记录时间
  status: string       // 状态(normal/warning/danger)
}

API 接口
-------

1. 获取设备列表
GET /api/v1/devices

响应示例：
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "name": "智能手环",
      "type": "bracelet",
      "model": "HC-001",
      "status": "online",
      "battery": 85,
      "lastUpdate": "2024-03-20 10:00:00",
      "bindTime": "2024-01-01",
      "settings": {
        "heartRateMonitor": true,
        "sleepTracker": true,
        "stepCounter": true,
        "displayBrightness": 80
      }
    }
  ]
}

2. 获取设备详情
GET /api/v1/devices/{id}

响应示例：
{
  "code": 200,
  "message": "success",
  "data": {
    // 设备详细信息
  }
}

3. 更新设备设置
PUT /api/v1/devices/{id}/settings

请求参数：
{
  "heartRateMonitor": true,
  "sleepTracker": true,
  "stepCounter": true,
  "displayBrightness": 80
}

4. 获取健康数据
GET /api/v1/devices/{id}/health-data

请求参数：
| 参数名 | 类型   | 必填 | 说明 |
| type   | string | 否   | 数据类型 |
| start  | string | 否   | 开始时间 |
| end    | string | 否   | 结束时间 |

响应示例：
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "deviceId": 1,
      "type": "heartRate",
      "value": 75,
      "unit": "bpm",
      "time": "2024-03-20 10:00:00",
      "status": "normal"
    }
  ]
}

5. 获取设备告警
GET /api/v1/devices/alerts

请求参数：
| 参数名    | 类型   | 必填 | 说明 |
| deviceId | number | 否   | 设备ID |
| handled  | boolean| 否   | 是否已处理 |

6. 处理告警
POST /api/v1/devices/alerts/{id}/handle

7. 获取位置记录
GET /api/v1/devices/{id}/locations

请求参数：
| 参数名     | 类型   | 必填 | 说明 |
| startTime | string | 否   | 开始时间 |
| endTime   | string | 否   | 结束时间 |
| limit     | number | 否   | 返回数量 |

8. 绑定设备
POST /api/v1/devices/bind

请求参数：
{
  "name": "智能手环",
  "type": "bracelet",
  "model": "HC-001"
}

9. 解绑设备
POST /api/v1/devices/{id}/unbind

10. 远程控制设备
POST /api/v1/devices/{id}/control

请求参数：
{
  "command": "restart",
  "params": {
    // 命令参数
  }
}

11. 获取设备统计
GET /api/v1/devices/{id}/stats

响应示例：
{
  "code": 200,
  "message": "success",
  "data": {
    "totalSteps": 8500,
    "avgHeartRate": 75,
    "sleepHours": 7.5,
    "activeMinutes": 120
  }
}

错误码说明
--------
| 错误码 | 说明 |
| 200    | 成功 |
| 400    | 请求参数错误 |
| 401    | 未授权 |
| 403    | 禁止访问 |
| 404    | 设备不存在 |
| 500    | 服务器内部错误 |

注意事项
-------
1. 设备类型说明：
   - bracelet: 智能手环
   - locator: GPS定位器
   - monitor: 健康监测仪

2. 健康数据类型：
   - heartRate: 心<><E5BF83><EFBFBD>
   - steps: 步数
   - bloodPressure: 血压
   - sleep: 睡眠

3. 告警级别：
   - info: 提示
   - warning: 警告
   - danger: 危险

4. 位置数据精度说明：
   - accuracy: 定位精度(米)
   - 建议每5分钟上报一次位置

5. 设备控制命令：
   - restart: 重启设备
   - reset: 重置设备
   - update: 更新固件
   - locate: 查找设备