Sport Record Share Image 运动记录轨迹图（前端调用视角）

路由：POST /api/v1/device（action 协议：{"action":"...", "payload":{...}}） action：sportRecordShareImage — 运动记录 → 高德地图轨迹图（详情页用） 鉴权：Bearer（未登录 40403002） 错误码段：40403xxx 后端契约权威：src/app/device/interface/api/device_actions.py · 2026-10-09 上线

📚 三接口完整篇（列表 sportRecords / 详情 sportRecordDetail / 轨迹图 + 调用样例 + 真实响应）： api/sport-records —— 本页是轨迹图专题（卡片参数细节）

场景（运动详情页）

运动数据 → 点记录 → 详情页的「轨迹图」区域：调本 action 拿图片 URL → 直接 <image> 展示。 无需前端地图组件 —— 后端出图：高德底图 + 红色轨迹线 + 起终点圆点（Web Mercator 投影后端自画）+ 底部数据卡片（记录名/距离/时长/配速/类型/心率/卡路里/地址/日期/品牌）。

请求

{
  "action": "sportRecordShareImage",
  "payload": {
    "externalId": "qm-qingmu_band-xxx",
    "name": "周日夜跑 · 麓松路沿线",
    "location": {
      "provice": "湖南省",
      "city": "长沙市",
      "area": "岳麓区",
      "address": "麓松路沿线",
      "lng": "112.9388",
      "lat": "28.2282"
    }
  }
}

字段	类型	必填	说明
externalId	string	✅	记录 id（sportRecords 列表项 id 原样回传，同 sportRecordDetail）
name	string	⬜	记录名（如「周日夜跑 · 麓松路沿线」；前端本地已有该名生成逻辑）—— 给了 → 卡片首行显示；不给 → 该行不显示
location	object	⬜	位置结构 —— 给了 → 卡片显示地址行；不给 → 该行不显示
location.provice	string	⬜	省（⚠️ 沿用既有拼写 provice；后端同时兼容 province，将来修拼写无需后端改码）
location.city / .area / .address	string	⬜	市 / 区 / 详址（拼接顺序：省 市 区·详址）
location.lng / .lat	string	⬜	经纬度（当前不参与出图 —— 轨迹以服务端数据为准；保留透传）

lng/lat 说明：图片轨迹以服务端存储的轨迹为准（sportRecordDetail.track 同源）， 前端传的坐标不会覆盖轨迹。若将来需要「图上标当前位置点」再扩展。

响应

{ "code": "0", "msg": "ok",
  "data": { "imageUrl": "https://cos-cdn.qingmulife.cn/share/sport/qm-qingmu_band-xxx.png",
            "pointCount": 42 } }

字段	类型	说明
imageUrl	string	图片 CDN 地址（1200×1600 PNG；底图 + 红色轨迹线 + 起终点圆点 + 底部数据卡片）
pointCount	int	轨迹点数（服务端抽稀后参与出图的点数）

⚠️ 必读四条

1. 幂等可缓存：同 externalId 永远返回同一 URL（COS 覆盖写）—— 可放心缓存 URL；但重新生成会覆盖旧图（记录更新后若需刷图，加时间戳参数即可，本项目不做）。
2. 无轨迹记录有明确空态：打卡类记录无 GPS 轨迹 → 40403009「该记录无轨迹数据」→ 前端显示「本次运动未记录轨迹」空态，不要重试。
3. 生成失败可重试：40403008（502）= 高德/COS 抖动 → 给「重试」按钮（幂等无害）。
4. 首次生成约 1-3 秒（拉高德底图 + 传 COS）→ 前端给 loading 态；生成后再调同 externalId 秒回（已是 CDN 图可直接缓存本地）。

错误码

code	HTTP	场景	前端处理
40403001	400	payload 校验失败 / unknown action	检查传参
40403002	401	未登录	跳登录
40403004	404	记录不存在（或非本人 —— 跨用户查不到）	提示记录不存在
40403008	502	轨迹图生成失败（高德/COS）	可重试按钮
40403009	400	该记录无轨迹数据（打卡类）	「未记录轨迹」空态，勿重试

调用时序（推荐）

进入详情页
  → sportRecordDetail {externalId}          ← 页面数据（距离/配速/心率曲线…）
  → sportRecordShareImage {externalId, location?}
      ├─ code=0 → <image :src="imageUrl">（轨迹图区）
      ├─ 40403009 → 「本次运动未记录轨迹」空态
      └─ 40403008 → 「生成失败」+ 重试

顺带修复：sportRecords 新增累计时长

sportRecords.summary 新增 totalDurationSec（秒）—— 列表页顶部「累计运动用时」 此前显示 -- 是因为该字段缺失，前端改用此字段即可：

summary: { totalDistanceKm, totalCalories, totalCount, totalDurationSec }

相关

• 三接口完整篇：api/sport-records（列表 / 详情 / 轨迹图 + 调用样例 + 生产真实响应）
• 跑步会话分享图（另一条线）：api/run-share