Files
HealthLog/src/lib/export/health-score-backup.ts
T
Marc-André Bombeck 333dfe8746 fix(backup): give every export read a total order
Several export reads sorted only by a column two rows can share (a
creation time, a day, a name), and a few to-many reads (medication
schedules, mood tag links, cycle and illness symptom links) had no order
at all. Tied rows then came back in whatever order they sat on disk, so
two exports of one account could differ, and the parity goldens flapped
once the fixture's child rows shared their pinned timestamps.

Each read now ends its order in the model's primary key: the existing
sort key plus `id`, or the remaining key columns of a compound key
(nutrient `source`, hidden tag `moodTagId`, link `symptomId` /
`moodTagId` / `documentId`). Schedules sort by window start, then id.
The restore re-export reads through the same modules, so it inherits
the order.

The parity goldens are unchanged: they already hold the tie-broken
order, so no regeneration was needed and they still pin the output of
the pre-split exporter.

A new integration test runs both purposes, built and streamed, through
a client that records every findMany and every nested to-many read, and
fails on any whose order does not cover the primary key (keys pinned by
an equality in `where`, or by the foreign key to the parent, count as
covered). A second case writes the same tied rows in forward and
reverse physical order and requires byte-identical files.
2026-10-23 00:28:38 +02:00

207 lines
7.5 KiB
TypeScript

/**
* The stored health score days, with both backup ends in one file.
*
* `HealthScoreRecord` looks derived and is not. The live computation answers
* for today from today's rows, so a day whose readings have since been
* corrected, re-synced or simply extended cannot be recomputed as it stood;
* the row is the only copy of the number the account actually saw. Classifying
* it `DERIVED` and leaving it out would produce a restore that comes back with
* a blank history and reports success, which is the shape of defect the
* nutrient day totals, the custom mood tags and the custom cycle symptoms each
* shipped in turn.
*
* The builder and the restore live together deliberately, the way
* `intraday-profile-backup.ts` and `src/lib/cycle/backup.ts` do: a reader
* asking "is this carried at both ends?" answers it in one file, and a reader
* who greps only the restore ROUTE gets a false negative, because the route
* delegates.
*
* Nothing here is encrypted, so there is no portable/disaster-recovery split
* on the values. The only difference between the two purposes is identity: a
* canonical disaster-recovery payload carries the row id and its timestamps so
* the row comes back as itself, a portable export carries the day alone.
*/
import type { Prisma, PrismaClient } from "@/generated/prisma/client";
import type { ScoreBand } from "@/lib/analytics/score/types";
export interface HealthScoreBackupOptions {
purpose?: "portable-export" | "disaster-recovery";
}
/** One local day's score, exactly as it was shown. */
export interface HealthScoreRecordBackupEntry {
/** Present in canonical DR payloads so the row keeps a stable identity. */
id?: string;
/** Local calendar day (`YYYY-MM-DD`) in `timezone`. */
dayKey: string;
/**
* The zone the day was cut on. Carried for the same reason the intraday
* curves carry theirs: an account that moved zones has days of different
* lengths behind it, and a restore that guessed would make them look
* comparable.
*/
timezone: string;
composite: number;
band: ScoreBand;
scoreVersion: number;
composition: string[];
/** Each counted pillar's own score, keyed by pillar id. */
pillarScores: Record<string, number>;
inputFingerprint: string;
configVersion: number | null;
configChangedAt: string | null;
computedAt: string;
createdAt?: string;
}
export interface HealthScoreBackupSection {
healthScoreRecords: HealthScoreRecordBackupEntry[];
}
export interface HealthScoreBackupCounts {
healthScoreRecords: number;
}
/**
* Read the stored score days as JSON-safe entries.
*
* `pillarScores` arrives as an opaque `JsonValue`; it is narrowed here rather
* than cast, so a row holding something other than a flat id-to-number map
* reaches the payload as an empty map instead of as a shape the restore's
* schema would reject at the worst possible moment.
*/
function readPillarScores(value: Prisma.JsonValue): Record<string, number> {
if (typeof value !== "object" || value === null || Array.isArray(value)) {
return {};
}
const out: Record<string, number> = {};
for (const [key, entry] of Object.entries(value)) {
if (typeof entry === "number") out[key] = entry;
}
return out;
}
/**
* Build the stored-score slice of a user's full backup.
*
* Takes the delegate it uses rather than a whole `PrismaClient`, matching the
* other section builders, so the route's global client and the worker's local
* one share one read.
*/
export async function buildHealthScoreBackupSection(
prisma: Pick<PrismaClient, "healthScoreRecord">,
userId: string,
options: HealthScoreBackupOptions = {},
): Promise<HealthScoreBackupSection> {
const disasterRecovery = options.purpose === "disaster-recovery";
// The table carries no tombstone — a day is written once and never deleted
// short of a wipe — so both purposes read the same set.
const rows = await prisma.healthScoreRecord.findMany({
where: { userId },
orderBy: [{ dayKey: "desc" }, { id: "asc" }],
});
return {
healthScoreRecords: rows.map((row) => ({
...(disasterRecovery
? { id: row.id, createdAt: row.createdAt.toISOString() }
: {}),
dayKey: row.dayKey,
timezone: row.timezone,
composite: row.composite,
band: row.band,
scoreVersion: row.scoreVersion,
composition: row.composition,
pillarScores: readPillarScores(row.pillarScores),
inputFingerprint: row.inputFingerprint,
configVersion: row.configVersion,
configChangedAt: row.configChangedAt?.toISOString() ?? null,
computedAt: row.computedAt.toISOString(),
})),
};
}
/** Row counts for the audit trail, mirroring the other section counters. */
export function countHealthScoreBackupSection(
section: HealthScoreBackupSection,
): HealthScoreBackupCounts {
return { healthScoreRecords: section.healthScoreRecords.length };
}
/** Counts the score-record restore wiped, for the audit trail. */
export interface HealthScoreRestoreCleared {
healthScoreRecords: number;
}
/**
* The slice of a parsed backup this restore consumes.
*
* Required rather than optional: `BackupPayload` defaults it, so every caller
* already satisfies this, and a caller that stops satisfying it fails to
* compile instead of passing `undefined` into a loop that iterates zero times
* and reports success.
*/
export interface HealthScoreRestoreInput {
healthScoreRecords: HealthScoreRecordBackupEntry[];
}
/**
* Re-create the account's stored score days.
*
* Delete-then-recreate inside the caller's transaction, matching every other
* section. Note the asymmetry with the live write path next door: THAT one
* yields on conflict, because a second computation of a day it already holds
* must change nothing. This one does not, because the file is the authority
* here and a day it carries twice is a corrupt file, not a race. Two entries
* claiming the same local day therefore throw with a sentence rather than
* letting `skipDuplicates` pick a winner and report success.
*/
export async function restoreHealthScoreData(
tx: Prisma.TransactionClient,
ownerId: string,
payload: HealthScoreRestoreInput,
): Promise<HealthScoreRestoreCleared> {
const cleared = await tx.healthScoreRecord.deleteMany({
where: { userId: ownerId },
});
const seen = new Set<string>();
for (const record of payload.healthScoreRecords) {
if (seen.has(record.dayKey)) {
throw new Error(
`Duplicate health score record for ${record.dayKey}. One account has ` +
"at most one score per local day, and picking a winner here would " +
"silently discard the other reading of that day.",
);
}
seen.add(record.dayKey);
}
if (payload.healthScoreRecords.length > 0) {
await tx.healthScoreRecord.createMany({
data: payload.healthScoreRecords.map((record) => ({
...(record.id ? { id: record.id } : {}),
userId: ownerId,
dayKey: record.dayKey,
timezone: record.timezone,
composite: record.composite,
band: record.band,
scoreVersion: record.scoreVersion,
composition: record.composition,
pillarScores: record.pillarScores as Prisma.InputJsonValue,
inputFingerprint: record.inputFingerprint,
configVersion: record.configVersion,
configChangedAt: record.configChangedAt
? new Date(record.configChangedAt)
: null,
computedAt: new Date(record.computedAt),
...(record.createdAt ? { createdAt: new Date(record.createdAt) } : {}),
})),
});
}
return { healthScoreRecords: cleared.count };
}