feat(mental-health): record which wording a check-in was answered in

An administration now stores `wording`: `validated` (the published
validated version of the reader's language, the original for English),
`unvalidated_translation` (HealthLog's own translation) or `original_en`
(the English original, chosen by a reader of another language). The
client sends only `englishOriginal`; the server resolves the rest from
the wording registry, so a client cannot claim a validated wording the
registry does not hold. `locale` keeps the reader's language, which
still selects the crisis resources.

Additive migration 0475: a nullable column with no backfill, since which
text earlier rows showed depended on releases since replaced. Every read
returns the field, the OpenAPI contract carries it and `englishOriginal`,
and the disaster-recovery backup carries and restores it (the parity
goldens gain the column; their pinned timestamps move by one step
because the fill writes one more column).

The PHQ-9 item-9 crisis signpost is answered from the answers alone and
is proven in every wording through the real route.
This commit is contained in:
Marc-André Bombeck committed 2026-10-23 08:14:15 +02:00
1 parent 3843705296
commit 02cc0631fa
14 files changed
+347 -66

No files matched your search

@@ -9,6 +9,7 @@
import { z } from "zod/v4";
import { AssessmentInstrument } from "@/generated/prisma/enums";
import { base64BytesSchema, isoDateTime } from "@/lib/export/backup-schema-kit";
import { ASSESSMENT_WORDINGS } from "@/lib/mental-health/wording/types";
/**
* A completed screener administration. `responsesEncrypted` is REQUIRED rather
@@ -22,6 +23,7 @@ export const mentalHealthAssessmentBackupSchema = z
id: z.string().min(1),
instrument: z.enum(AssessmentInstrument),
locale: z.string().min(1),
wording: z.enum(ASSESSMENT_WORDINGS).nullable().optional(),
version: z.string().optional(),
responsesEncrypted: base64BytesSchema,
totalScore: z.number().int(),
+12
View File
@@ -55,6 +55,10 @@
import type { Prisma, PrismaClient } from "@/generated/prisma/client";
import type { AssessmentInstrument } from "@/generated/prisma/client";
import {
isAssessmentWording,
type AssessmentWording,
} from "@/lib/mental-health/wording/types";
export interface SensitiveBackupOptions {
purpose?: "portable-export" | "disaster-recovery";
@@ -65,6 +69,8 @@ export interface MentalHealthAssessmentBackupEntry {
id: string;
instrument: AssessmentInstrument;
locale: string;
/** Which text the answers were given in; null before it was recorded. */
wording: AssessmentWording | null;
version: string;
/** Ciphertext as base64. The per-item answers, including PHQ-9 item 9. */
responsesEncrypted: string;
@@ -146,6 +152,7 @@ const MENTAL_HEALTH_BACKUP_SELECT = {
id: true,
instrument: true,
locale: true,
wording: true,
version: true,
responsesEncrypted: true,
totalScore: true,
@@ -210,6 +217,9 @@ export async function buildSensitiveBackupSection(
id: row.id,
instrument: row.instrument,
locale: row.locale,
// The app writes only the closed set; anything else travels as null
// ("not recorded") rather than as a value the restore would refuse.
wording: isAssessmentWording(row.wording) ? row.wording : null,
version: row.version,
responsesEncrypted: Buffer.from(row.responsesEncrypted).toString(
"base64",
@@ -276,6 +286,7 @@ export type RestoredMentalHealthAssessment = Pick<
Pick<
MentalHealthAssessmentBackupEntry,
| "version"
| "wording"
| "item9Flagged"
| "crisisShownAt"
| "tz"
@@ -326,6 +337,7 @@ export async function restoreSensitiveData(
userId: ownerId,
instrument: entry.instrument,
locale: entry.locale,
wording: entry.wording ?? null,
version: entry.version ?? "standard",
responsesEncrypted: decodeBase64(entry.responsesEncrypted),
totalScore: entry.totalScore,