---
url: /docs/guide/uniapp/api/sport.md
---
# Sport 运动会话 + 记录（前端调用视角）

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

## 6 个 action（contract-matrix n=41..46）

| action | 入参（`payload`） | 响应关键字段（`res.data`） |
|---|---|---|
| `startRun` | `{activityType: 'running'\|'walking'\|'cycling'}` | `{sessionId, activityType, startedAt(ms), resumed}`（幂等：已有进行中会话则返回同一 id + resumed=true）|
| `reportRunCoordinate` | `{sessionId, activityType, latitude, longitude, accuracy, speed, distance, duration, locationTimestamp, reportTimestamp}`（恰 10 字段 extra=forbid） | `{ok, receivedAt}` |
| `finishRun` | `{sessionId, distance?, duration?, calories?, avgHr?, steps?}` | RunSummary + `routePointCount`（重复收尾幂等）|
| `myRunRecords` | `{period?, limit?}` | `{period, since, summary, periodSummary, records[], groups[]}`（会话 + 打卡两源合并）|
| `runSessionDetail` | `{sessionId}` | RunSessionDetail{kind:'session'|'checkin', summary, routePoints, paceSeries, paceLaps, heartZones:null, heartSeries:null, cadenceSeries:null, strideSeries:null, elevationSeries:null}（两种形状按 kind 分支）|
| `addWeightRecord` | `{date, time?, weight, bodyFat?}`（恰 4 字段 extra=forbid） | `{ok, id:string, date, time, weight, bodyFat}` |

## ⚠️ 必读三条（与 wiring-guide.md 同源）

1. **`addWeightRecord` 必须剥离本地 WeightRecord 的 `id` / `createdAt`** —— 后端 `extra="forbid"`，原样提交 → `400 id: Extra inputs are not permitted`（阻断提交）。
2. **`runSessionDetail` 一个 action 两种形状** —— `kind='session'` 13 键 / `kind='checkin'` 仅 7 键（少 sessionId/activityType/startedAt/endedAt/status/avgHr/steps）。
   消费方必须按 `kind` 分支；不分支解引用 undefined（纯插值不崩，`.toUpperCase()` 会崩）。
3. **`startedAt` 是 naive UTC 字符串**（无时区后缀）—— 前端 `new Date()` 按本地时区解析会**差 8 小时**。对比 `startRun.startedAt` 是 epoch ms（无此问题）—— 同批 action 时间格式不一致。