feat(documents): review and extract lab values on the document itself

The server chain existed end to end (extract stages PENDING facts, per-fact
edit clears the low-confidence gate, confirm is the only write into the
structured stores) but the document detail offered no control over any of
it: it counted observation facts and linked to Labs. A user whose automatic
staging run was skipped had to re-upload the same PDF through Labs > Scan a
report.

- The detail sheet gains a staged-facts block with honest states: pending
  facts open an inline review (approve/reject per fact; a low-confidence
  fact is checked and saved first via the existing per-fact edit); a
  lab-filed, already-read document with nothing staged offers "Extract lab
  values" over its stored text; otherwise nothing renders.
- The extract route gains { mode: "stored" }: the same text-structuring
  pass the automatic worker runs, over the document's own content index.
  No re-upload, no second read of the original; full gauntlet including
  the shared document-AI bucket with charge-at-dispatch honesty; 422
  notIndexed when no stored text exists.
- A manual "Read with AI" / "Read again" now continues into the same
  lab auto-staging the background worker performs; the response reports
  labFactsStaged and the toast names the values waiting for review.
- Unchecked values are rejected and the copy says so; an unverified
  low-confidence fact receives no decision and stays pending rather than
  being silently discarded. Confirmation remains the only write into
  Labs, conditions, and medications; approved facts carry the
  committedRecordId link back to the source document (existing model, no
  schema change).
- The "lab values from this document" link now counts APPROVED facts
  only — it claims values that actually exist in Labs.
- Copy in all six locales; OpenAPI regenerated for the new extract mode
  and the index response field.
This commit is contained in:
Marc-André Bombeck committed 2026-08-13 00:33:14 +02:00
1 parent 8e16df6894
commit fd104dd0ac
20 files changed
+1681 -64

No files matched your search

@@ -0,0 +1,113 @@
"use client";
/**
* Client hooks for the review-then-confirm chain on a stored document's
* staged facts — the missing UI leg of the server chain that already existed:
*
* extract (`POST …/extract`, incl. `{ mode: "stored" }` over the document's
* own indexed text) → PENDING `ExtractedFact` rows → optional per-fact edit
* (`PATCH …/facts/{factId}`, clears `needsReview`) → confirm
* (`POST …/confirm`) — the ONLY write into the structured stores.
*
* Nothing here commits on its own. The confirm mutation carries the explicit
* approve/reject decisions the person made; a fact without a decision stays
* pending on the server.
*/
import { useMutation, useQueryClient } from "@tanstack/react-query";
import { apiPatch, apiPost } from "@/lib/api/api-fetch";
import { invalidateKeys, queryKeys } from "@/lib/query-keys";
import type {
ExtractedFactDto,
InboundDocumentDetailDto,
InboundFactEdit,
} from "@/lib/validations/inbound-documents";
/** The confirm route's per-batch outcome (per-fact misses never fail it). */
export interface ConfirmFactsResult {
approved: { factId: string; recordType: string; recordId: string }[];
rejected: string[];
needsReview: string[];
failed: { factId: string; reason: string }[];
}
/**
* Structure the document's own stored extracted text into staged facts —
* the manual recovery when the automatic staging run was skipped or failed.
* Stages PENDING facts only; the review + confirm steps stay mandatory.
* A provider call is slow, so the request opts out of the 15 s default.
*/
export function useStoredExtract() {
const queryClient = useQueryClient();
return useMutation<InboundDocumentDetailDto, Error, { documentId: string }>({
mutationFn: ({ documentId }) =>
apiPost<InboundDocumentDetailDto>(
`/api/documents/inbound/${documentId}/extract`,
{ mode: "stored" },
{ signal: AbortSignal.timeout(120_000) },
),
onSuccess: (_data, { documentId }) => {
void invalidateKeys(queryClient, [
queryKeys.inboundDocument(documentId),
queryKeys.documents(),
]);
},
});
}
/**
* Correct a staged fact before approval. A successful edit clears
* `needsReview` server-side — the values become user-asserted and the fact
* turns approvable. The fact's resource type can never change.
*/
export function useEditFact() {
const queryClient = useQueryClient();
return useMutation<
ExtractedFactDto,
Error,
{ documentId: string; factId: string; edit: InboundFactEdit }
>({
mutationFn: ({ documentId, factId, edit }) =>
apiPatch<ExtractedFactDto>(
`/api/documents/inbound/${documentId}/facts/${factId}`,
edit,
),
onSuccess: (_data, { documentId }) => {
void invalidateKeys(queryClient, [queryKeys.inboundDocument(documentId)]);
},
});
}
/**
* Commit the review decisions. Approved facts land in their structured
* stores (labs / conditions / medications) through the server's existing
* field-by-field commit; rejected facts are discarded. Invalidates every
* read the commit can touch, plus the document itself (status + fact states).
*/
export function useConfirmFacts() {
const queryClient = useQueryClient();
return useMutation<
ConfirmFactsResult,
Error,
{
documentId: string;
decisions: { factId: string; action: "approve" | "reject" }[];
}
>({
mutationFn: ({ documentId, decisions }) =>
apiPost<ConfirmFactsResult>(
`/api/documents/inbound/${documentId}/confirm`,
{ decisions },
),
onSuccess: (_data, { documentId }) => {
void invalidateKeys(queryClient, [
queryKeys.inboundDocument(documentId),
queryKeys.documents(),
queryKeys.labResults(),
queryKeys.biomarkers(),
queryKeys.illness(),
queryKeys.medications(),
]);
},
});
}