---
url: /docs/guide/uniapp/api/health-archive.md
---
# Health Archive 健康档案（前端调用视角）

> 路由：`POST /api/v1/health-archive`（action 协议：`{"action":"...", "payload":{...}}`）
> 封装：`src/api/health-archive.ts`（3 个 export：`archive / saveHealthIncident / saveHeartRateZones`）
> 字段真值以 9-20 audit 报告 `tests/reports/contract-audit-sport-healtharchive.md` §B 为准；本节仅为**矩阵覆盖留痕**，
> 让 `check_uniapp_api_docs` C1 守卫（合同矩阵 ↔ 前端文档）通过；详细字段含义后续阶段补。
> 错误码段：40427xxx。

## 3 个 action（contract-matrix n=47..49）

| action | 入参（`payload`） | 响应关键字段（`res.data`） |
|---|---|---|
| `archive` | `{}` | HealthArchive 7 组件聚合：`basicInfo / healthIncident / physiological / cardiopulmonary / heartRateZones / runningAbility / compatibilityRanges` |
| `saveHealthIncident` | `{symptom?, injuries?}`（部分更新：未出现键保留旧值；空串 = 清空归 null；至少一字段） | `{symptom, injuries, updatedAt}` |
| `saveHeartRateZones` | `{method: 'reserve'\|'maximum'\|'lactate', thresholds: number[4]}`（60-240 严格递增） | `{method, thresholds, updatedAt}` |

## ⚠️ 必读三条

1. **`heartRateZones.zones` / `compatibilityRanges.zones` 可为 `null`**（推导不出阈值时）—— 前端 `props.zones.length` 对 null 会抛 `TypeError`，接线必须 `?? []` 或后端改返 `[]`。
2. **`method` 是枚举键（`reserve` / `maximum` / `lactate`）—— 不是展示文案**。展示必须绑 `methodLabel`（绑 `method` 会显示 "reserve"）。
3. **`heartRateRecovery` 恒 `null`** —— 厂商云无此指标，后端不编造。前端「心率恢复 50」是假值，接真后必须做空态。