# 接口契约草稿（未实现）

> 阶段一仅用于对齐前后端边界，字段可能随 App 数据模型调整。

## 通用约定

- 基础路径：`/api/v1`
- 认证：`Authorization: Bearer <token>`
- 时间戳：毫秒（UTC）
- 分页：`page`（从 1 开始）、`pageSize`，按时间**倒序**

## 1. 登录

`POST /api/v1/auth/login`

| 字段 | 类型 | 说明 |
|---|---|---|
| phone | string | 手机号 |
| code | string | 短信验证码 |

响应：`{ "token": "...", "userId": "..." }`

## 2. 设备绑定

`POST /api/v1/devices/bind`

| 字段 | 类型 | 说明 |
|---|---|---|
| mac | string | 戒指 MAC 地址（广播数据第 6 位起） |
| name | string | 设备名称 |
| firmwareVersion | string | 固件版本 |

## 3. 健康数据上报

`POST /api/v1/health/records`

| 字段 | 类型 | 说明 |
|---|---|---|
| type | string | `STEP` / `HEART_RATE` / `SLEEP` / `BLOOD_OXYGEN` / `STRESS` / `TEMPERATURE` / `BLOOD_PRESSURE` |
| timestamp | long | 采集时间（毫秒） |
| value | double | 数值 |

支持批量：`POST /api/v1/health/records/batch`，请求体为数组。

## 4. 健康数据查询

`GET /api/v1/health/records?type=STEP&from=<ms>&to=<ms>&page=1&pageSize=100`

响应：

```json
{
  "code": 0,
  "message": "ok",
  "data": { "total": 128, "items": [ { "timestamp": 1757000000000, "value": 8426.0 } ] }
}
```

## 5. 待定项

- 用户资料、头像上传
- 运动记录同步（字段见 App 端 `WorkoutRecord`）
- 固件 OTA 包的托管方式（当前厂商走独立 HTTP 地址）