HealthGather API

把 Apple 健康（HealthKit）的血糖数据同步到自有服务器的 HTTP 接口。

Base URL：https://health.xiahaoyun.com

鉴权

所有 /v1/health/* 接口都需要 API key，放在请求头：

Authorization: Bearer hg_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Key 类型	scope	读	写	用途
只读 key	`read`	是	否	查询/对账、图表、第三方消费
读写 key	`read_write`	是	是	iOS 同步 App 上传

key 由服务端 CLI 创建，只存 SHA-256 哈希；不同 key 的数据按 user_id 互相隔离。错误码：缺失/未知 key → 401；只读 key 调写入 → 403；参数格式错误 → 422。

接口列表

GET /v1/health/status — 测试连接与 key 权限

权限：read 或 read_write

curl -H "Authorization: Bearer $KEY" https://health.xiahaoyun.com/v1/health/status

{"ok": true, "user_id": "5cae334c-...", "scope": "read"}

GET /v1/health/events — 查询血糖记录

权限：read 或 read_write

参数	必填	说明
`metric_type`	否	固定 `blood_glucose`
`from`	否	ISO8601 UTC，筛选 observed_at >= from
`to`	否	ISO8601 UTC，筛选 observed_at < to（左闭右开）
`limit`	否	返回条数，默认 1000，上限 5000

curl -H "Authorization: Bearer $KEY" \
  "https://health.xiahaoyun.com/v1/health/events?metric_type=blood_glucose&from=2026-07-25T00:00:00Z&to=2026-07-26T00:00:00Z&limit=100"

响应：Event 数组（见下方结构），按 observed_at 升序。

POST /v1/health/events — 批量上传血糖记录（幂等）

权限：read_write

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{
  "sent_at": "2026-07-25T03:40:00Z",
  "events": [{
    "provider_record_id": "0AD9FF4F-4E80-49E2-B7D7-E36704B98948",
    "metric_type": "blood_glucose",
    "observed_at": "2026-07-25T03:36:52Z",
    "value_raw": 4.7,
    "unit_raw": "mmol/L",
    "source": "鱼跃安耐糖"
  }]
}' https://health.xiahaoyun.com/v1/health/events

{"accepted": 1, "inserted": 1, "deduplicated": 0, "confirmed": ["0AD9FF4F-4E80-49E2-B7D7-E36704B98948"]}

幂等：按 (user_id, provider_record_id) 去重，重复上传安全。confirmed 为本次全部已确认 ID（含去重）。provider_record_id 建议用 HealthKit 记录 UUID。

GET /v1/health/reconcile — 按日对账（记录 ID 清单）

权限：read 或 read_write

参数	必填	说明
`date`	是	`YYYY-MM-DD`（按 UTC 日）

curl -H "Authorization: Bearer $KEY" "https://health.xiahaoyun.com/v1/health/reconcile?date=2026-07-25"

{"date": "2026-07-25", "ids": ["0AD9FF4F-...", "E8036D1E-..."]}

客户端核对某天服务端是否齐全：本地 ID 集合减去服务端返回 ID 集合，差集即缺失，重传即可（服务端幂等兜底）。

V2：通用样本 changes 协议

V1 与 V2 共享统一表 health_records（单一事实源）：V2 后台写入的数据对上面的 V1 查询/对账/看板立即可见，HomeView「立即同步」（V1 POST）与后台 V2 同步落在同一张表。配合 iOS 按类型 anchor 的增量同步底座，支持 upsert + delete tombstone。详见 docs/health-sync-phase0.md。

POST /v2/health/changes — 批量上传健康变更（幂等 upsert + delete tombstone）

权限：read_write

请求头：Idempotency-Key: <installation_id>:<batch_id>（诊断用；幂等性由行级 upsert/delete 保证）。

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{
  "source": "apple_health",
  "installation_id": "00000000-0000-0000-0000-000000000001",
  "sent_at": "2026-07-27T03:00:00Z",
  "changes": [
    { "operation": "upsert",
      "record": { "provider_record_id":"0AD9FF4F-...", "record_type":"quantity",
                  "metric_type":"blood_glucose", "start_at":"2026-07-27T02:59:00Z",
                  "end_at":"2026-07-27T02:59:00Z", "value_numeric":7.7,
                  "unit":"mmol/L", "source_name":"鱼跃安耐糖" } },
    { "operation": "delete",
      "provider_record_id":"E8036D1E-...", "record_type":"quantity",
      "metric_type":"blood_glucose" }
  ]
}' https://health.xiahaoyun.com/v2/health/changes

{"accepted": 2, "upserted": 1, "deleted": 1, "failed": []}

幂等与 tombstone：整批一个事务，2xx = 可安全重放。唯一键 (user_id, provider, record_type, provider_record_id)，跨设备/重放不重复。delete 置 deleted_at tombstone（绝不硬删除），已 tombstone 的记录后续 upsert 不复活（粘性）。点测类样本令 start_at == end_at。

数据结构：Event

字段	类型	说明
`provider_record_id`	string	HealthKit 记录 UUID，幂等去重依据
`metric_type`	string	MVP 固定 `blood_glucose`
`observed_at`	ISO8601 UTC	测量时间
`value_raw`	number	原始数值（CGM 原生单位）
`unit_raw`	string	单位，当前为 `mmol/L`
`source`	string?	写入 Apple 健康的设备/应用（可空）
`received_at`	ISO8601 UTC	服务端收到时间（仅查询返回）

其他

机器可读规范（供 AI/程序消费）： /openapi.json（OpenAPI 3.x）。
交互式调试： /docs（Swagger UI）。
血糖看板： /?key=<只读key>（折线图，支持缩放/选区）。
时间：全部 UTC。value_raw 可能有 CGM 单精度浮点小尾巴，消费时 round(v, 1)。

本服务是健康数据同步层，不提供诊断、告警或医疗建议。