Appearance
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_docsC1 守卫(合同矩阵 ↔ 前端文档)通过;详细字段含义后续阶段补。 错误码段: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 同源)
addWeightRecord必须剥离本地 WeightRecord 的id/createdAt—— 后端extra="forbid",原样提交 →400 id: Extra inputs are not permitted(阻断提交)。runSessionDetail一个 action 两种形状 ——kind='session'13 键 /kind='checkin'仅 7 键(少 sessionId/activityType/startedAt/endedAt/status/avgHr/steps)。 消费方必须按kind分支;不分支解引用 undefined(纯插值不崩,.toUpperCase()会崩)。startedAt是 naive UTC 字符串(无时区后缀)—— 前端new Date()按本地时区解析会差 8 小时。对比startRun.startedAt是 epoch ms(无此问题)—— 同批 action 时间格式不一致。