GPX/TCX 导入与 Strava 同步:两路骑行数据如何合流

2 阅读10分钟

Strava 的 activity 接口给的只是聚合值。仓库里 StravaActivity 这个 data class 一共就七个数字:distance、moving_time、elapsed_time、total_elevation_gain、average_speed、average_heartrate、average_watts,加一个名字和开始时间。CP/W′ 拟合、NP、W′ 平衡、功率区间分布这些,全都要从逐点流里自己算。

而逐点流是第二次请求:GET /api/v3/activities/{id}/streams,要传九个 key(time、latlng、distance、altitude、heartrate、cadence、watts、velocity_smooth、grade_smooth),配 key_by_type=true 拿回一个 map。所以第一次点进活动详情,必然要等一次网络往返——仓库自己的 docs/流数据加载说明.md 写的是首次 5–15 秒、有缓存后 <1 秒。这个延迟不是优化问题,是接口形态决定的。

另一条路就是文件。码表、别的 App 导出的 GPX/TCX 躺在手机存储里,不需要授权、不需要联网,ActivityResultContracts.OpenDocument() 挑一个就能当场出结果。对于没有功率计订阅、或者不愿把账号交出去的人,这是唯一入口。

这个仓库是公开发行版:源码全在 app/src/main 下,docs/ 下还有 23 篇中文设计与修复文档。所以两路实现可以摊开讲,而不是只讲截图。

整体设计:两条入口,一个会话结构

设计上只有一条硬约束——不管数据从文件来还是从 API 来,最后都必须落到同一个 RideSession 上。分析层 PowerAnalysis 是纯 Kotlin(不 import 任何 android.*),所以它只认这个结构,加格式不用碰它。

先看两路能拿到的字段差异,这决定了哪条路必须自己补算:

字段GPXTCXStrava 流
时间<time> 每点(可缺失)Trackpoint/Timetime(秒偏移)
经纬度trkpt 的 lat/lon 属性LatitudeDegrees/LongitudeDegreeslatlng
海拔eleAltitudeMetersaltitude
心率gpxtpx:hr 扩展HeartRateBpm/Valueheartrate
功率power(非标准扩展)Extensions/TPX/Wattswatts
踏频cadence 扩展Cadencecadence
速度无,需自算无,需自算velocity_smooth

契约本身很薄,全部字段可空:

data class RidePoint(
    val timeEpochSec: Long,
    val latitude: Double?, val longitude: Double?,
    val elevationMeters: Double?, val speedMps: Double?,
    val heartRateBpm: Int?, val powerWatts: Int?, val cadenceRpm: Int?
)

data class RideSession(
    val source: String,           // "gpx" / "tcx" / "strava"
    val startTime: Instant?, val endTime: Instant?,
    val durationSec: Long?, val distanceMeters: Double?,
    val elevationGainMeters: Double?, val avgSpeedMps: Double?,
    val avgHeartRateBpm: Double?, val avgPowerWatts: Double?,
    val points: List<RidePoint>
)

"缺失就 null、不填 0"是后面所有判断的基础。分析入口第一件事就是 val havePower = points.any { it.powerWatts != null },没有功率就整块跳过功率逻辑,而不是拿 0 W 去算 NP——那会把 IF 和 TSS 算成垃圾。

两条链路的调用顺序也是刻意对齐的:

  1. 文件链路:OpenDocument → ContentResolver.openInputStream → parseGpx/parseTcx → RideSession → PowerAnalysis.analyze() → 直接渲染文本结果。中间的会话不进数据库,是一次性的。
  2. API 链路:WorkManager 或手动触发 → syncRecent() 分页拉活动列表落 strava_activities 表 → 进详情页时 buildRideSessionForActivity() 才拉流、分块、拼装 → 同一个 RideSession → 同一个 analyze()。

差别只在"会话的生命周期":文件导入是内存里算完即弃,Strava 活动要能被反复打开,所以多了一层缓存和迁移。分析层对此一无所知。

实现一:导入侧用 XmlPullParser,不建 DOM

GPX/TCX 都是 XML,但一个 3 小时的骑行文件动辄几万个点。用 DOM 或 SimpleXML 一次性建树,内存曲线很难看。这里用 android.util.Xml.newPullParser() 流式读,START_TAG 收字段、END_TAG 碰到 trkpt/Trackpoint 就 flush 一个点到列表里。

真正的麻烦是扩展字段的命名空间不统一。GPX 里心率常见写法是 <gpxtpx:hr>,功率有的设备写 <power>、有的写 <gpxx:power>、有的前缀是 <pwr:power>;TCX 里功率埋在 <Extensions><TPX><Watts> 里,心率是 <HeartRateBpm><Value>。按标签全名相等匹配必然会漏,所以只能退化成后缀/包含匹配:

val name = parser.name.lowercase()
when (name) {
    "trkpt" -> { inTrkpt = true; lat = attr("lat"); lon = attr("lon") }
    "ele" -> ele = parser.nextText().toDoubleOrNull()
    "time" -> time = parseIsoInstant(parser.nextText())
    else -> when {
        name.endsWith(":hr") || name == "hr" -> hr = parser.nextText().toIntOrNull()
        name == "power" || name.endsWith(":power") -> power = parser.nextText().toIntOrNull()
        name.contains("cadence") || name == "cad" -> cad = parser.nextText().toIntOrNull()
    }
}

时间解析用 Instant.parse(),失败返回 null;缺时间的点回退到上一个点的时间(time ?: points.lastOrNull()?.timeEpochSec ?: 0L),保证后面按秒聚合时有基准。

聚合在 buildSession() 里做三件事:距离按 haversine 逐段累加(R = 6371000.0);爬升只累加正的海拔差;平均速度用 distance / duration 而不是逐点速度平均——后者会被停车的采样点稀释。这里没有做任何平滑,代价放在后面说。

实现二:Strava 侧把 JSON 拆成 2000 点一块的 BLOB

旧设计是把整条流塞进一个 TEXT 列(dataJson),读的时候 JSONArray 全量解析;这套结构现在还在 schema 里(StravaActivityStreamEntity),数据靠 StreamChunkMigrator 搬到新表。一条 3 小时 1 Hz 的活动是 10800 点,九条流就是近十万个 double,进详情页直接顶住主线程。

后来换成按块存:表 strava_activity_stream_chunks,主键 (activityId, type, seq),payload 是 BLOB,内容是 Float32 小端序列(FloatArrayCodec 用 ByteBuffer.order(LITTLE_ENDIAN) 编解码),每块 2000 点(StreamChunkBuilder.DEFAULT_CHUNK_SIZE)。

列类型含义
activityIdINTEGER活动 ID,联合主键第一部分
typeTEXT流类型,如 watts、time
seqINTEGER块序号,从 0 递增
startElapsedSecINTEGER块首点的秒偏移
resolutionTEXTStrava 返回的 low/medium/high
sampleRateHzREAL采样率,迁移时从 time 流推断
pointCountINTEGER本块点数
payloadBLOBFloat32 LE 原始字节
compressedINTEGER预留字段,当前恒为 0

旧数据靠 StreamChunkMigrator.migrateIfNeeded() 冷迁移:countAllChunks > 0 直接返回;否则读旧表 JSON、逐条 buildChunks、批量插新表、再删旧行。采样率用 time 流前 16 个间隔的均值取倒数(1f / avgDelta),推断不出来就留 null。读取端 aggregateChunks() 按 seq 排序拼回 DoubleArray,超过 500 ms 会打一条 warning 日志。

拉列表的逻辑在 syncRecent(maxPages, pageSize):翻页直到返回条数小于 pageSize 或触及 maxPages,每页先 dao.existingIds() 查一遍已存在的 ID,用差集算新增,再 upsertAll。这样重复同步不会把"新增数"算错。默认参数是 3 页 × 50 条(SyncStravaUseCase),后台 worker 用的是更保守的 2 页 × 30 条。

同步还有个不明显但致命的点:Strava 的 time 流偶发重复或回退(同一秒里出现两个样本,或者客户端时钟回拨)。如果直接 baseEpoch + seconds,durationSec 会算出 0 或负数,后面的 NP/TSS 全部作废。所以这里做了单调化:

val rawSeconds = timeValues?.getOrNull(index)?.takeIf { it.isFinite() }?.roundToLong()
val seconds = when {
    rawSeconds != null && rawSeconds > lastSeconds -> rawSeconds   // 正常前进
    rawSeconds != null -> lastSeconds + 1                          // 重复/回退,补 1 秒
    lastSeconds >= 0L -> lastSeconds + 1                           // time 流整体缺失
    else -> 0L
}
lastSeconds = seconds

实现三:图只画 1500 点,指标全量算

两条入口汇合之后,消费端分成两路,阈值完全不同:画图可以降采样,指标一秒都不能少。

图表用 LTTB(Largest Triangle Three Buckets)降到 MAX_CHART_POINTS = 1_500,桶宽 (n-2)/(threshold-2),每桶保留与前后基准点构成三角形面积最大的那个点,首尾点强制保留。10800 点的曲线压到 1500 点,视觉上峰谷还在。

指标侧走全量。buildPerSecondPowerSeries() 先把稀疏采样按秒填充成 DoubleArray,再用前缀和求各窗口均值得到 MMP;CP/W′ 用 W = W′ + CP·t 做最小二乘(输入点是 (t, P·t)),拟合失败(斜率或截距 ≤ 0)就返回 null 而不是硬给一个数。

指标参数 / 阈值位置
MMP 窗口5 / 60 / 300 / 1200 / 3600 秒computeMmp
eFTP0.95 × P20,缺失时退 CP,再退 P60/P300estimateFtp
CP / W′W = W′ + CP·t 最小二乘fitCpFromMmp
NP30 秒滚动均值的四次方均值再开四次方computeNp
TSSduration × NP × IF / (FTP × 3600) × 100analyze
功率区间FTP 的 0.55 / 0.75 / 0.90 / 1.05 / 1.20 / 1.50 倍timeInPowerZones
心率区间HRmax 的 0.50 / 0.60 / 0.70 / 0.80 / 0.90 / 1.00 倍timeInHrZones
HRmax全体心率的 98 分位estimateHrMax

没有功率计时,buildFromSeries 直接返回 session = null,只留 hasPowerData 标记;心率侧的 hrTSS 也只在 !havePower && haveHr 时才计算。这条分支很关键——它让"只有心率的手表用户"和"有功率计的用户"走同一套 UI,而不是给前者塞一堆 null。

踩到的三个坑

1. 冷迁移写在 onStart 里,进详情页直接卡住。 最初的写法是 chunkDao.observeAllChunks(id).onStart { migrator.migrateIfNeeded(id) }。onStart 在收集线程执行,而收集发生在主线程;map 里虽然套了 withContext(Dispatchers.Default),外层 Flow 的调度仍然是主线程。大活动(docs/单日记录卡顿修复指南.md 举的例子是 10000+ 采样点)首次进入白屏好几秒,低端机上就是 ANR。改成把整个流包进 flow { } 并 flowOn(Dispatchers.IO):

fun streamSeries(activityId: Long) = flow {
    withContext(Dispatchers.IO) { streamChunkMigrator.migrateIfNeeded(activityId) }
    chunkDao.observeAllChunks(activityId)
        .map { chunks ->
            if (chunks.isEmpty()) emptyList()
            else withContext(Dispatchers.Default) { aggregateChunks(chunks) }
        }
        .collect { emit(it) }
}.flowOn(Dispatchers.IO)

2. Strava OAuth 放进 WebView,直接被 Google 拦。 授权页会跳 Google 登录,而 "Use secure browsers" 策略禁止 WebView 里执行 Google 登录,返回 Error 403: disallowed_useragent。改法是 Custom Tabs(androidx.browser 1.8.0)+ 自定义 scheme 回调 cyclingplus://cyclingplus;manifest 里两个 intent-filter 的 scheme/host 用 gradle placeholder 注入(默认 cyclingplus,可被 gradle.properties 覆盖),并且 token 交换时的 redirect_uri 必须和 Strava 后台填的完全一致。state 也补上了:12 字节随机 hex 存 prefs,回调比对不一致直接拒绝。这条路走通后 README 里专门留了一节配置说明。

3. WorkManager 用错构建器,启动即崩。 StravaAutoSyncManager.syncNow() 里把 PeriodicWorkRequestBuilder 造出来的请求丢给了 enqueue()——周期任务只能进 enqueueUniquePeriodicWork。CRASH_FIX.md 记的现象是应用启动瞬间闪退、logcat 里一条 FATAL,改法是换成 OneTimeWorkRequestBuilder。这类崩溃很讨厌:它跟业务无关,但会让整个 App 打不开。

边界与代价

  • 只认 GPX/TCX。 ImportFragment 里对 fit 是明确提示不支持的(import_unsupported_fit),用户拿 FIT 过来只能先转格式。
  • 爬升没有平滑窗口。 只累加逐点正的海拔差,GPS 高程噪声会累积;如果设备高程抖动 1–2 m,长距离活动的爬升会被明显高估。
  • 秒数补 +1 保证了单调,但会拉长总时长。 重复样本多的活动,durationSec 会比 Strava 自己的 elapsed_time 略大,TSS 跟着偏大一点。
  • 迁移里剔 NaN 会打乱下标。 parseFloatArray 最后是 result.filterNot { it.isNaN() }.toFloatArray(),数组变短了;一旦某条流有大面积 NaN,它和 time 流的下标就对不齐。这类数据目前只能靠"过滤后再判 size"兜着,没有补位。
  • 凭据是明文。 access/refresh token 和 client secret 都存在 SharedPreferences("accounts") 里,client secret 还会被 buildConfigField 打进 APK。发行版能跑,但不是能上架的安全水位。
  • 两套调度并存。 StravaSyncScheduler(6 小时周期、要求 UNMETERED 且电量不低,unique name strava_sync)和 StravaAutoSyncManager(每天 6:00、只要求 CONNECTED,unique name strava_auto_sync)是两套独立链路,同一份数据可能被各拉一次。
  • 拦截器里阻塞。 AuthorizationInterceptor 用 runBlocking 拿 token,RetryInterceptor 用 Thread.sleep 做退避(4 次重试、1 s 起、30 s 封顶、±50% jitter,只对 408/425/429/5xx 和 401 强刷一次)。单人用没问题,并发抓多条流时会排队。token 有效性判断留了 60 秒余量(exp > now + 60 直接用,否则走 refresh),并发刷新靠一个 Mutex 串起来,避免同一条 refresh_token 被两次消费。
  • 同步是"列表优先"的。 活动列表落库后,流数据要等用户点进详情才拉。好处是首屏快,坏处是"离线看不了没打开过的活动"——缓存只覆盖看过的那些。

小结

两路入口的价值不在"支持更多格式",而在于把"数据从哪来"和"数据怎么算"彻底切开:解析器和同步器只负责往 RideSession 里塞点,PowerAnalysis 不碰 Android,所以能直接写单测——PowerAnalysisTest 里 20 分钟恒定 250 W 的用例断言 eFTP ≈ 237.5、NP ≈ 250、IF ≈ 1.05、TSS ≈ 33。要再加一种码表格式,动的是 ImportParsers,不是分析层。

仓库:github.com/Cooperiano/…