diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml index 1845aee25..5697416df 100644 --- a/docs/api/openapi.yaml +++ b/docs/api/openapi.yaml @@ -8137,6 +8137,16 @@ paths: locale: type: string maxLength: 16 + source: + default: WEB + type: string + enum: + - WEB + - IOS + externalId: + type: string + minLength: 1 + maxLength: 120 required: - instrument - items diff --git a/prisma/migrations/0221_v125_mental_health_external_id_dedup/migration.sql b/prisma/migrations/0221_v125_mental_health_external_id_dedup/migration.sql new file mode 100644 index 000000000..7630417ff --- /dev/null +++ b/prisma/migrations/0221_v125_mental_health_external_id_dedup/migration.sql @@ -0,0 +1,22 @@ +-- v1.25 — iOS parity: durable dedup for mental-health screener administrations. +-- +-- The native client queues completed check-ins in an outbox and replays them on +-- reconnect. The 24h idempotency-key window covers a fast retry, but a queued +-- entry can replay long after that window closes. Without a stable client key +-- the replay would mint a duplicate administration AND a duplicate *_SCORE trend +-- point. +-- +-- The `source` + `external_id` columns already exist (migration 0213). This adds +-- the DB-level backstop: a partial UNIQUE index over `(user_id, external_id)` +-- restricted to non-NULL externalIds. It deduplicates across sources (a repeat +-- externalId collides regardless of WEB vs IOS), while NULL externalIds (the +-- web path that supplies none) stay unconstrained by the partial predicate. +-- +-- The route pre-checks `(user_id, external_id)` and returns the existing row; +-- this index is the race backstop (a concurrent insert surfaces P2002, which +-- the route catches and resolves to the winning row). Idempotent + forward-only; +-- reversible with `DROP INDEX IF EXISTS "mental_health_assessments_user_external_id_unique"`. + +CREATE UNIQUE INDEX IF NOT EXISTS "mental_health_assessments_user_external_id_unique" + ON "mental_health_assessments" ("user_id", "external_id") + WHERE "external_id" IS NOT NULL; diff --git a/prisma/schema.prisma b/prisma/schema.prisma index 67e260d4d..f10c6427f 100644 --- a/prisma/schema.prisma +++ b/prisma/schema.prisma @@ -1328,6 +1328,12 @@ model MentalHealthAssessment { @@unique([userId, source, externalId]) @@index([userId, instrument, takenAt]) @@index([userId, updatedAt, id]) + // `mental_health_assessments_user_external_id_unique` is a partial UNIQUE + // index over `(user_id, external_id) WHERE external_id IS NOT NULL` — see + // migration 0221. It deduplicates an outbox replay across sources (a repeat + // client externalId returns the existing administration). Prisma can't express + // a partial index in the schema language, so it lives in raw SQL and is + // intentionally omitted here. @@map("mental_health_assessments") } diff --git a/src/app/api/mental-health/assessments/__tests__/route.test.ts b/src/app/api/mental-health/assessments/__tests__/route.test.ts index 40bdc9bea..aba10d668 100644 --- a/src/app/api/mental-health/assessments/__tests__/route.test.ts +++ b/src/app/api/mental-health/assessments/__tests__/route.test.ts @@ -15,7 +15,7 @@ import { NextRequest } from "next/server"; vi.mock("@/lib/db", () => ({ prisma: { appSettings: { findUnique: vi.fn().mockResolvedValue(null) }, - mentalHealthAssessment: { create: vi.fn() }, + mentalHealthAssessment: { create: vi.fn(), findFirst: vi.fn() }, measurement: { create: vi.fn().mockResolvedValue({}) }, }, })); @@ -92,6 +92,10 @@ beforeEach(() => { remaining: 29, resetAt: Date.now(), }); + // No prior administration by default; the dedup test overrides this. + vi.mocked(prisma.mentalHealthAssessment.findFirst).mockResolvedValue( + null as never, + ); }); describe("POST /api/mental-health/assessments", () => { @@ -188,6 +192,75 @@ describe("POST /api/mental-health/assessments", () => { expect(measArg.data.externalId).toBe("assessment:mha_2"); }); + it("dedups a repeat externalId: returns the existing administration, writes nothing new", async () => { + // The outbox replays a queued check-in with the same client externalId. + vi.mocked(prisma.mentalHealthAssessment.findFirst).mockResolvedValue({ + id: "mha_dup", + instrument: "PHQ9", + locale: "en", + version: "standard", + totalScore: 4, + severityBand: "mild", + item9Flagged: false, + crisisShownAt: null, + takenAt: new Date("2026-06-28T00:00:00.000Z"), + createdAt: new Date("2026-06-28T00:00:00.000Z"), + } as never); + + const res = await callPost( + makeReq({ + instrument: "PHQ9", + items: [1, 1, 1, 1, 0, 0, 0, 0, 0], + source: "IOS", + externalId: "outbox-7f3c", + }), + ); + + // Existing row returned (200, not 201) — no duplicate assessment or trend point. + expect(res.status).toBe(200); + const body = (await res.json()) as { + data: { assessment: { id: string } }; + }; + expect(body.data.assessment.id).toBe("mha_dup"); + expect(prisma.mentalHealthAssessment.findFirst).toHaveBeenCalledWith( + expect.objectContaining({ + where: { userId: "user-1", externalId: "outbox-7f3c" }, + }), + ); + expect(prisma.mentalHealthAssessment.create).not.toHaveBeenCalled(); + expect(prisma.measurement.create).not.toHaveBeenCalled(); + }); + + it("persists client provenance + externalId on a first write", async () => { + vi.mocked(prisma.mentalHealthAssessment.create).mockResolvedValue({ + id: "mha_3", + instrument: "GAD7", + locale: "en", + version: "standard", + totalScore: 3, + severityBand: "mild", + item9Flagged: false, + crisisShownAt: null, + takenAt: new Date("2026-06-28T00:00:00.000Z"), + createdAt: new Date("2026-06-28T00:00:00.000Z"), + } as never); + + const res = await callPost( + makeReq({ + instrument: "GAD7", + items: [1, 1, 1, 0, 0, 0, 0], + source: "IOS", + externalId: "outbox-aa01", + }), + ); + expect(res.status).toBe(201); + + const createArg = vi.mocked(prisma.mentalHealthAssessment.create).mock + .calls[0][0] as { data: { source: string; externalId: string | null } }; + expect(createArg.data.source).toBe("IOS"); + expect(createArg.data.externalId).toBe("outbox-aa01"); + }); + it("rejects a wrong item count with 422 and never writes", async () => { const res = await callPost( makeReq({ instrument: "PHQ9", items: [1, 2, 3] }), // 3 ≠ 9 diff --git a/src/app/api/mental-health/assessments/route.ts b/src/app/api/mental-health/assessments/route.ts index d98915794..315e547b0 100644 --- a/src/app/api/mental-health/assessments/route.ts +++ b/src/app/api/mental-health/assessments/route.ts @@ -75,6 +75,23 @@ function shapeRow(row: { }; } +// Idempotent replay: return an already-recorded administration in the same +// shape a fresh create returns. The crisis set is re-derived from the stored +// item-9 flag + presented locale — no item content is decrypted. 200 (not 201) +// signals "already exists" to the client. +function respondExisting(row: Parameters[0]): Response { + const def = INSTRUMENTS[row.instrument as InstrumentId]; + const crisis = row.item9Flagged ? crisisResourcesForLocale(row.locale) : null; + return apiSuccess( + { + assessment: shapeRow(row), + actionThreshold: def.actionThreshold, + crisis, + }, + 200, + ); +} + export const GET = apiHandler(async (request: NextRequest) => { const { user } = await requireAuth(); // Opt-in module (default OFF): the screener history is unreachable until the @@ -172,11 +189,45 @@ async function postAssessment(request: NextRequest): Promise { return returnAllZodIssues(parsed.error, 422); } - const { instrument, items, functionalDifficulty, takenAt, tz, locale } = - parsed.data; + const { + instrument, + items, + functionalDifficulty, + takenAt, + tz, + locale, + source, + externalId, + } = parsed.data; const id = instrument as InstrumentId; const def = INSTRUMENTS[id]; + // Durable dedup: a repeat externalId (the native client's outbox replaying a + // queued check-in beyond the 24h idempotency-key window) must return the + // existing administration, never a duplicate row + duplicate trend point. The + // partial unique index on `(user_id, external_id)` is the DB-level backstop + // (migration 0221); this pre-check returns the existing row cleanly without + // relying on a constraint throw. Scoped to the caller — externalId is unique + // per user, not globally. + if (externalId) { + const existing = await prisma.mentalHealthAssessment.findFirst({ + where: { userId: user.id, externalId }, + select: { + id: true, + instrument: true, + locale: true, + version: true, + totalScore: true, + severityBand: true, + item9Flagged: true, + crisisShownAt: true, + takenAt: true, + createdAt: true, + }, + }); + if (existing) return respondExisting(existing); + } + // Server-authoritative scoring (the client never computes these). const total = scoreTotal(items); const band = severityBand(id, total); @@ -193,37 +244,74 @@ async function postAssessment(request: NextRequest): Promise { }), ); - const assessment = await prisma.mentalHealthAssessment.create({ - data: { - userId: user.id, - instrument: id, - locale: presentedLocale, - version: "standard", - responsesEncrypted: blob, - totalScore: total, - severityBand: band, - item9Flagged: flagged, - crisisShownAt: flagged ? new Date() : null, - takenAt: when, - tz: tz ?? null, - source: "WEB", - }, - select: { - id: true, - instrument: true, - locale: true, - version: true, - totalScore: true, - severityBand: true, - item9Flagged: true, - crisisShownAt: true, - takenAt: true, - createdAt: true, - }, - }); + const assessmentSelect = { + id: true, + instrument: true, + locale: true, + version: true, + totalScore: true, + severityBand: true, + item9Flagged: true, + crisisShownAt: true, + takenAt: true, + createdAt: true, + } as const; + + let assessment; + try { + assessment = await prisma.mentalHealthAssessment.create({ + data: { + userId: user.id, + instrument: id, + locale: presentedLocale, + version: "standard", + responsesEncrypted: blob, + totalScore: total, + severityBand: band, + item9Flagged: flagged, + crisisShownAt: flagged ? new Date() : null, + takenAt: when, + tz: tz ?? null, + source, + externalId: externalId ?? null, + }, + select: assessmentSelect, + }); + } catch (err: unknown) { + // Concurrent replay: two requests carrying the same externalId raced past + // the pre-check. The partial unique index (migration 0221) rejects the + // second insert with P2002 — re-fetch the winner and return it idempotently + // rather than surfacing a 500 (the cycle day-log conflict precedent). + if ( + externalId && + typeof err === "object" && + err !== null && + "code" in err && + (err as { code?: unknown }).code === "P2002" + ) { + const winner = await prisma.mentalHealthAssessment.findFirst({ + where: { userId: user.id, externalId }, + select: assessmentSelect, + }); + if (winner) { + annotate({ + action: { name: "mental-health.create.dedup" }, + meta: { instrument: id }, + }); + return respondExisting(winner); + } + } + throw err; + } // Read-optimised projection: the total rides a Measurement row so the existing - // chart/rollup infra reads the trend without ever touching item content. + // chart/rollup infra reads the trend without ever touching item content. The + // externalId anchors the trend point to this administration; duplicate trend + // points are structurally impossible because a replayed externalId returns + // the existing assessment above before reaching this create. `MeasurementSource` + // carries no WEB/IOS member (a screener is questionnaire input, not a device + // sample), so the row stays MANUAL — the WEB/IOS provenance + client + // externalId live on the assessment this row links to. await prisma.measurement.create({ data: { userId: user.id, diff --git a/src/lib/measurements/__tests__/apple-health-mapping.test.ts b/src/lib/measurements/__tests__/apple-health-mapping.test.ts index 66544ea21..d109e739c 100644 --- a/src/lib/measurements/__tests__/apple-health-mapping.test.ts +++ b/src/lib/measurements/__tests__/apple-health-mapping.test.ts @@ -78,15 +78,16 @@ const MEASUREMENT_TYPES_WITHOUT_HK_COUNTERPART = new Set([ // resilience metric. No HK mapping by design. "RESILIENCE", // v1.25 — clinical-signals wave. The mental-health screener totals are - // derived from an in-app questionnaire, and grip strength / pain NRS / waist - // circumference + waist-to-height are manual / instrument readings — none - // ships a first-class HealthKit quantity we ingest, so they have no HK - // mapping by design. + // derived from an in-app questionnaire, and grip strength / pain NRS are + // manual / instrument readings — none ships a first-class HealthKit quantity + // we ingest, so they have no HK mapping by design. Waist-to-height is a + // server-derived ratio (no HK quantity). `WAIST_CIRCUMFERENCE` DOES round- + // trip via `HKQuantityTypeIdentifierWaistCircumference`, so it is NOT listed + // here. "PHQ9_SCORE", "GAD7_SCORE", "GRIP_STRENGTH", "PAIN_NRS", - "WAIST_CIRCUMFERENCE", "WAIST_TO_HEIGHT", ]); @@ -288,6 +289,26 @@ describe("HK_QUANTITY_TYPE_DEFERRED", () => { expect(mapping.convertToDbUnit(0.245)).toBeCloseTo(24.5); }); + it("round-trips waist circumference from HK metres to canonical cm", () => { + const mapping = + APPLE_HEALTH_TYPE_MAP.HKQuantityTypeIdentifierWaistCircumference; + expect(mapping.measurementType).toBe("WAIST_CIRCUMFERENCE"); + expect(mapping.dbUnit).toBe("cm"); + // 0.84 m → 84 cm. + expect(mapping.convertToDbUnit(0.84)).toBeCloseTo(84); + const out = mapAppleHealthEntry({ + hkIdentifier: "HKQuantityTypeIdentifierWaistCircumference", + value: 0.92, + unit: "m", + startDate: "2026-06-28T08:00:00.000Z", + endDate: "2026-06-28T08:00:00.000Z", + }); + expect(out).not.toBeNull(); + expect(out!.type).toBe("WAIST_CIRCUMFERENCE"); + expect(out!.value).toBeCloseTo(92); + expect(out!.unit).toBe("cm"); + }); + it("uses identity conversion for the SI-aligned identifiers", () => { for (const id of [ "HKQuantityTypeIdentifierBodyMass", diff --git a/src/lib/measurements/apple-health-mapping.ts b/src/lib/measurements/apple-health-mapping.ts index d6be7265a..39db69181 100644 --- a/src/lib/measurements/apple-health-mapping.ts +++ b/src/lib/measurements/apple-health-mapping.ts @@ -220,6 +220,22 @@ export const APPLE_HEALTH_TYPE_MAP: Record = { convertToDbUnit: (v) => v, aggregation: "latest", }, + // Waist circumference — HealthKit ships this as a length quantity in the SI + // base unit (metres), the same wire convention the other length identifiers + // follow (`DistanceWalkingRunning`, `WalkingStepLength`). It is the first + // length metric whose canonical DB unit (cm) differs from the metre wire + // unit, so it scales ×100 server-side — the length sibling of the percent + // metrics' ×100 path. WHO risk bands are evaluated in cm at display + // (men > 94 / women > 80; see `norms.ts`). + HKQuantityTypeIdentifierWaistCircumference: { + hkIdentifier: "HKQuantityTypeIdentifierWaistCircumference", + measurementType: "WAIST_CIRCUMFERENCE", + hkUnit: "m", + dbUnit: "cm", + // Apple ships length in metres; HealthLog stores waist in cm. + convertToDbUnit: (v) => v * 100, + aggregation: "latest", + }, // ── Cardiovascular ────────────────────────────────────────── HKQuantityTypeIdentifierBloodPressureSystolic: { diff --git a/src/lib/validations/mental-health.ts b/src/lib/validations/mental-health.ts index 3cd8bfefc..9cd08f999 100644 --- a/src/lib/validations/mental-health.ts +++ b/src/lib/validations/mental-health.ts @@ -12,6 +12,15 @@ import { export const assessmentInstrumentEnum = z.enum(["PHQ9", "GAD7"]); +/** + * 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"]); + const itemAnswer = z.number().int().min(0).max(3); export const createAssessmentSchema = z @@ -26,6 +35,16 @@ export const createAssessmentSchema = z tz: z.string().max(64).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];