# 手表被动记录：数据接入契约（2026-10-01）

范围：iPhone 端只读 Apple HealthKit 的既有记录；Android Health Connect 为后续接入。本文规定原始数据摄取与可用性表达，不定义健康评分、诊断或阈值。实现中的同步频率和可获得样本数都不能视为手表实时采样承诺。

## iOS：接入与增量流程

1. 配置 HealthKit capability 与 `NSHealthShareUsageDescription`，调用 `HKHealthStore.isHealthDataAvailable()`；按实际功能逐类请求 **read** 权限（首批候选 `stepCount`、`restingHeartRate`、`heartRateVariabilitySDNN`、`sleepAnalysis`，其他类型另行按需申请）。`requestAuthorization` 返回成功只说明请求流程完成，**不代表任何读取权限已授予**。Apple 明确不向应用披露某类型的读取授权/拒绝状态；拒绝读取时查询可能表现为无匹配数据。用户还可仅开放有限历史区间。[Apple：授权](https://developer.apple.com/documentation/healthkit/authorizing-access-to-health-data) · [Apple：授权状态](https://developer.apple.com/documentation/healthkit/hkauthorizationstatus)
2. 首次读取用各类型独立的 `HKAnchoredObjectQuery`（`anchor=nil`）取得可见快照；持久化每类型的 `HKQueryAnchor`。后续从各自锚点获取新增样本和删除对象。`HKObserverQuery` 配合 background delivery 仅作为“需要拉增量”的唤醒信号：回调本身没有变化详情，后台通知受系统调度与注册频率限制，不能承诺立即到达。启动时重建 observer，唤醒后执行 anchored query，处理成功后再保存新锚点并调用 observer completion handler。后台能力需相应 entitlement；真机验证。[Apple：锚点查询](https://developer.apple.com/documentation/healthkit/hkanchoredobjectquery) · [Apple：观察查询](https://developer.apple.com/documentation/healthkit/executing-observer-queries) · [Apple：后台 entitlement](https://developer.apple.com/documentation/bundleresources/entitlements/com.apple.developer.healthkit.background-delivery)
3. 每条新增记录按 `(platform='healthkit', type, HKObject.uuid)` 幂等 upsert，保留 `sourceRevision` / `device` 供来源说明与排重策略使用。原始样本重复摄取只留一条；不同来源在同一时段的重叠样本**不可直接相加**。若需形成单一展示序列，先确定并记录每指标的来源优先级，在展示层选源，原始记录保留。`HKDeletedObject.uuid` 对应本地副本应删除或标记删除；删除对象在 HealthKit 中可能只短暂保留，长期离线后要允许对已授权可见区间重新对账。[Apple：来源字段](https://developer.apple.com/documentation/healthkit/hkobject/sourcerevision) · [Apple：删除对象](https://developer.apple.com/documentation/healthkit/hkdeletedobject)

## 标准化原始字段

| 字段 | 规则 |
|---|---|
| `platform`, `type`, `source_record_id` | 必填；iOS 为 `healthkit`、HealthKit 类型名、`HKObject.uuid`；三者组成摄取键。 |
| `start_at`, `end_at`, `observed_at` | UTC 时间；保留原始区间，单点样本也保留原始 start/end。`observed_at` 为本应用读入时间，不能冒充测量时间。 |
| `value`, `unit`, `method` | 数值型样本存原值与单位；HRV 显式 `method=SDNN`、单位毫秒。不同方法不能混为同一数列。睡眠样本使用 `stage` 而非 `value`。 |
| `stage` | iOS 保留 `inBed`、`awake`、`asleepCore`、`asleepDeep`、`asleepREM`、`asleepUnspecified` 原值；兼容历史 `asleep` 时归为“不分期睡眠”，不推测具体阶段。`inBed` 可与详细睡眠阶段重叠，不能累加为总睡眠。 |
| `source_id`, `source_version`, `device_info` | 来自 `sourceRevision` 与 `device`，空值允许；不要仅凭设备名去重。 |
| `ingested_at`, `deleted_at` | 本地同步审计时间；删除事件保留 ID 墓碑，以便下游撤销派生结果。 |

Apple 的 HRV 类型是 `heartRateVariabilitySDNN`，Apple Watch 自动产生的是**离散样本**；不能假设每分钟或连续 HRV 数据。心率后台采样也依机型、动作与信号质量而异；缺口应保留为缺口，不插值伪造原始样本。[Apple：HRV 类型](https://developer.apple.com/documentation/healthkit/hkquantitytypeidentifier/heartratevariabilitysdnn) · [Apple：手表心率技术说明](https://www.apple.com/health/pdf/Heart_Rate_Calorimetry_Activity_on_Apple_Watch_November_2024.pdf)

睡眠是若干区间样本，并非必然完整连续。Apple 说明手表的 `awake` 样本只包括两段睡眠之间的清醒片段，`inBed` 区间首尾可能没有详细阶段；缺失阶段不能补作清醒或深睡。[Apple：睡眠枚举与样本关系](https://developer.apple.com/documentation/healthkit/hkcategoryvaluesleepanalysis)

## 权限、缺失与错误状态

| 对外状态 | 触发与处理 |
|---|---|
| `unsupported` | HealthKit 不可用；停止请求并说明当前设备不支持。 |
| `access_requested` | 授权请求已完成；不标成“已获得读取权限”。若查询为空，表达为“暂无可读取记录”，附“可能尚无数据、未开放此项或历史范围受限”。提供前往系统“健康”应用管理权限的路径。 |
| `partial_data` | 某类型、时段或睡眠阶段缺样本；只展示实际覆盖时间与最近样本时间，不把缺失值当作零。不同类型分别处理，不阻塞其余数据。 |
| `sync_delayed` | observer 未到或后台受限；前台启动/打开页面时主动增量同步，并显示上次成功同步时间。 |
| `sync_error` | 查询、存储或同步失败；保留上次完整数据与旧锚点，退避重试。只有增量数据及删除处理全部持久化后才推进锚点。 |

## Android 后续路径

采用 Health Connect 的每类型读取权限与 `getGrantedPermissions()` 检查；与 iOS 不同，这里可检查应用已获权限。先确认 Health Connect 可用，再请求所需记录类型。初次按时间范围分页读取；持续同步使用每类型 `getChangesToken` / `getChanges`，处理 upsert 与 deletion，并保存 token；token 失效时重建可读窗口。后台读取与超过默认历史窗口读取分别需要额外权限，不能默认为可用。[Google：开始接入](https://developer.android.com/health-and-fitness/health-connect/get-started) · [Google：读取与历史范围](https://developer.android.com/health-and-fitness/health-connect/read-data) · [Google：变更同步](https://developer.android.com/health-and-fitness/health-connect/sync-data)

映射建议：`HeartRateRecord`、`RestingHeartRateRecord`、`SleepSessionRecord` 分别接入对应原始类型。Health Connect 的 HRV 为 `HeartRateVariabilityRmssdRecord`，方法是 **RMSSD**；必须写 `method=RMSSD`，不得与 HealthKit 的 SDNN 值直接合并或比较。睡眠阶段沿用 Android 原始枚举及 session ID，保留区间缺口；其阶段集合与 Apple 不完全一致。[Google：数据类型与权限](https://developer.android.com/health-and-fitness/health-connect/data-types) · [Google：睡眠阶段](https://developer.android.com/health-and-fitness/health-connect/features/sleep-sessions)
