64 lines
1.5 KiB
Markdown
64 lines
1.5 KiB
Markdown
# 接口契约草稿（未实现）
|
||
|
||
> 阶段一仅用于对齐前后端边界，字段可能随 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 地址）
|