mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-15 23:12:04 +00:00
Build the Apple-Health-Highlights grid of personal-vital tiles on the
Insights overview, backed by four new pure derived-metric compute
functions over the established seam:
- cardio-fitness band ("Fitness Age" frame) — VO2max placed against the
FRIEND-registry age/sex norm (Kaminsky 2015), surfaced + trended, never
re-derived.
- vascular-age delta — Withings vascular-age vs chronological age, a
relative wellness indicator (Vlachopoulos 2010 PWV framing), no medical
claim.
- HRV (SDNN) balance — reuses the typical-range engine for the band and
places the recent average as balanced / above / below; SDNN never
relabelled RMSSD; cadence-gated.
- BMI from weight + height — exact WHO classification, the fallback when
no device BMI exists.
Each metric carries coverage + confidence + provenance and cites its
standard through the provenance explainer. The dashboard renders one
SparklineDeltaTile per available vital: an absent vital does not render,
a still-building one shows the honest coverage meter rather than a
headline from too little history. Tiles read the generic
/api/insights/derived route through a TanStack Query hook keyed off the
centralised factory.
Regenerates the OpenAPI contract for the two new metric ids and adds the
vitals copy across all six locales.
170 lines
5.1 KiB
TypeScript
170 lines
5.1 KiB
TypeScript
/**
|
||
* v1.10.0 — catalogue metric #9: BMI from weight + height.
|
||
*
|
||
* `computeBmi(userId, profile, opts)` derives body-mass index from the
|
||
* latest `WEIGHT` reading and the profile `heightCm`, as the fallback for
|
||
* users whose device never sent a `BODY_MASS_INDEX` row. When a device BMI
|
||
* exists it is preferred upstream via the source ladder; this metric fills
|
||
* the gap for manual / scale-only data.
|
||
*
|
||
* - **bmi** = kg ÷ m² (exact).
|
||
* - **band** — WHO classification placed on the green/yellow/red
|
||
* vocabulary: 18.5–24.9 normal (green); 25–29.9 overweight OR < 18.5
|
||
* underweight (yellow); ≥ 30 obese (red).
|
||
* - **category** — the WHO label (underweight / normal / overweight /
|
||
* obese) for the framing line.
|
||
*
|
||
* Standard: WHO BMI classification (WHO Technical Report Series 894, 2000,
|
||
* "Obesity: preventing and managing the global epidemic"). BMI is a
|
||
* population screen, not a body-composition measure — `BODY_FAT` /
|
||
* `MUSCLE_MASS` are richer where available.
|
||
*
|
||
* Server-only — reads the latest `WEIGHT` row via Prisma; height comes from
|
||
* the caller's profile. The classification helper is exported pure for the
|
||
* unit tests.
|
||
*/
|
||
import type { MeasurementType } from "@/generated/prisma/client";
|
||
import { prisma } from "@/lib/db";
|
||
import {
|
||
buildInsufficient,
|
||
buildOk,
|
||
deriveCoverage,
|
||
nowProvenanceTimestamp,
|
||
} from "./coverage";
|
||
import type { BaselineProfile } from "./baseline";
|
||
import type { Derived } from "./types";
|
||
|
||
const WEIGHT_TYPE: MeasurementType = "WEIGHT";
|
||
/** A weight reading older than this no longer reflects current BMI. */
|
||
const DEFAULT_WINDOW_DAYS = 90;
|
||
|
||
/** Green/yellow/red placement, same vocabulary as the design-system tokens. */
|
||
export type BmiBand = "green" | "yellow" | "red";
|
||
/** WHO weight-status category. */
|
||
export type BmiCategory = "underweight" | "normal" | "overweight" | "obese";
|
||
|
||
/** The successful `value` payload for the BMI metric. */
|
||
export interface BmiValue {
|
||
/** Body-mass index (kg/m²). */
|
||
bmi: number;
|
||
/** WHO weight-status category. */
|
||
category: BmiCategory;
|
||
/** Band placement for the colour grammar. */
|
||
band: BmiBand;
|
||
/** The weight that backed the value (kg). */
|
||
weightKg: number;
|
||
/** The height used (cm). */
|
||
heightCm: number;
|
||
}
|
||
|
||
/** WHO category + band for a BMI value. Pure. */
|
||
export function classifyBmi(bmi: number): {
|
||
category: BmiCategory;
|
||
band: BmiBand;
|
||
} {
|
||
if (bmi < 18.5) return { category: "underweight", band: "yellow" };
|
||
if (bmi < 25) return { category: "normal", band: "green" };
|
||
if (bmi < 30) return { category: "overweight", band: "yellow" };
|
||
return { category: "obese", band: "red" };
|
||
}
|
||
|
||
/**
|
||
* BMI from weight + height. Returns `insufficient` when the profile has no
|
||
* usable height or no recent weight reading; otherwise an exact `ok` value.
|
||
*/
|
||
export async function computeBmi(
|
||
userId: string,
|
||
profile: BaselineProfile,
|
||
opts?: { windowDays?: number; now?: Date },
|
||
): Promise<Derived<BmiValue>> {
|
||
const now = opts?.now ?? new Date();
|
||
const windowDays = opts?.windowDays ?? DEFAULT_WINDOW_DAYS;
|
||
const computedAt = nowProvenanceTimestamp(now);
|
||
const heightCm = profile.heightCm ?? null;
|
||
|
||
// No usable height → cannot derive BMI; name height as the missing input.
|
||
if (heightCm == null || !Number.isFinite(heightCm) || heightCm <= 0) {
|
||
const { coverage } = deriveCoverage({
|
||
requiredInputs: 2,
|
||
presentInputs: 0,
|
||
historyDays: 0,
|
||
missing: [WEIGHT_TYPE, "HEIGHT"],
|
||
fullHistoryDays: 1,
|
||
});
|
||
return buildInsufficient<BmiValue>({
|
||
coverage,
|
||
provenance: {
|
||
inputs: [WEIGHT_TYPE, "HEIGHT"],
|
||
source: "none",
|
||
windowDays,
|
||
computedAt,
|
||
},
|
||
reason: "no_height_on_profile",
|
||
});
|
||
}
|
||
|
||
const since = new Date(now.getTime() - windowDays * 24 * 60 * 60 * 1000);
|
||
const latest = await prisma.measurement.findFirst({
|
||
where: {
|
||
userId,
|
||
type: WEIGHT_TYPE,
|
||
deletedAt: null,
|
||
measuredAt: { gte: since },
|
||
},
|
||
orderBy: { measuredAt: "desc" },
|
||
select: { value: true },
|
||
});
|
||
|
||
if (!latest) {
|
||
// Height present but no recent weight → missing the weight input only.
|
||
const { coverage } = deriveCoverage({
|
||
requiredInputs: 2,
|
||
presentInputs: 1,
|
||
historyDays: 0,
|
||
missing: [WEIGHT_TYPE],
|
||
fullHistoryDays: 1,
|
||
});
|
||
return buildInsufficient<BmiValue>({
|
||
coverage,
|
||
provenance: {
|
||
inputs: ["HEIGHT"],
|
||
source: "none",
|
||
windowDays,
|
||
computedAt,
|
||
},
|
||
reason: "no_weight_in_window",
|
||
});
|
||
}
|
||
|
||
const weightKg = latest.value;
|
||
const heightM = heightCm / 100;
|
||
const bmi = weightKg / (heightM * heightM);
|
||
const { category, band } = classifyBmi(bmi);
|
||
|
||
const { coverage, confidence } = deriveCoverage({
|
||
requiredInputs: 2,
|
||
presentInputs: 2,
|
||
historyDays: 1,
|
||
missing: [],
|
||
fullHistoryDays: 1,
|
||
});
|
||
|
||
return buildOk<BmiValue>({
|
||
value: {
|
||
bmi: Math.round(bmi * 10) / 10,
|
||
category,
|
||
band,
|
||
weightKg,
|
||
heightCm,
|
||
},
|
||
coverage,
|
||
confidence,
|
||
provenance: {
|
||
inputs: [WEIGHT_TYPE, "HEIGHT"],
|
||
source: "live",
|
||
windowDays,
|
||
computedAt,
|
||
},
|
||
});
|
||
}
|