feat(schema): Workout + WorkoutRoute tables for HKWorkout passthrough (Migration 0053)

Locks the workout-ingest contract before the v1.5 iOS-Swift session.
v1.4.25 ships no UI surface for workouts beyond the VO2-max tile
landing in W8d.5; the table layout is in place so the iOS DTO can
be generated against it and the v1.4.26 XML / Strava workers can
target the same shape.

Schema highlights (full rationale in
.planning/research/w8d-implementation-outline.md §4):

  - Typed columns for every hot-path metric (sport, duration, energy,
    distance, HR avg/max/min, steps, elevation, pause). HKWorkout-
    shaped 1:1, so the iOS DTO needs zero glue. Withings v2/measure
    getworkouts maps cleanly modulo `hr_zone_0..3` (-> metadata).
  - Open `metadata Json?` blob for the long tail (HK metadata bag,
    Withings HR-zone breakdown, device bundle id).
  - `sportType` is TEXT, not a Postgres enum — Apple alone carries
    70+ HKWorkoutActivityType values and the tail only grows. Adding
    a new sport is a Zod refinement, never a Postgres migration.
  - Composite unique `(userId, source, externalId)` for ingest dedup;
    Postgres NULL-distinct semantics keep manual entries non-colliding.
  - WorkoutRoute is 1:1 with Workout, FK on workoutId with cascade
    delete. Geometry is GeoJSON LineString in JSONB (no PostGIS
    dependency — v1.4.20 set the same precedent for correlations).
    Per-sample timestamps + speed/HR ride in `sample_timestamps` and
    stay parallel to the coordinate array.

New module src/lib/validations/workout.ts:
  - workoutSportTypeEnum: 20-member roster covering ≥98% of typical
    workouts in the open-source corpora referenced in the outline.
  - geoJsonLineStringSchema: RFC 7946 §3.1.4 with optional altitude
    component; ≥2 points, lon ∈ [-180, 180], lat ∈ [-90, 90].
  - workoutRouteSamplesSchema: parallel-array timestamp + speed + HR.
  - createWorkoutSchema: full HKWorkout-shaped payload Zod for the
    eventual POST /api/measurements/batch?kind=workout endpoint.

13 unit tests cover the happy path (Apple Health full payload), the
minimal-payload defaults, sport-type rejection, GeoJSON validation
(Point rejected, single-point LineString rejected, OOB coordinates
rejected), and route-sample edge cases. No ingest route ships in
v1.4.25 — the schema is the contract.
This commit is contained in:
Marc-André Bombeck committed 2026-05-14 15:57:39 +02:00
1 parent 89fb3bcc6c
commit 5d6f0c3110
4 files changed
+435

No files matched your search

@@ -0,0 +1,170 @@
import { describe, expect, it } from "vitest";
import {
createWorkoutSchema,
geoJsonLineStringSchema,
workoutRouteSamplesSchema,
workoutSportTypeEnum,
type CreateWorkoutInput,
} from "../workout";
describe("workoutSportTypeEnum", () => {
it("accepts every documented sport", () => {
for (const sport of [
"walking",
"running",
"cycling",
"swimming",
"hiit",
"other",
]) {
expect(workoutSportTypeEnum.parse(sport)).toBe(sport);
}
});
it("rejects an unknown sport", () => {
expect(() => workoutSportTypeEnum.parse("teleportation")).toThrow();
});
});
describe("geoJsonLineStringSchema", () => {
it("accepts a valid GeoJSON LineString with lon/lat pairs", () => {
const parsed = geoJsonLineStringSchema.parse({
type: "LineString",
coordinates: [
[11.077, 49.452],
[11.078, 49.453],
],
});
expect(parsed.type).toBe("LineString");
expect(parsed.coordinates).toHaveLength(2);
});
it("accepts coordinates with an altitude component", () => {
const parsed = geoJsonLineStringSchema.parse({
type: "LineString",
coordinates: [
[11.077, 49.452, 320.5],
[11.078, 49.453, 322.1],
],
});
expect(parsed.coordinates[0]).toHaveLength(3);
});
it("rejects a Point geometry", () => {
expect(() =>
geoJsonLineStringSchema.parse({
type: "Point",
coordinates: [11.077, 49.452],
}),
).toThrow();
});
it("rejects a single-point LineString", () => {
expect(() =>
geoJsonLineStringSchema.parse({
type: "LineString",
coordinates: [[11.077, 49.452]],
}),
).toThrow(/at least 2 points/);
});
it("rejects out-of-bounds longitude / latitude", () => {
expect(() =>
geoJsonLineStringSchema.parse({
type: "LineString",
coordinates: [
[200, 49.452],
[201, 49.453],
],
}),
).toThrow();
expect(() =>
geoJsonLineStringSchema.parse({
type: "LineString",
coordinates: [
[11.077, 200],
[11.078, 201],
],
}),
).toThrow();
});
});
describe("workoutRouteSamplesSchema", () => {
it("accepts an array of timestamp + optional speed/hr entries", () => {
const parsed = workoutRouteSamplesSchema.parse([
{ t: "2026-05-14T07:00:00.000Z", speedMs: 3.2, hr: 142 },
{ t: "2026-05-14T07:00:05.000Z" },
]);
expect(parsed).toHaveLength(2);
});
it("rejects negative speed", () => {
expect(() =>
workoutRouteSamplesSchema.parse([
{ t: "2026-05-14T07:00:00.000Z", speedMs: -1 },
]),
).toThrow();
});
});
describe("createWorkoutSchema", () => {
const minimalRun: Record<string, unknown> = {
sportType: "running",
startedAt: "2026-05-14T06:30:00.000Z",
endedAt: "2026-05-14T07:15:00.000Z",
};
it("accepts a minimal workout payload", () => {
const parsed = createWorkoutSchema.parse(minimalRun);
expect(parsed.sportType).toBe("running");
expect(parsed.startedAt).toBeInstanceOf(Date);
expect(parsed.endedAt).toBeInstanceOf(Date);
expect(parsed.source).toBe("MANUAL");
});
it("accepts an Apple-Health-shaped HKWorkout payload", () => {
const input: Record<string, unknown> = {
sportType: "running",
startedAt: "2026-05-14T06:30:00.000Z",
endedAt: "2026-05-14T07:15:00.000Z",
totalEnergyKcal: 412.3,
totalDistanceM: 7_800,
avgHeartRate: 154,
maxHeartRate: 178,
minHeartRate: 92,
source: "APPLE_HEALTH",
externalId: "B5F8-...-A3",
metadata: { HKAverageMETs: 8.4, sourceBundleId: "com.apple.health" },
route: {
geometry: {
type: "LineString",
coordinates: [
[11.077, 49.452, 320.5],
[11.078, 49.453, 322.1],
],
},
sampleTimestamps: [
{ t: "2026-05-14T06:30:00.000Z", speedMs: 3.2, hr: 142 },
{ t: "2026-05-14T06:30:05.000Z", speedMs: 3.3, hr: 144 },
],
},
};
const parsed: CreateWorkoutInput = createWorkoutSchema.parse(input);
expect(parsed.source).toBe("APPLE_HEALTH");
expect(parsed.totalDistanceM).toBe(7_800);
expect(parsed.route?.geometry.coordinates).toHaveLength(2);
});
it("rejects an unknown sportType", () => {
expect(() =>
createWorkoutSchema.parse({ ...minimalRun, sportType: "fartlek" }),
).toThrow();
});
it("rejects a max heart rate below the resting floor", () => {
expect(() =>
createWorkoutSchema.parse({ ...minimalRun, maxHeartRate: 5 }),
).toThrow();
});
});
+110
View File
@@ -0,0 +1,110 @@
import { z } from "zod/v4";
import { measurementSourceEnum } from "./measurement";
/**
* Workout sport-type union.
*
* Stored as a TEXT column at the DB layer (see `Workout.sport_type` in
* `prisma/schema.prisma`) rather than a Postgres enum. Apple alone has
* 70+ `HKWorkoutActivityType` values and the long tail (paddle / row /
* ski / etc.) only grows release-on-release. A Zod `enum` here gives
* compile-time exhaustiveness without making every new sport a Postgres
* migration. Adding a new sport: append the literal to this union and
* any source-specific code that maps to it (e.g. an HK numeric-code →
* union entry in `apple-health-mapping.ts`).
*
* The initial roster covers ≥98% of typical workouts observed across
* the open-source Apple Health corpora referenced in the W8d research
* outline. Anything not in the list lands as `"other"` until promoted
* to a first-class member.
*/
export const workoutSportTypeEnum = z.enum([
"walking",
"running",
"cycling",
"hiking",
"swimming",
"rowing",
"elliptical",
"stairClimber",
"yoga",
"mindAndBody",
"strength",
"hiit",
"dance",
"golf",
"tennis",
"basketball",
"soccer",
"crossTraining",
"mixedCardio",
"other",
]);
export type WorkoutSportType = z.infer<typeof workoutSportTypeEnum>;
/**
* GeoJSON LineString — the WorkoutRoute.geometry shape. RFC 7946 §3.1.4
* with one HealthLog-specific allowance: the altitude component on
* each coordinate is optional. Apple HKWorkoutRoute carries it; some
* GPX imports do not.
*/
export const geoJsonLineStringSchema = z.object({
type: z.literal("LineString"),
coordinates: z
.array(
z
.tuple([z.number().min(-180).max(180), z.number().min(-90).max(90)])
.rest(z.number()),
)
.min(2, "LineString requires at least 2 points"),
});
export type GeoJsonLineString = z.infer<typeof geoJsonLineStringSchema>;
/**
* Per-sample timestamp + speed companion to the LineString. Parallel
* to `coordinates` — same length, one entry per point. NULL at the
* column level when the source only ships static GPX (Withings).
*/
export const workoutRouteSamplesSchema = z.array(
z.object({
t: z.iso.datetime({ offset: true }),
speedMs: z.number().min(0).max(50).optional(),
hr: z.number().int().min(20).max(300).optional(),
}),
);
export type WorkoutRouteSamples = z.infer<typeof workoutRouteSamplesSchema>;
/**
* Workout insert payload — the shape `POST /api/measurements/batch?kind=workout`
* will accept once that endpoint lands (v1.5). Defined here so the iOS
* Swift session can generate its DTO against the locked contract and
* the v1.4.26 XML import worker has the same target.
*/
export const createWorkoutSchema = z.object({
sportType: workoutSportTypeEnum,
startedAt: z.iso.datetime({ offset: true }).transform((s) => new Date(s)),
endedAt: z.iso.datetime({ offset: true }).transform((s) => new Date(s)),
totalEnergyKcal: z.number().min(0).max(50000).optional(),
totalDistanceM: z.number().min(0).max(1_000_000).optional(),
avgHeartRate: z.number().int().min(20).max(300).optional(),
maxHeartRate: z.number().int().min(20).max(300).optional(),
minHeartRate: z.number().int().min(20).max(300).optional(),
stepCount: z.number().int().min(0).max(200_000).optional(),
elevationM: z.number().min(-500).max(10_000).optional(),
pauseDurationSec: z.number().int().min(0).max(86_400).optional(),
source: measurementSourceEnum.optional().default("MANUAL"),
externalId: z.string().max(128).optional(),
externalSourceVersion: z.string().max(64).optional(),
metadata: z.record(z.string(), z.unknown()).optional(),
route: z
.object({
geometry: geoJsonLineStringSchema,
sampleTimestamps: workoutRouteSamplesSchema.optional(),
})
.optional(),
});
export type CreateWorkoutInput = z.infer<typeof createWorkoutSchema>;