feat(mental-health): opt-in PHQ-9 / GAD-7 screeners with item-9 crisis signposting

Add the validated mental-health self-assessment surface, beside mood tracking
(never replacing it) and off by default:

- MentalHealthAssessment stores per-item answers in a single AES-256-GCM Bytes
  blob (registered for key rotation); only the server-authoritative total,
  severity band, and item-9 flag are denormalised. The total projects to a
  PHQ9_SCORE / GAD7_SCORE measurement row so the trend rides existing infra
  without ever exposing item content.
- Item-9 safety: any non-zero PHQ-9 self-harm answer surfaces a calm,
  locale-aware crisis-resource set (DE: TelefonSeelsorge 0800 111 0 111 / 112;
  international fallback) and stamps crisisShownAt. No clinical interpretation,
  no AI ingestion of item content, no third-party alerting.
- API + OpenAPI: POST/GET /api/mental-health/assessments; the response excludes
  raw item answers by construction. Required Pfizer/PHQ attribution lives in the
  instrument module, rendered verbatim.

The screener scores are kept off the Coach snapshot and MCP surfaces, and out of
exports by default — item content never reaches the AI pipeline.
This commit is contained in:
Marc-André Bombeck committed 2026-06-28 15:47:39 +02:00
1 parent e4875db93e
commit 7575275d7e
11 files changed
+655

No files matched your search

+44
View File
@@ -0,0 +1,44 @@
/**
* v1.25 — request/response validation for the opt-in mental-health screeners
* (PHQ-9 / GAD-7). The item answers are 0–3 integers; the array length must
* match the instrument (PHQ-9 = 9, GAD-7 = 7). `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";
export const assessmentInstrumentEnum = z.enum(["PHQ9", "GAD7"]);
const itemAnswer = z.number().int().min(0).max(3);
export const createAssessmentSchema = z
.object({
instrument: assessmentInstrumentEnum,
/** Per-item answers, each 0–3, 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).optional(),
/** Locale of the validated wording actually presented. */
locale: z.string().max(16).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`,
});
}
});
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>;