From fe5f6863263ec744c81018caeb72e0312ac82d29 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=B4=94=E9=B2=81=E6=AD=A3?= <13780741225@163.com>
Date: Thu, 10 Sep 2026 12:33:42 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=88=9D=E5=A7=8B=E5=8C=96=20API=20?=
 =?UTF-8?q?=E4=BB=93=E5=BA=93=E9=AA=A8=E6=9E=B6=E4=B8=8E=E6=8E=A5=E5=8F=A3?=
 =?UTF-8?q?=E5=A5=91=E7=BA=A6=E8=8D=89=E7=A8=BF?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .gitignore           | 17 ++++++++++++
 README.md            |  9 +++++++
 docs/api-contract.md | 63 ++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 89 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 README.md
 create mode 100644 docs/api-contract.md

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 地址）