Skip to content

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 时间格式不一致。