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.*),所以它只认这个结构,加格式不用碰它。
先看两路能拿到的字段差异,这决定了哪条路必须自己补算:
| 字段 | GPX | TCX | Strava 流 |
|---|---|---|---|
| 时间 | <time> 每点(可缺失) | Trackpoint/Time | time(秒偏移) |
| 经纬度 | trkpt 的 lat/lon 属性 | LatitudeDegrees/LongitudeDegrees | latlng |
| 海拔 | ele | AltitudeMeters | altitude |
| 心率 | gpxtpx:hr 扩展 | HeartRateBpm/Value | heartrate |
| 功率 | power(非标准扩展) | Extensions/TPX/Watts | watts |
| 踏频 | cadence 扩展 | Cadence | cadence |
| 速度 | 无,需自算 | 无,需自算 | 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 算成垃圾。
两条链路的调用顺序也是刻意对齐的:
- 文件链路:
OpenDocument→ContentResolver.openInputStream→parseGpx/parseTcx→RideSession→PowerAnalysis.analyze()→ 直接渲染文本结果。中间的会话不进数据库,是一次性的。 - 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)。
| 列 | 类型 | 含义 |
|---|---|---|
activityId | INTEGER | 活动 ID,联合主键第一部分 |
type | TEXT | 流类型,如 watts、time |
seq | INTEGER | 块序号,从 0 递增 |
startElapsedSec | INTEGER | 块首点的秒偏移 |
resolution | TEXT | Strava 返回的 low/medium/high |
sampleRateHz | REAL | 采样率,迁移时从 time 流推断 |
pointCount | INTEGER | 本块点数 |
payload | BLOB | Float32 LE 原始字节 |
compressed | INTEGER | 预留字段,当前恒为 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 |
| eFTP | 0.95 × P20,缺失时退 CP,再退 P60/P300 | estimateFtp |
| CP / W′ | W = W′ + CP·t 最小二乘 | fitCpFromMmp |
| NP | 30 秒滚动均值的四次方均值再开四次方 | computeNp |
| TSS | duration × NP × IF / (FTP × 3600) × 100 | analyze |
| 功率区间 | 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 namestrava_sync)和StravaAutoSyncManager(每天 6:00、只要求 CONNECTED,unique namestrava_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,不是分析层。