feat(workouts): enrich the per-workout detail view (#67)

The detail surface at /insights/workouts/[id] gains a real heart-rate
curve, effort zones, an aspect-true GPS route, and per-kilometre splits
— all read from data already stored, no new integration, no migration.

- HR curve: one server path with strict provenance — stored
  WorkoutSamples series first, a raw-PULSE window reconstruction second
  (quality-gated so sparse data hides rather than lies), nothing third.
  Adaptive bucketing keeps on-screen density constant across a 20-minute
  HIIT and a 6-hour ride; a min/max envelope surfaces intervals.
- Effort zones: five %HRmax bands via the Tanaka HRmax, with a device's
  own reported time-in-zone winning when present. Descriptive only.
- GPS route: self-rendered inline SVG with an equirectangular
  cos(midLat) longitude correction (fixes the ~40% horizontal stretch),
  aspect-clamped viewBox, RDP downsampling, start/end markers, and an
  optional elevation profile. Nothing leaves the origin — no map tiles.
- Per-km splits and a GPX export, both derived client/server-side from
  the geometry already on the payload.
- The endpoint extends additively (hrSeries, zones, splits, sportContext,
  a reserved insight seam) behind an opt-in compact=1 param that drops
  the raw sample/timestamp blobs for the web client; without the param
  the response is unchanged.
- Every data-less section now hides instead of rendering an empty card;
  the growing detail component is split into a workout-detail/ directory.
- List rows flag which sessions open into a rich detail.
This commit is contained in:
Marc-André Bombeck committed 2026-07-18 16:05:17 +02:00
1 parent 04320c415d
commit e61fe42bd1
38 files changed
+3466 -511

No files matched your search

+71 -1
View File
@@ -56,6 +56,9 @@ const workoutListEntry = z
maxHr: z.number().int().nullable(),
source: measurementSourceEnum,
externalId: z.string().nullable(),
// #67 list glyphs — flags which sessions open into a rich detail.
hasRoute: z.boolean(),
hasHrSeries: z.boolean(),
})
.meta({ id: "WorkoutListEntry" });
@@ -89,6 +92,61 @@ const workoutHrSeries = z
})
.meta({ id: "WorkoutHrSeries" });
// #67 — per-workout HR curve, one DTO with explicit provenance. Stored
// `WorkoutSamples` series first, raw PULSE-window reconstruction second.
const workoutHrCurve = z
.object({
source: z.enum(["workout_series", "pulse_window"]),
bucketSec: z.number().int().positive(),
points: z.array(
z.object({
tSec: z.number().int().nonnegative(),
mean: z.number().int(),
min: z.number().int(),
max: z.number().int(),
}),
),
envelope: z.boolean(),
})
.meta({ id: "WorkoutHrCurve" });
// #67 — effort-zone distribution. WHOOP device durations win; else a
// %HRmax fold from the HR curve when profile age exists.
const workoutZones = z
.object({
model: z.enum(["whoop", "tanaka"]),
hrMax: z.number().int().nullable(),
zones: z.array(
z.object({
zone: z.number().int().min(1).max(5),
lowBpm: z.number().int().nullable(),
highBpm: z.number().int().nullable(),
seconds: z.number().int().nonnegative(),
}),
),
})
.meta({ id: "WorkoutZones" });
// #67 — per-kilometre splits, derived server-side from geometry +
// timestamps so the raw timestamp blob can be dropped under `compact=1`.
const workoutSplit = z
.object({
km: z.number().int().positive(),
durationSec: z.number().int().nonnegative(),
paceSecPerKm: z.number().int().nonnegative(),
})
.meta({ id: "WorkoutSplit" });
// #67 — own-history average for the sport (comparison line).
const workoutSportContext = z
.object({
count: z.number().int().nonnegative(),
avgDurationSec: z.number().int().nonnegative(),
avgDistanceM: z.number().nullable(),
avgAvgHr: z.number().int().nullable(),
})
.meta({ id: "WorkoutSportContext" });
const workoutDetailResponse = z
.object({
id: z.string(),
@@ -109,6 +167,15 @@ const workoutDetailResponse = z
metadata: z.unknown().nullable(),
route: workoutRouteGeometry.nullable(),
samples: workoutHrSeries.nullable(),
// #67 enrichment — additive; absent from a pre-enrichment client's
// expectations, opt-in `compact=1` only trims the raw blobs above.
hrSeries: workoutHrCurve.nullable(),
zones: workoutZones.nullable(),
splits: z.array(workoutSplit).nullable(),
sportContext: workoutSportContext.nullable(),
// Reserved Activity-Insight seam — always null until the Phase-2 job
// populates it. Typed here so the wire contract is stable in advance.
aiInsight: z.null(),
canonicalId: z.string(),
})
.meta({ id: "WorkoutDetailResponse" });
@@ -147,9 +214,12 @@ export const workoutPaths: NonNullable<ZodOpenApiObject["paths"]> = {
tags: ["Measurements"],
summary: "Workout detail (v1.4.32)",
description:
"Single-workout envelope. Owns the optional `WorkoutRoute` GeoJSON geometry + `canonicalId` pointer that resolves to the cluster winner so deep-links into non-canonical twin rows can redirect cleanly. Cross-user rows surface as 404 (existence channel sealed).",
"Single-workout envelope. Owns the optional `WorkoutRoute` GeoJSON geometry + `canonicalId` pointer that resolves to the cluster winner so deep-links into non-canonical twin rows can redirect cleanly. Additive enrichment fields (`hrSeries`, `zones`, `splits`, `sportContext`, reserved `aiInsight`) are computed server-side. `compact=1` (sent by the web client) drops the raw `samples.samples` HR blob and `route.sampleTimestamps` array from the response; without it the payload is byte-identical to the v1.4.32 contract. Cross-user rows surface as 404 (existence channel sealed).",
requestParams: {
path: z.object({ id: z.string() }),
query: z.object({
compact: z.enum(["1"]).optional(),
}),
},
responses: {
"200": {