commit fe5f6863263ec744c81018caeb72e0312ac82d29
Author: 崔鲁正 <13780741225@163.com>
Date:   Thu Sep 10 12:33:42 2026 +0800

    docs: 初始化 API 仓库骨架与接口契约草稿

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..602ceb2
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,17 @@
+# 通用
+.idea/
+.vscode/
+*.log
+.DS_Store
+
+# Java / Kotlin
+*.class
+build/
+.gradle/
+out/
+target/
+
+# .NET
+bin/
+obj/
+*.user
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..bd4bc90
--- /dev/null
+++ b/README.md
@@ -0,0 +1,9 @@
+# ring-health-api
+
+智能戒指健康 App 的后端 API（阶段一仅契约，未实现）。
+
+- 当前状态：**空仓库 + 接口契约草稿**
+- 后端技术栈：待 M4 前确定（Spring Boot / .NET 均可，见设计文档）
+- 接口契约：见 `docs/api-contract.md`
+
+等待 App 端数据模型稳定后（M3 结束）再启动实现，避免两端空转。
diff --git a/docs/api-contract.md b/docs/api-contract.md
new file mode 100644
index 0000000..55bd1b4
--- /dev/null
+++ b/docs/api-contract.md
@@ -0,0 +1,63 @@
+# 接口契约草稿（未实现）
+
+> 阶段一仅用于对齐前后端边界，字段可能随 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 地址）