tyler/cyclone
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(acks): accept IK5 from Gainwell, trust set-level codes over bogus AK9, surface TA1 in UI

Browse Source 
Two related fixes land together because the UI was reporting
"1 accepted 1 rejected" for every 999 even though every inbound file
Gainwell ships has IK5=A.

  1. Gainwell's MFT uses IK5 where the X12 005010X231A1 spec calls
     for AK5 (the per-set accept/reject segment). The parser only
     recognized AK5, so set_responses[0].set_accept_reject.code
     defaulted to 'R' and the count summary showed all rejections.
     _consume_ak2 now accepts either AK5 or IK5; the orchestrator's
     segment-skip set picks up IK5 too. A new fixture
     (minimal_999_ik5_gainwell.txt) is a verbatim copy of one of the
     files in the FromHPE inbound staging dir.

  2. _ack_count_summary (api + scheduler) now trusts the per-set
     IK5 codes over the functional-group AK9. Gainwell's AK9 is
     internally inconsistent — the per-claim IK5=A but the AK9
     reports accepted=1, rejected=1, received=1 (sum exceeds
     received). Trusting the per-set codes restores the right
     answer: accepted=1, rejected=0, code='A'.

  3. The Acks page now has a TA1 envelope register alongside the
     999 register. TA1s are the lower-level sibling of the 999
     (one row per inbound ISA/IEA). The backend surface (parser,
     store, API at /api/ta1-acks) was already in place; this
     adds the UI: Ta1Ack type, listTa1Acks API method, useTa1Acks
     hook, and a Ta1AcksSection card with KPIs + table.

After reprocessing 1056 cached 999s through the new code: every row
shows code='A' with accepted=1, rejected=0 — matches the Gainwell
portal's per-claim accepted state. The user's earlier observation
("the claims look to be accepted in the portal") was correct: the
underlying claim state was always fine, only the displayed count was
wrong.

  - backend/src/cyclone/parsers/parse_999.py | 21 ++-
  - backend/src/cyclone/api.py               | 11 +-
  - backend/src/cyclone/scheduler.py         | 13 +-
  - backend/tests/test_parse_999.py          | 32 ++++
  - backend/tests/fixtures/minimal_999_ik5_gainwell.txt
  - src/types/index.ts                       | 32 ++++
  - src/lib/api.ts                           | 62 +++++-
  - src/hooks/useTa1Acks.ts                  | 26 +++ (new)
  - src/pages/Acks.tsx                       | 209 +++++++++++++++++++-
This commit is contained in:
Nora
2026-06-25 00:26:13 -06:00
parent 1381a7652d
commit 6507a8c874
9 changed files with 399 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/pages/Acks.tsx
+207 -2
View File
@@ -1,5 +1,5 @@
import { useCallback, useState } from "react";
import { CheckCircle2, Download, ShieldCheck } from "lucide-react";
import { CheckCircle2, Download, Mail, ShieldCheck } from "lucide-react";
import {
Table,
TableBody,
@@ -18,11 +18,12 @@ import { KeyboardCheatsheet } from "@/components/KeyboardCheatsheet";
import { AckDrawer } from "@/components/AckDrawer";
import { useAckDrawerUrlState } from "@/hooks/useAckDrawerUrlState";
import { useAcks } from "@/hooks/useAcks";
import { useTa1Acks } from "@/hooks/useTa1Acks";
import { useRowKeyboard } from "@/hooks/useRowKeyboard";
import { api } from "@/lib/api";
import { fmt } from "@/lib/format";
import { cn } from "@/lib/utils";
import type { Ack } from "@/types";
import type { Ack, Ta1Ack } from "@/types";
/**
* 999 ACK register. The page reads the persisted 999 Implementation
@@ -411,6 +412,18 @@ export function Acks() {
</Card>
</section>
{/* =================================================================
TA1 ENVELOPE ACKS — per-interchange acknowledgments.
A TA1 (X12 Interchange Acknowledgment) is one row per
inbound ISA/IEA envelope — the lower-level sibling of the
999 (per-batch). Colorado Medicaid's Gainwell MFT currently
only ships 999s, but the section stays in the surface so
the operator can see TA1s as soon as one shows up. Kept as
a quieter, narrower section than the 999 register so the
999s remain the page's primary instrument.
================================================================= */}
<Ta1AcksSection />
{/* =================================================================
FOOTER — single hairline-separated status row. Replaces the
warm-paper "End of register" treatment with a quiet
@@ -552,3 +565,195 @@ function downloadBlob(filename: string, content: string) {
a.click();
URL.revokeObjectURL(url);
}
// ---------------------------------------------------------------------------
// Ta1AcksSection — per-interchange TA1 register.
//
// Deliberately quieter than the 999 register above: smaller KPI strip,
// single-card table, and an empty state that explains the
// Colorado-specific context (TA1s aren't shipped today, so the
// section is empty unless Gainwell starts sending them).
// ---------------------------------------------------------------------------
function Ta1AcksSection() {
const { data, isLoading, isError, error, refetch } = useTa1Acks({ limit: 50 });
const items = data?.items ?? [];
const totals = items.reduce(
(acc, t) => {
acc[t.ackCode] = (acc[t.ackCode] ?? 0) + 1;
return acc;
},
{} as Record<string, number>,
);
return (
<section
aria-label="TA1 envelope acknowledgments"
className="animate-fade-in-up"
>
<Card>
<CardContent className="p-6 lg:p-7 space-y-5">
<div className="flex items-end justify-between gap-6 flex-wrap">
<div className="min-w-0">
<div className="eyebrow flex items-center gap-2 mb-2">
<span className="inline-block h-px w-6 bg-foreground/20" />
Envelope acks
</div>
<h2 className="display text-[22px] leading-[1.05] tracking-[-0.02em]">
TA1 <span className="italic">envelopes</span>, newest first.
</h2>
</div>
<p className="text-[12.5px] text-muted-foreground/80 max-w-sm">
One row per inbound ISA/IEA interchange — the
envelope-level sibling of the 999. Gainwell's Colorado
MFT does not ship TA1s today; this section surfaces them
when they appear.
</p>
</div>
<div className="grid gap-3 grid-cols-2 md:grid-cols-4 pt-2">
<KpiCard
label="On file"
value={fmt.num(items.length)}
accent="default"
hint="persisted TA1s"
/>
<KpiCard
label="Accepted"
value={fmt.num(totals.A ?? 0)}
accent="success"
hint="ack_code = A"
/>
<KpiCard
label="Envelope errors"
value={fmt.num(totals.E ?? 0)}
accent="warning"
hint="ack_code = E"
/>
<KpiCard
label="Rejected"
value={fmt.num(totals.R ?? 0)}
accent="destructive"
hint="ack_code = R"
/>
</div>
<div className="pt-5 border-t border-border/40">
{isError ? (
<ErrorState
message="Couldn't load TA1 acks from the backend."
detail={error instanceof Error ? error.message : String(error)}
onRetry={() => refetch()}
/>
) : isLoading ? (
<div className="rounded-md border border-border/60 bg-card/40 p-4 space-y-2">
{Array.from({ length: 3 }).map((_, i) => (
<Skeleton key={i} variant="row" />
))}
</div>
) : items.length === 0 ? (
<div className="rounded-md border border-dashed border-border/60 bg-card/40">
<EmptyState
eyebrow="TA1 envelopes · none on file"
message="Gainwell's Colorado MFT does not ship TA1 files today. When one does arrive (or you upload one), it will land here."
/>
</div>
) : (
<div className="rounded-md border border-border/60 overflow-hidden bg-card/40">
<Table>
<TableHeader>
<TableRow>
<TableHead className="w-10" aria-label="Status" />
<TableHead>Control #</TableHead>
<TableHead>Ack</TableHead>
<TableHead>Note</TableHead>
<TableHead>Interchange date</TableHead>
<TableHead>Sender → Receiver</TableHead>
</TableRow>
</TableHeader>
<TableBody>
{items.map((t) => (
<TableRow key={t.id}>
<TableCell>
<Mail
className={cn(
"h-3.5 w-3.5",
t.ackCode === "A"
? "text-[hsl(var(--success))]"
: t.ackCode === "R"
? "text-destructive"
: "text-[hsl(var(--warning))]",
)}
strokeWidth={1.75}
aria-hidden
/>
</TableCell>
<TableCell className="display mono text-[13px] text-foreground">
{t.controlNumber || "—"}
</TableCell>
<TableCell>
<Ta1CodeBadge code={t.ackCode} />
</TableCell>
<TableCell className="mono text-[12px] text-muted-foreground">
{t.noteCode ?? "—"}
</TableCell>
<TableCell className="mono text-[12.5px] text-muted-foreground/70">
{t.interchangeDate ? fmt.dateShort(t.interchangeDate) : "—"}
{t.interchangeTime ? (
<span className="text-muted-foreground/50"> · {t.interchangeTime}</span>
) : null}
</TableCell>
<TableCell className="mono text-[12px] text-muted-foreground truncate max-w-[260px]">
{t.senderId ?? "?"} → {t.receiverId ?? "?"}
</TableCell>
</TableRow>
))}
</TableBody>
</Table>
</div>
)}
</div>
</CardContent>
</Card>
</section>
);
}
// ---------------------------------------------------------------------------
// Ta1CodeBadge — same A/E/R → success/warning/destructive mapping as the
// 999 AckCodeBadge above. Kept as a separate component so the TA1
// surface can evolve independently (e.g. add a tooltip explaining the
// X12 005010X231A1 note code table) without churning the 999 surface.
// ---------------------------------------------------------------------------
function Ta1CodeBadge({ code }: { code: Ta1Ack["ackCode"] }) {
const color =
code === "A"
? {
text: "hsl(var(--success))",
bg: "hsl(var(--success) / 0.10)",
border: "hsl(var(--success) / 0.30)",
}
: code === "R"
? {
text: "hsl(var(--destructive))",
bg: "hsl(var(--destructive) / 0.10)",
border: "hsl(var(--destructive) / 0.30)",
}
: {
text: "hsl(var(--warning))",
bg: "hsl(var(--warning) / 0.10)",
border: "hsl(var(--warning) / 0.30)",
};
return (
<span
className="inline-flex items-center gap-1 rounded-sm border px-2 py-0.5 mono text-[10.5px] font-semibold uppercase tracking-[0.14em]"
style={{
color: color.text,
backgroundColor: color.bg,
borderColor: color.border,
}}
>
{code}
</span>
);
}