ring-health-api/docs/api-contract.md

接口契约草稿（未实现）

阶段一仅用于对齐前后端边界，字段可能随 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

响应：

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

5. 待定项

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