feat(insights): add composite scores, score-anatomy view, and correlation discovery

Build the composite tier of the derived-metrics layer on the shared seam:

- Sleep score — a transparent 0–100 composite from sufficiency, efficiency,
  consistency, timing and composition sub-scores over the per-stage sleep
  rows, reweighting around any sub-score the data cannot support (a legacy
  asleep-only night drops composition gracefully rather than fabricating it).
- Wellness/readiness index — extends the health-score null-redistribution
  blend with resting-HR, HRV (SDNN), sleep, respiratory-rate and mood
  deviation-from-baseline components; returns insufficient below two present
  components so it never headlines from one signal.
- Coincident-deviation flag — counts vitals outside their personal band on
  the latest day and fires when two or more coincide, listing the
  contributing vitals as possible factors, never a cause or a diagnosis.

Each composite cites its standard, carries coverage + confidence +
provenance, and reweights around missing inputs.

Add an FDR-controlled correlation discovery engine behind
GET /api/insights/correlations: it scans a curated behaviour x outcome
matrix, lag-joins each behaviour day to the next day's outcome, runs Pearson
with the exact Student-t p-value, and applies Benjamini-Hochberg control
across every tested pair so only statistically-defensible patterns surface —
each tagged with n, r, p and the adjusted q, framed descriptive not causal.

Add the score-anatomy detail view at /insights/scores/<metric>: a full
score ring, ranked contributor rows each showing its push/pull and weight
share, and the cited-standard provenance explainer — reused by every
composite, mobile-first and accessible.

Regenerate the OpenAPI contract for the new metric values + the correlation
discovery response, and add the i18n keys across all six locales.
This commit is contained in:
Marc-André Bombeck committed 2026-06-02 21:19:56 +02:00
1 parent 663a3ee09d
commit 95a2a7692f
29 files changed
+3087 -30

No files matched your search

+72
View File
@@ -0,0 +1,72 @@
"use client";
import { useQuery } from "@tanstack/react-query";
import { useAuth } from "@/hooks/use-auth";
import { queryKeys } from "@/lib/query-keys";
import type {
DerivedConfidence,
DerivedCoverage,
DerivedProvenance,
} from "@/lib/insights/derived/types";
/**
* v1.10.0 — client loader for one derived wellness metric.
*
* Reads the flat `Derived<T>` envelope off `/api/insights/derived?metric=…`
* (the same shape the score-anatomy view + iOS decode). Pure compute on the
* server — sub-second on a warm rollup tenant — so the hook bounds the fetch
* on an 8 s client ceiling (a slow response means a degraded network, not a
* provider call), keeps a 60 s `staleTime`, and never inline-retries.
*
* `T` is the metric-specific value shape (e.g. `ReadinessValue`,
* `SleepScoreValue`); the caller supplies it so the anatomy view stays
* strongly typed without a second cast.
*/
const DERIVED_TIMEOUT_MS = 8_000;
/** The flat wire shape the derived route returns inside `{ data }`. */
export interface DerivedMetricEnvelope<T> {
metric: string;
status: "ok" | "insufficient";
value: T | null;
coverage: DerivedCoverage;
confidence: DerivedConfidence | null;
provenance: DerivedProvenance;
reason: string | null;
}
export function useDerivedMetric<T>(
metric: string,
options: { type?: string; enabled?: boolean } = {},
) {
const { isAuthenticated } = useAuth();
const enabled = (options.enabled ?? true) && isAuthenticated && metric !== "";
return useQuery({
queryKey: queryKeys.insightsDerivedMetric(metric, options.type),
queryFn: async (): Promise<DerivedMetricEnvelope<T>> => {
const controller = new AbortController();
const timeoutHandle = setTimeout(
() => controller.abort(),
DERIVED_TIMEOUT_MS,
);
try {
const params = new URLSearchParams({ metric });
if (options.type) params.set("type", options.type);
const res = await fetch(`/api/insights/derived?${params.toString()}`, {
signal: controller.signal,
});
if (!res.ok) throw new Error("Failed");
const json = (await res.json()) as { data: DerivedMetricEnvelope<T> };
return json.data;
} finally {
clearTimeout(timeoutHandle);
}
},
enabled,
staleTime: 60 * 1000,
retry: 0,
});
}