mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-17 07:42:23 +00:00
Migrations 0402 to 0410: AI usage levels, biomarker aliases and merges, medication ingredients (with the supplement label run kind), life circumstance fact kinds, AI sections and AUDIT-C, Dawarich context, the pulse day-mean method, intraday hour buckets, the readable location drop and five relation link tables. Every new column carries its reader or a pending-consumer marker. 0409 refuses to run while any home, location period or stored day still holds a readable location, and names the counts. Locations are read from the sealed copy only; the encryption backfill no longer handles them, and the demo seed writes sealed locations only. The new tables are backed up and wiped, the new sealed columns are in the rotation registry with labels of their own, the AI usage level and the life-circumstance confirmations travel with the backup, and the wellbeing score reads the mental-health screeners only.
105 lines
4.2 KiB
TypeScript
105 lines
4.2 KiB
TypeScript
/**
|
||
* v1.25 — request/response validation for the opt-in mental-health screeners
|
||
* (PHQ-9 / GAD-7; v1.27.9 adds WHO-5 + SCI). The item answers are small
|
||
* integers whose ceiling is instrument-specific (PHQ/GAD 0–3, SCI 0–4,
|
||
* WHO-5 0–5); the array length must match the instrument. `userId` is NEVER
|
||
* a body field — it is narrowed from the session in the handler (CLAUDE.md
|
||
* convention).
|
||
*/
|
||
import { z } from "zod/v4";
|
||
import {
|
||
INSTRUMENTS,
|
||
type InstrumentId,
|
||
} from "@/lib/mental-health/instruments";
|
||
import { assertStableExternalId } from "@/lib/validations/external-id";
|
||
import { isValidTimezone } from "@/lib/tz/format";
|
||
|
||
export const assessmentInstrumentEnum = z.enum(["PHQ9", "GAD7", "WHO5", "SCI"]);
|
||
|
||
/**
|
||
* The mental-health screeners, as opposed to every `AssessmentInstrument`.
|
||
* Since v1.43 the table also stores AUDIT-C (the alcohol section of the life
|
||
* circumstances), which no mental-health surface may list or score: older app
|
||
* builds decode `instrument` against exactly these four values.
|
||
*/
|
||
export const SCREENER_INSTRUMENTS = assessmentInstrumentEnum.options;
|
||
export type ScreenerInstrument = (typeof SCREENER_INSTRUMENTS)[number];
|
||
|
||
export function isScreenerInstrument(
|
||
instrument: string,
|
||
): instrument is ScreenerInstrument {
|
||
return (SCREENER_INSTRUMENTS as readonly string[]).includes(instrument);
|
||
}
|
||
|
||
/**
|
||
* Client provenance for an administration. Closed enum so the column can never
|
||
* carry a free-form label. `WEB` is the in-app questionnaire (the DB default);
|
||
* `IOS` is the native client. Distinct from `MeasurementSource` on purpose — a
|
||
* screener is questionnaire input, not a device sample, so it keeps its own
|
||
* narrow vocabulary.
|
||
*/
|
||
export const assessmentSourceEnum = z.enum(["WEB", "IOS"]);
|
||
|
||
// Structural ceiling — the WHO-5's 0–5 scale is the widest. The exact
|
||
// per-instrument ceiling (PHQ/GAD 3, SCI 4) is enforced in the superRefine
|
||
// below, where the instrument is known.
|
||
const itemAnswer = z.number().int().min(0).max(5);
|
||
|
||
export const createAssessmentSchema = z
|
||
.object({
|
||
instrument: assessmentInstrumentEnum,
|
||
/** Per-item answers, ordered as the instrument presents them. */
|
||
items: z.array(itemAnswer).min(1).max(12),
|
||
/** Optional functional-impairment follow-up (not scored into the total). */
|
||
functionalDifficulty: z.number().int().min(0).max(3).optional(),
|
||
/** ISO instant the screener was taken; defaults to now server-side. */
|
||
takenAt: z.string().datetime().optional(),
|
||
tz: z
|
||
.string()
|
||
.max(64)
|
||
.refine(isValidTimezone, "Invalid IANA timezone")
|
||
.optional(),
|
||
/** Locale of the validated wording actually presented. */
|
||
locale: z.string().max(16).optional(),
|
||
/** Client provenance; defaults to WEB. */
|
||
source: assessmentSourceEnum.optional().default("WEB"),
|
||
/**
|
||
* Optional client-supplied idempotency anchor. When present, a repeat with
|
||
* the same value returns the existing administration instead of minting a
|
||
* duplicate — durable replay protection beyond the 24h idempotency-key
|
||
* window (the native client's outbox). Bounded to the 120-char measurement
|
||
* externalId cap.
|
||
*/
|
||
externalId: z.string().min(1).max(120).optional(),
|
||
})
|
||
.superRefine((val, ctx) => {
|
||
const def = INSTRUMENTS[val.instrument as InstrumentId];
|
||
if (val.items.length !== def.itemCount) {
|
||
ctx.addIssue({
|
||
code: "custom",
|
||
path: ["items"],
|
||
message: `${val.instrument} expects exactly ${def.itemCount} item answers`,
|
||
});
|
||
}
|
||
val.items.forEach((answer, index) => {
|
||
if (answer > def.itemMax) {
|
||
ctx.addIssue({
|
||
code: "custom",
|
||
path: ["items", index],
|
||
message: `${val.instrument} answers range 0–${def.itemMax}`,
|
||
});
|
||
}
|
||
});
|
||
})
|
||
// The replay anchor only protects against a duplicate administration
|
||
// while the id is stable across client launches.
|
||
.superRefine(assertStableExternalId);
|
||
|
||
export const listAssessmentsSchema = z.object({
|
||
instrument: assessmentInstrumentEnum.optional(),
|
||
limit: z.coerce.number().int().min(1).max(200).optional(),
|
||
offset: z.coerce.number().int().min(0).optional(),
|
||
});
|
||
|
||
export type CreateAssessmentInput = z.infer<typeof createAssessmentSchema>;
|