mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-16 23:33:29 +00:00
feat(labs): merge markers, keep aliases and read lab series per marker
POST /api/biomarkers/{id}/merge folds markers into one in a transaction,
converting readings where the registry knows the units and refusing the
whole merge where it does not; a dry run answers the same result and
writes nothing. Aliases appear on the marker and are edited through the
marker's PUT. Scan and document review rows name the matched marker or
offer up to three, and a chosen marker is remembered as an alias. The
doctor report, FHIR and MCP group readings by marker. Aliases and the
merge ledger travel through backup and restore.
This commit is contained in:
1 parent
a3ce6af9a3
commit
81be73fca8
42 files changed
+1645
-423
No files matched your search
@@ -0,0 +1,56 @@
|
||||
/**
|
||||
* The `Biomarker` DTO, one shape for the list, the detail, the edit and the
|
||||
* merge result. The encrypted context bytes are never echoed: `hasContext`
|
||||
* flags them and `context` carries the plaintext. `aliases` are the other
|
||||
* spellings the marker answers to (v1.43), sorted, without its own name.
|
||||
*/
|
||||
import {
|
||||
decryptContextFromBytes,
|
||||
decryptContextSoft,
|
||||
} from "@/lib/labs/biomarker-store";
|
||||
|
||||
export interface BiomarkerDtoRow {
|
||||
id: string;
|
||||
name: string;
|
||||
unit: string;
|
||||
lowerBound: number | null;
|
||||
upperBound: number | null;
|
||||
panel: string | null;
|
||||
analyteKey: string | null;
|
||||
hidden: boolean;
|
||||
contextEncrypted: Uint8Array | null;
|
||||
createdAt: Date;
|
||||
updatedAt: Date;
|
||||
}
|
||||
|
||||
/**
|
||||
* `soft` decrypts fail-soft (the list: one bad row must not 500 the catalog);
|
||||
* otherwise a decrypt failure throws so a key gap surfaces on the detail.
|
||||
*/
|
||||
export function serialiseBiomarker(
|
||||
row: BiomarkerDtoRow,
|
||||
aliases: readonly string[],
|
||||
options: { soft?: boolean } = {},
|
||||
) {
|
||||
return {
|
||||
id: row.id,
|
||||
name: row.name,
|
||||
unit: row.unit,
|
||||
lowerBound: row.lowerBound,
|
||||
upperBound: row.upperBound,
|
||||
panel: row.panel,
|
||||
analyteKey: row.analyteKey,
|
||||
hasContext: row.contextEncrypted !== null,
|
||||
context: options.soft
|
||||
? decryptContextSoft(row.contextEncrypted)
|
||||
: row.contextEncrypted
|
||||
? decryptContextFromBytes(row.contextEncrypted)
|
||||
: null,
|
||||
hidden: row.hidden,
|
||||
aliases: [...aliases],
|
||||
createdAt: row.createdAt.toISOString(),
|
||||
updatedAt: row.updatedAt.toISOString(),
|
||||
};
|
||||
}
|
||||
|
||||
export type BiomarkerDto = ReturnType<typeof serialiseBiomarker>;
|
||||
@@ -0,0 +1,388 @@
|
||||
/**
|
||||
* Merge markers into one (D1223): "Alk.P" and "Alkaline Phosphatase" become
|
||||
* one marker with one history.
|
||||
*
|
||||
* The plan and the write are one function, so a dry run answers exactly what
|
||||
* the merge would do: it reads the same rows, converts the same values and
|
||||
* returns the same numbers, and only the write step is skipped.
|
||||
*
|
||||
* What a merge does, in one transaction:
|
||||
* - every reading of every source moves to the target. A reading in a unit
|
||||
* other than the target's is converted with the target's analyte
|
||||
* (`convertLabValue`), together with the windows stamped on it; the value
|
||||
* and unit the report printed stay in `sourceValue` / `sourceUnit` (a
|
||||
* reading that was already converted keeps its original pair). The
|
||||
* reading's own `analyte` stays the name that was printed.
|
||||
* - a pair of units the registry cannot convert refuses the WHOLE merge;
|
||||
* nothing moves, not even the sources that would convert;
|
||||
* - medication efficacy targets follow their marker;
|
||||
* - each source's name and its aliases become aliases of the target
|
||||
* (`MERGE`), unless the target's name or another marker already answers
|
||||
* to that spelling;
|
||||
* - one `biomarker_merges` row per source, and the rows that already pointed
|
||||
* at a source now point at the target, so an id merged twice still finds
|
||||
* where it went;
|
||||
* - the sources are deleted.
|
||||
*
|
||||
* There is no undo. The ledger keeps what a later split would need to know
|
||||
* (which marker, which name, how many readings).
|
||||
*/
|
||||
import type { Prisma } from "@/generated/prisma/client";
|
||||
import { prisma } from "@/lib/db";
|
||||
import { foldForMatch } from "@/lib/i18n/fold-for-match";
|
||||
|
||||
import { matchAnalyteKey } from "./analyte-match";
|
||||
import {
|
||||
BIOMARKER_ALIAS_MAX_LENGTH,
|
||||
aliasNamesByMarker,
|
||||
} from "./biomarker-aliases";
|
||||
import { serialiseBiomarker, type BiomarkerDto } from "./biomarker-dto";
|
||||
import {
|
||||
convertLabRange,
|
||||
convertLabValue,
|
||||
type ConversionRefusal,
|
||||
} from "./unit-conversion/convert";
|
||||
import { sameLabUnit } from "./unit-normalise";
|
||||
|
||||
export type MergeConversion = "none" | "converted" | "refused";
|
||||
|
||||
export interface MergeSourceSummary {
|
||||
id: string;
|
||||
name: string;
|
||||
unit: string;
|
||||
readingCount: number;
|
||||
conversion: MergeConversion;
|
||||
refusal: ConversionRefusal | null;
|
||||
}
|
||||
|
||||
export interface BiomarkerMergeResult {
|
||||
dryRun: boolean;
|
||||
target: BiomarkerDto;
|
||||
sources: MergeSourceSummary[];
|
||||
movedReadings: number;
|
||||
convertedReadings: number;
|
||||
aliasesAdded: string[];
|
||||
mergeId: string | null;
|
||||
}
|
||||
|
||||
export type BiomarkerMergeOutcome =
|
||||
| { kind: "ok"; result: BiomarkerMergeResult }
|
||||
| { kind: "notFound"; ids: string[] }
|
||||
| {
|
||||
kind: "unitMismatch";
|
||||
sources: Array<{
|
||||
id: string;
|
||||
unit: string;
|
||||
targetUnit: string;
|
||||
reason: ConversionRefusal;
|
||||
}>;
|
||||
};
|
||||
|
||||
interface ReadingUpdate {
|
||||
id: string;
|
||||
value: number;
|
||||
unit: string;
|
||||
referenceLow: number | null;
|
||||
referenceHigh: number | null;
|
||||
sourceReferenceLow: number | null;
|
||||
sourceReferenceHigh: number | null;
|
||||
sourceValue: number;
|
||||
sourceUnit: string;
|
||||
}
|
||||
|
||||
/** Thrown inside the transaction to roll it back with the refusal. */
|
||||
class MergeRefused extends Error {
|
||||
constructor(readonly outcome: BiomarkerMergeOutcome) {
|
||||
super("merge refused");
|
||||
}
|
||||
}
|
||||
|
||||
export async function mergeBiomarkers(input: {
|
||||
userId: string;
|
||||
targetId: string;
|
||||
sourceIds: readonly string[];
|
||||
dryRun: boolean;
|
||||
}): Promise<BiomarkerMergeOutcome> {
|
||||
try {
|
||||
return await prisma.$transaction(
|
||||
(tx) => runMerge(tx, input),
|
||||
// A source with a long history updates row by row where it converts.
|
||||
{ timeout: 60_000, maxWait: 10_000 },
|
||||
);
|
||||
} catch (err) {
|
||||
if (err instanceof MergeRefused) return err.outcome;
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
|
||||
async function runMerge(
|
||||
tx: Prisma.TransactionClient,
|
||||
input: {
|
||||
userId: string;
|
||||
targetId: string;
|
||||
sourceIds: readonly string[];
|
||||
dryRun: boolean;
|
||||
},
|
||||
): Promise<BiomarkerMergeOutcome> {
|
||||
const { userId, targetId, sourceIds, dryRun } = input;
|
||||
|
||||
const markers = await tx.biomarker.findMany({
|
||||
where: { userId, id: { in: [targetId, ...sourceIds] } },
|
||||
});
|
||||
const byId = new Map(markers.map((m) => [m.id, m]));
|
||||
const missing = [targetId, ...sourceIds].filter((id) => !byId.has(id));
|
||||
if (missing.length > 0) return { kind: "notFound", ids: missing };
|
||||
const target = byId.get(targetId)!;
|
||||
const sources = sourceIds.map((id) => byId.get(id)!);
|
||||
|
||||
// The target's analyte, derived the way every write path derives it, so a
|
||||
// stale stored key cannot pick the wrong factor.
|
||||
const analyteKey = matchAnalyteKey({ name: target.name, unit: target.unit });
|
||||
|
||||
const readings = await tx.labResult.findMany({
|
||||
where: { userId, biomarkerId: { in: [...sourceIds] } },
|
||||
select: {
|
||||
id: true,
|
||||
biomarkerId: true,
|
||||
value: true,
|
||||
unit: true,
|
||||
referenceLow: true,
|
||||
referenceHigh: true,
|
||||
sourceReferenceLow: true,
|
||||
sourceReferenceHigh: true,
|
||||
sourceValue: true,
|
||||
sourceUnit: true,
|
||||
deletedAt: true,
|
||||
},
|
||||
});
|
||||
|
||||
const summaries: MergeSourceSummary[] = [];
|
||||
const updates: ReadingUpdate[] = [];
|
||||
let movedReadings = 0;
|
||||
// Counted like `readingCount`: the live readings a person sees. A tombstoned
|
||||
// reading moves and converts with them, so an undo brings it back right.
|
||||
let convertedLive = 0;
|
||||
for (const source of sources) {
|
||||
const own = readings.filter((r) => r.biomarkerId === source.id);
|
||||
let converted = 0;
|
||||
let refusal: ConversionRefusal | null = null;
|
||||
for (const reading of own) {
|
||||
// A qualitative reading, or one already in the target's unit, moves as
|
||||
// it is.
|
||||
if (reading.value === null || sameLabUnit(reading.unit, target.unit)) {
|
||||
continue;
|
||||
}
|
||||
const value = convertLabValue({
|
||||
analyteKey,
|
||||
value: reading.value,
|
||||
from: reading.unit,
|
||||
to: target.unit,
|
||||
});
|
||||
const stamped = convertLabRange({
|
||||
analyteKey,
|
||||
low: reading.referenceLow,
|
||||
high: reading.referenceHigh,
|
||||
from: reading.unit,
|
||||
to: target.unit,
|
||||
});
|
||||
const printed = convertLabRange({
|
||||
analyteKey,
|
||||
low: reading.sourceReferenceLow,
|
||||
high: reading.sourceReferenceHigh,
|
||||
from: reading.unit,
|
||||
to: target.unit,
|
||||
});
|
||||
if (!value.ok || !stamped.ok || !printed.ok) {
|
||||
refusal ??= !value.ok
|
||||
? value.reason
|
||||
: !stamped.ok
|
||||
? stamped.reason
|
||||
: !printed.ok
|
||||
? printed.reason
|
||||
: "unknown_unit";
|
||||
continue;
|
||||
}
|
||||
converted += 1;
|
||||
if (reading.deletedAt === null) convertedLive += 1;
|
||||
updates.push({
|
||||
id: reading.id,
|
||||
value: value.value,
|
||||
unit: target.unit,
|
||||
referenceLow: stamped.low,
|
||||
referenceHigh: stamped.high,
|
||||
sourceReferenceLow: printed.low,
|
||||
sourceReferenceHigh: printed.high,
|
||||
// A reading converted on its way in keeps what the report printed.
|
||||
sourceValue: reading.sourceValue ?? reading.value,
|
||||
sourceUnit: reading.sourceUnit ?? reading.unit.trim(),
|
||||
});
|
||||
}
|
||||
const live = own.filter((r) => r.deletedAt === null).length;
|
||||
movedReadings += live;
|
||||
summaries.push({
|
||||
id: source.id,
|
||||
name: source.name,
|
||||
unit: source.unit,
|
||||
readingCount: live,
|
||||
conversion: refusal ? "refused" : converted > 0 ? "converted" : "none",
|
||||
refusal,
|
||||
});
|
||||
}
|
||||
const convertedReadings = convertedLive;
|
||||
|
||||
// The spellings the target gains: each source's name and its aliases, once
|
||||
// each, except what the target's name already is or another marker (not a
|
||||
// source) already answers to.
|
||||
const sourceAliases = await tx.biomarkerAlias.findMany({
|
||||
where: { userId, biomarkerId: { in: [...sourceIds] } },
|
||||
select: { id: true, name: true, nameFolded: true },
|
||||
});
|
||||
const otherAliases = await tx.biomarkerAlias.findMany({
|
||||
where: { userId, biomarkerId: { notIn: [...sourceIds] } },
|
||||
select: { biomarkerId: true, nameFolded: true },
|
||||
});
|
||||
const blocked = new Set(
|
||||
otherAliases
|
||||
.filter((a) => a.biomarkerId !== targetId)
|
||||
.map((a) => a.nameFolded),
|
||||
);
|
||||
const targetAliasFolds = new Set(
|
||||
otherAliases
|
||||
.filter((a) => a.biomarkerId === targetId)
|
||||
.map((a) => a.nameFolded),
|
||||
);
|
||||
const otherMarkerFolds = new Set(
|
||||
(
|
||||
await tx.biomarker.findMany({
|
||||
where: { userId, id: { notIn: [targetId, ...sourceIds] } },
|
||||
select: { name: true },
|
||||
})
|
||||
).map((m) => foldForMatch(m.name)),
|
||||
);
|
||||
const targetFold = foldForMatch(target.name);
|
||||
const added = new Map<string, string>();
|
||||
const consider = (name: string) => {
|
||||
const folded = foldForMatch(name).slice(0, BIOMARKER_ALIAS_MAX_LENGTH);
|
||||
if (!folded || folded === targetFold) return;
|
||||
if (targetAliasFolds.has(folded) || added.has(folded)) return;
|
||||
if (blocked.has(folded) || otherMarkerFolds.has(folded)) return;
|
||||
added.set(folded, name.trim().slice(0, BIOMARKER_ALIAS_MAX_LENGTH));
|
||||
};
|
||||
for (const source of sources) consider(source.name);
|
||||
for (const alias of sourceAliases) consider(alias.name);
|
||||
const aliasesAdded = [...added.values()];
|
||||
|
||||
const refused = summaries.filter((s) => s.conversion === "refused");
|
||||
if (!dryRun && refused.length > 0) {
|
||||
throw new MergeRefused({
|
||||
kind: "unitMismatch",
|
||||
sources: refused.map((s) => ({
|
||||
id: s.id,
|
||||
unit: s.unit,
|
||||
targetUnit: target.unit,
|
||||
reason: s.refusal ?? "unknown_unit",
|
||||
})),
|
||||
});
|
||||
}
|
||||
|
||||
let mergeId: string | null = null;
|
||||
if (!dryRun) {
|
||||
for (const update of updates) {
|
||||
await tx.labResult.update({
|
||||
where: { id: update.id },
|
||||
data: {
|
||||
biomarkerId: targetId,
|
||||
value: update.value,
|
||||
unit: update.unit,
|
||||
referenceLow: update.referenceLow,
|
||||
referenceHigh: update.referenceHigh,
|
||||
sourceReferenceLow: update.sourceReferenceLow,
|
||||
sourceReferenceHigh: update.sourceReferenceHigh,
|
||||
sourceValue: update.sourceValue,
|
||||
sourceUnit: update.sourceUnit,
|
||||
},
|
||||
});
|
||||
}
|
||||
await tx.labResult.updateMany({
|
||||
where: { userId, biomarkerId: { in: [...sourceIds] } },
|
||||
data: { biomarkerId: targetId },
|
||||
});
|
||||
await tx.medicationEfficacyTarget.updateMany({
|
||||
where: { biomarkerId: { in: [...sourceIds] } },
|
||||
data: { biomarkerId: targetId },
|
||||
});
|
||||
// The sources' own alias rows go with the sources; the spellings that
|
||||
// survive are written again on the target below.
|
||||
await tx.biomarkerAlias.deleteMany({
|
||||
where: { userId, id: { in: sourceAliases.map((a) => a.id) } },
|
||||
});
|
||||
if (added.size > 0) {
|
||||
await tx.biomarkerAlias.createMany({
|
||||
data: [...added].map(([nameFolded, name]) => ({
|
||||
userId,
|
||||
biomarkerId: targetId,
|
||||
name,
|
||||
nameFolded,
|
||||
source: "MERGE",
|
||||
})),
|
||||
});
|
||||
}
|
||||
await tx.biomarkerMerge.updateMany({
|
||||
where: { userId, targetBiomarkerId: { in: [...sourceIds] } },
|
||||
data: { targetBiomarkerId: targetId },
|
||||
});
|
||||
const now = new Date();
|
||||
for (const summary of summaries) {
|
||||
const row = await tx.biomarkerMerge.create({
|
||||
data: {
|
||||
userId,
|
||||
targetBiomarkerId: targetId,
|
||||
sourceBiomarkerId: summary.id,
|
||||
sourceName: summary.name.slice(0, BIOMARKER_ALIAS_MAX_LENGTH),
|
||||
readingCount: summary.readingCount,
|
||||
mergedAt: now,
|
||||
},
|
||||
select: { id: true },
|
||||
});
|
||||
mergeId ??= row.id;
|
||||
}
|
||||
await tx.biomarker.deleteMany({
|
||||
where: { userId, id: { in: [...sourceIds] } },
|
||||
});
|
||||
}
|
||||
|
||||
const after = dryRun
|
||||
? target
|
||||
: await tx.biomarker.findUniqueOrThrow({ where: { id: targetId } });
|
||||
const aliases = await aliasNamesByMarker(tx, userId, [after]);
|
||||
|
||||
return {
|
||||
kind: "ok",
|
||||
result: {
|
||||
dryRun,
|
||||
target: serialiseBiomarker(after, aliases.get(after.id) ?? []),
|
||||
sources: summaries,
|
||||
movedReadings,
|
||||
convertedReadings,
|
||||
aliasesAdded,
|
||||
mergeId,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Where a merged marker went: the target of the newest merge that removed
|
||||
* `id`, or null. Chains resolve because a merge re-points the rows that named
|
||||
* its sources.
|
||||
*/
|
||||
export async function mergedInto(
|
||||
userId: string,
|
||||
id: string,
|
||||
): Promise<string | null> {
|
||||
const row = await prisma.biomarkerMerge.findFirst({
|
||||
where: { userId, sourceBiomarkerId: id },
|
||||
orderBy: { mergedAt: "desc" },
|
||||
select: { targetBiomarkerId: true },
|
||||
});
|
||||
return row?.targetBiomarkerId ?? null;
|
||||
}
|
||||
@@ -29,6 +29,11 @@ import {
|
||||
parseReferenceRange,
|
||||
} from "@/lib/labs/parse-reference-range";
|
||||
import { matchAnalyteKey } from "@/lib/labs/analyte-match";
|
||||
import {
|
||||
loadMarkerIndex,
|
||||
matchForReview,
|
||||
type MarkerIndex,
|
||||
} from "@/lib/labs/biomarker-resolve";
|
||||
import { sameLabUnit } from "@/lib/labs/unit-normalise";
|
||||
import { annotate } from "@/lib/logging/context";
|
||||
import {
|
||||
@@ -138,16 +143,18 @@ export async function annotateRow(
|
||||
row: ExtractedRow,
|
||||
reportDate: string | null,
|
||||
tz: string,
|
||||
/** The account's markers and aliases, loaded once per extraction. */
|
||||
markerIndex?: MarkerIndex,
|
||||
): Promise<OcrExtractedRowDto> {
|
||||
const analyte = row.analyte.trim();
|
||||
const takenAt = normaliseDate(row.takenAt) ?? reportDate;
|
||||
const printed = parseReferenceRange(row.referenceText, row.unit);
|
||||
|
||||
// Biomarker match — case-insensitive on the catalog identity, presence-only.
|
||||
const existingBiomarker = await prisma.biomarker.findFirst({
|
||||
where: { userId, name: { equals: analyte, mode: "insensitive" } },
|
||||
select: { id: true, name: true, unit: true },
|
||||
});
|
||||
// v1.43 (D1223) — the marker this name resolves to (name, alias, catalog),
|
||||
// exactly as the commit resolves it, or up to three to choose from.
|
||||
const index = markerIndex ?? (await loadMarkerIndex(prisma, userId));
|
||||
const { match, suggestions } = matchForReview(index, analyte, row.unit);
|
||||
const existingBiomarker = match?.marker ?? null;
|
||||
// The analyte the marker is, so the review can say whether a row in another
|
||||
// unit converts. Derived from the name and unit exactly as the commit derives
|
||||
// it (a stored key is only that derivation, written down), so the review and
|
||||
@@ -171,7 +178,12 @@ export async function annotateRow(
|
||||
where: {
|
||||
userId,
|
||||
deletedAt: null,
|
||||
analyte: { equals: analyte, mode: "insensitive" },
|
||||
// The printed name, or any reading already filed under the marker it
|
||||
// resolves to: an earlier report may have spelled it another way.
|
||||
OR: [
|
||||
{ analyte: { equals: analyte, mode: "insensitive" } },
|
||||
...(existingBiomarker ? [{ biomarkerId: existingBiomarker.id }] : []),
|
||||
],
|
||||
takenAt: labReadingDaySearchRange(takenAt),
|
||||
},
|
||||
select: {
|
||||
@@ -235,6 +247,9 @@ export async function annotateRow(
|
||||
markerUnit: existingBiomarker?.unit ?? null,
|
||||
markerAnalyteKey,
|
||||
duplicateOf,
|
||||
biomarkerId: existingBiomarker?.id ?? null,
|
||||
matchKind: match?.matchKind ?? null,
|
||||
suggestions,
|
||||
};
|
||||
}
|
||||
|
||||
@@ -322,11 +337,12 @@ export async function runOcrExtraction(
|
||||
// hearing about it. A count only: the string is the user's document.
|
||||
let unreadableRanges = 0;
|
||||
const tz = await resolveUserTimezone(args.userId);
|
||||
const markerIndex = await loadMarkerIndex(prisma, args.userId);
|
||||
for (const row of envelope.rows.slice(0, OCR_MAX_ROWS)) {
|
||||
if (isUnreadableRange(parseReferenceRange(row.referenceText, row.unit))) {
|
||||
unreadableRanges += 1;
|
||||
}
|
||||
rows.push(await annotateRow(args.userId, row, reportDate, tz));
|
||||
rows.push(await annotateRow(args.userId, row, reportDate, tz, markerIndex));
|
||||
}
|
||||
|
||||
annotate({
|
||||
@@ -337,6 +353,8 @@ export async function runOcrExtraction(
|
||||
rows: rows.length,
|
||||
duplicates: rows.filter((r) => r.duplicateOf !== null).length,
|
||||
newBiomarkers: rows.filter((r) => r.biomarkerMatch === "new").length,
|
||||
aliasMatches: rows.filter((r) => r.matchKind === "alias").length,
|
||||
catalogMatches: rows.filter((r) => r.matchKind === "catalog").length,
|
||||
unreadableRanges,
|
||||
},
|
||||
});
|
||||
|
||||
Reference in new issue
Block a user