/** * The immunization log, with both backup ends in one file. * * Same arrangement as `visits-backup.ts` and for the same reason: a reader * asking "is this carried at both ways?" answers it here, and a reader who * greps only the restore ROUTE gets a false negative because the route * delegates. * * Two models ride: the dose and the link that keeps the scanned Impfpass page * beside it. Both are carried rather than owed. `DocumentConditionLink` on the * debt register says what the alternative costs — documents and conditions * both restore, the filing between them does not — and an immunization history * is the record with the least chance of being reconstructed from anywhere * else, so the same regret is not repeated here. * * Each model uses its own named select constant and its own delegate call * rather than riding a parent's `include`: `documentLinks` is a relation field * name on three different models now, so a relation-shaped write would be * attributed to whichever of them a matcher happened to find first. * * Three references need care on the way back: * * - `practitionerId` and `encounterId` point at models that restore in the * same run. They remap to the restored rows, and drop to NULL when the * file references a row it does not carry. * - `reminderId` points at a `MeasurementReminder`, which is on the * coverage-pending register and does not come back. It resolves to NULL, * never to a dangling id, and the drop is reported. * - `antigenSlug` is restored verbatim with no validation against the * current catalogue. A slug this release no longer resolves must still * come back; the renderer degrades to the free-text arm, which is the * guarantee `src/lib/vaccinations/__tests__/catalog-integrity.test.ts` * holds. */ import { Buffer } from "node:buffer"; import type { Prisma, PrismaClient } from "@/generated/prisma/client"; import type { VaccinationSite } from "@/generated/prisma/client"; import { recordUnknownKeys, type RestoreSkipLog, } from "@/lib/export/restore-skips"; export interface VaccinationsBackupOptions { purpose?: "portable-export" | "disaster-recovery"; } /** One administered dose, as the Pass recorded it. */ export interface VaccinationBackupEntry { /** Always carried: the document link addresses a dose by it. */ id: string; occurredAt: string; /** * Carried verbatim, never checked against the catalogue this release ships. * A slug that stopped resolving still describes what the person was given. */ antigenSlug: string | null; vaccineName: string | null; doseNumber: number | null; seriesDoses: number | null; lotNumber: string | null; site: VaccinationSite | null; practitionerId: string | null; encounterId: string | null; /** * Carried so the loss is visible in the file rather than inferred from its * absence. The restore resolves it to NULL and names the drop: the reminder * it points at is not in the backup. */ reminderId: string | null; /** Base64 ciphertext, carried verbatim — never decrypted into the file. */ noteEncrypted: string | null; createdAt: string; updatedAt: string; deletedAt?: string | null; } /** One edge from a dose to the page it was transcribed from. */ export interface VaccinationDocumentLinkBackupEntry { vaccinationId: string; targetId: string; createdAt: string; } export interface VaccinationsBackupSection { vaccinations: VaccinationBackupEntry[]; vaccinationDocumentLinks: VaccinationDocumentLinkBackupEntry[]; } export interface VaccinationsBackupCounts { vaccinations: number; vaccinationLinks: number; } /** Base64 for a `Bytes` ciphertext column, or null when the column is empty. */ function encodeCiphertext(value: Uint8Array | null): string | null { if (!value || value.byteLength === 0) return null; return Buffer.from(value).toString("base64"); } /** * Named select constants, one per model — a structural matcher binds a model * to the literal beside its delegate call, and an inline object inside a * `Promise.all` is the shape earlier work here had to refactor away from. */ const VACCINATION_BACKUP_SELECT = { id: true, occurredAt: true, antigenSlug: true, vaccineName: true, doseNumber: true, seriesDoses: true, lotNumber: true, site: true, practitionerId: true, encounterId: true, reminderId: true, noteEncrypted: true, createdAt: true, updatedAt: true, deletedAt: true, } as const; const VACCINATION_DOCUMENT_LINK_BACKUP_SELECT = { vaccinationId: true, documentId: true, createdAt: true, } as const; /** * Build the immunization slice of a user's full backup. * * Takes the delegates it uses rather than a whole client, matching the other * section builders. A portable export omits tombstones so a restore cannot * resurrect them; a disaster-recovery payload keeps them so the account comes * back as itself. */ export async function buildVaccinationsBackupSection( prisma: Pick, userId: string, options: VaccinationsBackupOptions = {}, ): Promise { const disasterRecovery = options.purpose === "disaster-recovery"; const [vaccinationRows, documentLinkRows] = await Promise.all([ prisma.vaccinationRecord.findMany({ where: disasterRecovery ? { userId } : { userId, deletedAt: null }, orderBy: { occurredAt: "desc" }, select: VACCINATION_BACKUP_SELECT, }), prisma.vaccinationDocumentLink.findMany({ where: { userId }, orderBy: { createdAt: "asc" }, select: VACCINATION_DOCUMENT_LINK_BACKUP_SELECT, }), ]); return { vaccinations: vaccinationRows.map((row) => ({ id: row.id, occurredAt: row.occurredAt.toISOString(), antigenSlug: row.antigenSlug, vaccineName: row.vaccineName, doseNumber: row.doseNumber, seriesDoses: row.seriesDoses, lotNumber: row.lotNumber, site: row.site, practitionerId: row.practitionerId, encounterId: row.encounterId, reminderId: row.reminderId, noteEncrypted: encodeCiphertext(row.noteEncrypted), createdAt: row.createdAt.toISOString(), updatedAt: row.updatedAt.toISOString(), ...(disasterRecovery ? { deletedAt: row.deletedAt?.toISOString() ?? null } : {}), })), vaccinationDocumentLinks: documentLinkRows.map((row) => ({ vaccinationId: row.vaccinationId, targetId: row.documentId, createdAt: row.createdAt.toISOString(), })), }; } /** Row counts for the audit trail, mirroring the other section counters. */ export function countVaccinationsBackupSection( section: VaccinationsBackupSection, ): VaccinationsBackupCounts { return { vaccinations: section.vaccinations.length, vaccinationLinks: section.vaccinationDocumentLinks.length, }; } /** Counts the immunization restore wiped, for the audit trail. */ export interface VaccinationsRestoreCleared { vaccinations: number; vaccinationLinks: number; } /** * The slice of a parsed backup this restore consumes. * * Required rather than optional: the payload schema defaults every key, so * every caller already satisfies this, and one that stops satisfying it fails * to compile instead of passing `undefined` into a loop that iterates zero * times and reports success. */ export interface VaccinationsRestoreInput { vaccinations: RestoredVaccination[]; vaccinationDocumentLinks: VaccinationDocumentLinkBackupEntry[]; } /** * What the restore reads, as the parsed file actually presents it — a wider * set than what this release writes: a portable export omits the tombstone, * and every optional column arrives as `undefined` rather than `null`. */ type OptionalNullable = { [K in keyof T]?: T[K] | undefined }; export type RestoredVaccination = Pick< VaccinationBackupEntry, "id" | "occurredAt" | "createdAt" | "updatedAt" > & OptionalNullable< Pick< VaccinationBackupEntry, | "antigenSlug" | "vaccineName" | "doseNumber" | "seriesDoses" | "lotNumber" | "site" | "practitionerId" | "encounterId" | "reminderId" | "noteEncrypted" > > & { deletedAt?: string | null }; function decodeCiphertext(encoded: string): Uint8Array { const decoded = Buffer.from(encoded, "base64"); const bytes = new Uint8Array(new ArrayBuffer(decoded.byteLength)); bytes.set(decoded); return bytes; } /** * Re-create the account's immunization log and its document links. * * Delete-then-recreate inside the caller's transaction, matching every other * section. The dose first, then the link, because a link addresses both of its * ends by id. * * MUST be called after the practitioners, encounters and documents have been * restored: the dose remaps two of those references against the database and * the link is written only when the document actually came back. Calling it * earlier would drop every reference and be counted as a successful restore of * a thinner record. */ export async function restoreVaccinationsData( tx: Prisma.TransactionClient, ownerId: string, payload: VaccinationsRestoreInput, skips: RestoreSkipLog, ): Promise { const clearedLinks = await tx.vaccinationDocumentLink.deleteMany({ where: { userId: ownerId }, }); const clearedVaccinations = await tx.vaccinationRecord.deleteMany({ where: { userId: ownerId }, }); // Both far sides are restored by other branches of the same transaction, so // the check is against the database rather than against the payload — this // is the only place that can see all three sections at once. const [practitionerIds, encounterIds] = await Promise.all([ tx.practitioner.findMany({ where: { userId: ownerId }, select: { id: true }, }), tx.encounter.findMany({ where: { userId: ownerId }, select: { id: true }, }), ]); const restoredPractitioners = new Set(practitionerIds.map((row) => row.id)); const restoredEncounters = new Set(encounterIds.map((row) => row.id)); // A row the file references but the restore did not bring back cannot be // invented, and a dangling id would fail the foreign key and roll the whole // restore back over one dose. The reference drops to NULL instead — the // dose, its date, its antigen and its batch code all survive. const droppedPractitioners: string[] = []; const droppedEncounters: string[] = []; // The reminder is on the coverage-pending register: it is not in the file at // all, so every reference to one is a known, reportable drop. const droppedReminders: string[] = []; if (payload.vaccinations.length > 0) { await tx.vaccinationRecord.createMany({ data: payload.vaccinations.map((entry) => { const practitionerId = entry.practitionerId && restoredPractitioners.has(entry.practitionerId) ? entry.practitionerId : null; if (entry.practitionerId && practitionerId === null) { droppedPractitioners.push(entry.practitionerId); } const encounterId = entry.encounterId && restoredEncounters.has(entry.encounterId) ? entry.encounterId : null; if (entry.encounterId && encounterId === null) { droppedEncounters.push(entry.encounterId); } if (entry.reminderId) droppedReminders.push(entry.reminderId); return { id: entry.id, userId: ownerId, occurredAt: new Date(entry.occurredAt), // Verbatim, deliberately: a slug the current catalogue no longer // resolves still describes what was given, and the renderer falls // back to `vaccineName`. antigenSlug: entry.antigenSlug ?? null, vaccineName: entry.vaccineName ?? null, doseNumber: entry.doseNumber ?? null, seriesDoses: entry.seriesDoses ?? null, lotNumber: entry.lotNumber ?? null, site: entry.site ?? null, practitionerId, encounterId, // Never the id the file carried: the row it named is not restored. reminderId: null, noteEncrypted: entry.noteEncrypted == null ? null : decodeCiphertext(entry.noteEncrypted), createdAt: new Date(entry.createdAt), updatedAt: new Date(entry.updatedAt), deletedAt: entry.deletedAt ? new Date(entry.deletedAt) : null, }; }), }); } recordUnknownKeys( skips, "vaccinationReference", [...new Set(droppedPractitioners)], droppedPractitioners, ); recordUnknownKeys( skips, "vaccinationReference", [...new Set(droppedEncounters)], droppedEncounters, ); recordUnknownKeys( skips, "vaccinationReference", [...new Set(droppedReminders)], droppedReminders, ); const restoredVaccinations = new Set( payload.vaccinations.map((entry) => entry.id), ); const documentIds = await tx.inboundDocument.findMany({ where: { userId: ownerId }, select: { id: true }, }); const restoredDocuments = new Set(documentIds.map((row) => row.id)); const writableLinks: Array<{ vaccinationId: string; documentId: string; createdAt: Date; }> = []; const droppedLinks: string[] = []; for (const entry of payload.vaccinationDocumentLinks) { if ( restoredVaccinations.has(entry.vaccinationId) && restoredDocuments.has(entry.targetId) ) { writableLinks.push({ vaccinationId: entry.vaccinationId, documentId: entry.targetId, createdAt: new Date(entry.createdAt), }); } else { droppedLinks.push(entry.targetId); } } if (writableLinks.length > 0) { await tx.vaccinationDocumentLink.createMany({ data: writableLinks.map((row) => ({ userId: ownerId, vaccinationId: row.vaccinationId, documentId: row.documentId, createdAt: row.createdAt, })), }); } recordUnknownKeys( skips, "vaccinationReference", [...new Set(droppedLinks)], droppedLinks, ); return { vaccinations: clearedVaccinations.count, vaccinationLinks: clearedLinks.count, }; }