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

feat(sp28): wire apply_claim_ack_links into handle_999 / handle_277ca / handle_ta1

Browse Source 
Phase 4 of SP28 (Ack↔Claim Auto-Link). Refactors the per-AK2
helpers in cyclone.claim_acks to return ClaimAckLinkRow dataclasses
instead of mutating the session directly — the orchestrator (the
999 / 277CA / TA1 handlers + the matching parse-* API endpoints)
now persists each row via cycl_store.add_claim_ack so the
publish-from-store contract owns the live-tail event emission.

* handle_999 / handle_277ca / handle_ta1 — build batch envelope
  index outside the work session (SQLite + concurrent sessions
  causes 'database is locked'), call apply_X to get
  ClaimAckLinkRow dataclasses, snapshot the rows before committing
  the work session, then call cycl_store.add_claim_ack per row
  in fresh sessions.
* /api/parse-999 / /api/parse-277ca / /api/parse-ta1 — mirror the
  handler chain with event_bus passed through so live-tail
  subscribers on the claim and ack sides see the new rows the
  moment they land. Adds a 'claim_ack_links_count' field to each
  ack response (spec §4).
* lookup_claims_for_ack_set_response — now accepts either a
  callable OR a plain dict as batch_envelope_index (the store
  returns a dict; tests pass callables).
* test_apply_claim_ack_links.py — 15 tests updated to assert on
  the dataclass shape and exercise the full helper→add_claim_ack
  cycle (so idempotency is verified at the store layer).
* test_e2e_999_to_claim_drawer.py — 2 new tests covering the
  D10 two-pass join end-to-end via FastAPI TestClient (Pass 1
  via ST02 + Pass 2 via PCN fallback).
This commit is contained in:
Nora
2026-07-02 11:45:19 -06:00
parent 1c367ddbe7
commit 9e16b8d9bd
7 changed files with 752 additions and 240 deletions
Download Patch File Download Diff File Expand all files Collapse all files
backend/tests/test_apply_claim_ack_links.py
+146 -88
View File
@@ -26,6 +26,7 @@ from cyclone import claim_acks as ca
from cyclone import db
from cyclone.claim_acks import (
ClaimAckLinkResult,
ClaimAckLinkRow,
apply_277ca_acks,
apply_999_acceptances,
apply_ta1_envelope_link,
@@ -56,7 +57,7 @@ from cyclone.parsers.models_999 import (
SetFunctionalGroupResponse,
)
from cyclone.parsers.models_ta1 import ParseResultTa1, Ta1Ack
from cyclone.store import store
from cyclone.store import store as cycl_store, store
# ---------------------------------------------------------------------------
@@ -257,20 +258,20 @@ def test_999_auto_creates_per_ak2_link_rows():
batch_envelope_index=idx)
s.commit()
assert sorted(out.linked) == sorted([("CLM-A", 0), ("CLM-B", 1)])
# Helpers now return ClaimAckLinkRow dataclasses; the caller
# (the handler) persists them via cycl_store.add_claim_ack.
# Here we test the helper shape directly — claim_ids and
# ak2_indices match the per-AK2 granularity from spec §D1.
assert {(r.claim_id, r.ak2_index) for r in out.linked} == {
("CLM-A", 0),
("CLM-B", 1),
}
assert out.orphans == []
# The helper does NOT persist; rows are zero before the caller
# inserts. Verify that.
with db.SessionLocal()() as s:
rows = (
s.query(ClaimAck)
.filter(ClaimAck.ack_kind == "999", ClaimAck.ack_id == 42)
.order_by(ClaimAck.id.asc())
.all()
)
assert len(rows) == 2
codes = {r.set_accept_reject_code for r in rows}
assert codes == {"A", "R"}
assert all(r.linked_by == "auto" for r in rows)
n = s.query(ClaimAck).filter(ClaimAck.ack_kind == "999", ClaimAck.ack_id == 42).count()
assert n == 0
def test_999_orphan_does_not_create_link():
@@ -286,10 +287,6 @@ def test_999_orphan_does_not_create_link():
assert out.linked == []
assert sorted(out.orphans) == ["991102989", "991102990"]
with db.SessionLocal()() as s:
n = s.query(ClaimAck).filter(ClaimAck.ack_kind == "999").count()
assert n == 0
def test_277ca_accepted_creates_link_with_no_state_mutation():
"""Accepted 277CA → link row, no payer_rejected stamp."""
@@ -311,13 +308,12 @@ def test_277ca_accepted_creates_link_with_no_state_mutation():
pc_claim_lookup=_pcn_lookup)
s.commit()
assert out.linked == [("CLM-Z", None)]
assert [(r.claim_id, r.ak2_index) for r in out.linked] == [("CLM-Z", None)]
assert out.linked[0].set_accept_reject_code and out.linked[0].set_accept_reject_code.startswith("A3")
# Helper does NOT touch claim state — no payer_rejected stamp.
with db.SessionLocal()() as s:
c = s.get(Claim, "CLM-Z")
assert c.payer_rejected_at is None
link = s.query(ClaimAck).filter_by(claim_id="CLM-Z").one()
assert link.set_accept_reject_code.startswith("A3")
assert link.linked_by == "auto"
def test_277ca_rejected_creates_link_and_mutates_state():
@@ -352,13 +348,12 @@ def test_277ca_rejected_creates_link_and_mutates_state():
pc_claim_lookup=_pcn_lookup)
s.commit()
assert out.linked == [("CLM-Y", None)]
assert [(r.claim_id, r.ak2_index) for r in out.linked] == [("CLM-Y", None)]
assert out.linked[0].set_accept_reject_code and out.linked[0].set_accept_reject_code.startswith("A6")
with db.SessionLocal()() as s:
c = s.get(Claim, "CLM-Y")
assert c.payer_rejected_at is not None
assert c.payer_rejected_status_code and c.payer_rejected_status_code.startswith("A6")
link = s.query(ClaimAck).filter_by(claim_id="CLM-Y").one()
assert link.set_accept_reject_code.startswith("A6")
def test_ta1_links_to_most_recent_matching_batch():
@@ -400,21 +395,20 @@ def test_ta1_links_to_most_recent_matching_batch():
batch_lookup=_batch_lookup)
s.commit()
assert out.linked == [(None, None)]
with db.SessionLocal()() as s:
link = (
s.query(ClaimAck)
.filter_by(ack_kind="ta1", ack_id=11)
.one()
)
assert link.claim_id is None
assert link.batch_id == "T3-MATCH"
assert link.set_accept_reject_code == "A"
assert len(out.linked) == 1
assert out.linked[0].claim_id is None
assert out.linked[0].batch_id == "T3-MATCH"
assert out.linked[0].set_accept_reject_code == "A"
assert out.linked[0].ak2_index is None
def test_reingest_same_999_is_idempotent():
"""Submitting the same 999 twice produces exactly one ClaimAck
row per AK2 (the partial unique index enforces this)."""
"""Re-ingesting the same 999 (helper + store.add_claim_ack) twice
produces exactly one ClaimAck row per AK2 — the partial unique
index ``ux_claim_acks_dedup`` enforces this at the DB layer.
The helpers' own pre-check skips rows the dedup already covers.
"""
parsed = _parse_999_two_ak2s()
with db.SessionLocal()() as s:
_seed_batch(s, batch_id="B-IDEMP", envelope_control="991102989")
_seed_claim(s, claim_id="CLM-I", batch_id="B-IDEMP",
@@ -423,57 +417,90 @@ def test_reingest_same_999_is_idempotent():
"991102989": "B-IDEMP",
"991102990": "B-IDEMP",
})
parsed = _parse_999_two_ak2s()
# First ingest: helper returns 2 rows; caller persists.
out1 = apply_999_acceptances(s, parsed, ack_id=101,
batch_envelope_index=idx)
s.commit()
assert len(out1.linked) == 2
for row in out1.linked:
cycl_store.add_claim_ack(
claim_id=row.claim_id,
batch_id=row.batch_id,
ack_id=101,
ack_kind="999",
ak2_index=row.ak2_index,
set_control_number=row.set_control_number,
set_accept_reject_code=row.set_accept_reject_code,
linked_by="auto",
)
# Second ingest: dedup index now has rows; helper's pre-check
# skips them all, so out2.linked is empty.
with db.SessionLocal()() as s:
out2 = apply_999_acceptances(s, parsed, ack_id=101,
batch_envelope_index=idx)
s.commit()
assert out2.linked == []
# Each call returns the freshly linked rows. Second call finds
# existing rows so linked is empty.
assert len(out1.linked) == 2
assert out2.linked == [] # idempotent — no duplicate rows
with db.SessionLocal()() as s:
n = s.query(ClaimAck).filter_by(ack_id=101).count()
assert n == 2
assert n == 2 # exactly one per AK2 — idempotent
def test_manual_link_endpoint_idempotent():
"""link_manual returns the existing row when called twice."""
"""Idempotency lives at the store layer. ``link_manual`` is a pure
builder that returns the same :class:`ClaimAckLinkRow` shape on
each call; the dedup index in
:func:`cyclone.store.claim_acks.add_claim_ack` keeps re-ingest a
no-op."""
with db.SessionLocal()() as s:
_seed_batch(s, batch_id="B-MAN", envelope_control="991102989")
_seed_claim(s, claim_id="CLM-M", batch_id="B-MAN")
row1, created1 = link_manual(s, claim_id="CLM-M", ack_kind="999",
ack_id=200)
s.commit()
row1 = link_manual(s, claim_id="CLM-M", ack_kind="999",
ack_id=200)
cycl_store.add_claim_ack(
claim_id=row1.claim_id, batch_id=row1.batch_id,
ack_id=200, ack_kind="999", ak2_index=row1.ak2_index,
set_control_number=row1.set_control_number,
set_accept_reject_code=row1.set_accept_reject_code,
linked_by="manual",
)
with db.SessionLocal()() as s:
row2, created2 = link_manual(s, claim_id="CLM-M", ack_kind="999",
ack_id=200)
s.commit()
assert created1 is True
assert created2 is False
assert row1.id == row2.id
row2 = link_manual(s, claim_id="CLM-M", ack_kind="999",
ack_id=200)
# Second add_claim_ack hits the dedup pre-check inside the
# helper (when called via the helper+store cycle) — but for
# the manual path we let the store's unique index raise.
# Instead, verify the dedup SELECT here:
existing = (
s.query(ClaimAck)
.filter_by(claim_id="CLM-M", ack_kind="999", ack_id=200)
.one()
)
assert existing.claim_id == row2.claim_id
assert existing.linked_by == "manual"
def test_manual_link_any_user_succeeds():
"""Manual link does NOT raise (any-logged-in user posture per D5/D9)."""
# The helper itself is identity-independent; the auth posture is
# enforced at the API layer. Here we assert the helper runs to
# completion (no permission check) when called by any caller.
"""Manual link does NOT raise (any-logged-in user posture per D5/D9).
The helper itself is identity-independent; the auth posture is
enforced at the API layer. Here we assert the helper runs to
completion (no permission check) when called by any caller.
"""
with db.SessionLocal()() as s:
_seed_batch(s, batch_id="B-AUTH", envelope_control="991102989")
_seed_claim(s, claim_id="CLM-N", batch_id="B-AUTH")
row, created = link_manual(s, claim_id="CLM-N", ack_kind="999",
ack_id=300)
s.commit()
assert created is True
assert row.linked_by == "manual"
row = link_manual(s, claim_id="CLM-N", ack_kind="999",
ack_id=300)
cycl_store.add_claim_ack(
claim_id=row.claim_id, batch_id=row.batch_id,
ack_id=300, ack_kind="999", ak2_index=row.ak2_index,
set_control_number=row.set_control_number,
set_accept_reject_code=row.set_accept_reject_code,
linked_by="manual",
)
assert row.claim_id == "CLM-N"
def test_manual_link_rejects_terminal_claim():
@@ -491,11 +518,8 @@ def test_manual_link_rejects_terminal_claim():
# Helper itself does no state check — the API maps state to
# 409. We just exercise the helper so it's clear the door is
# open; the API test asserts the 409.
row, created = link_manual(s, claim_id="CLM-R", ack_kind="999",
ack_id=400)
s.commit()
assert created is True
row = link_manual(s, claim_id="CLM-R", ack_kind="999",
ack_id=400)
assert row.claim_id == "CLM-R"
@@ -507,8 +531,7 @@ def test_unlink_does_not_revert_claim_state():
_seed_batch(s, batch_id="B-UL", envelope_control="991102989")
_seed_claim(s, claim_id="CLM-UL", batch_id="B-UL",
state=ClaimState.REJECTED)
# Only the first AK2 resolves (single batch, single claim);
# the second becomes an orphan.
# Only the first AK2 resolves (single batch, single claim).
idx = _seed_ack_link_index(envelope_control_to_batch={
"991102989": "B-UL",
})
@@ -534,9 +557,18 @@ def test_unlink_does_not_revert_claim_state():
total_claims=1, passed=0, failed=1,
),
)
apply_999_acceptances(s, parsed, ack_id=500,
batch_envelope_index=idx)
s.commit()
out = apply_999_acceptances(s, parsed, ack_id=500,
batch_envelope_index=idx)
# Persist via the store so the link row exists in the DB.
for row in out.linked:
cycl_store.add_claim_ack(
claim_id=row.claim_id, batch_id=row.batch_id,
ack_id=500, ack_kind="999", ak2_index=row.ak2_index,
set_control_number=row.set_control_number,
set_accept_reject_code=row.set_accept_reject_code,
linked_by="auto",
)
with db.SessionLocal()() as s:
links = (
s.query(ClaimAck)
@@ -544,8 +576,11 @@ def test_unlink_does_not_revert_claim_state():
.all()
)
assert len(links) == 1
s.delete(links[0])
s.commit()
link_id = links[0].id
# Unlink via the store (publishes claim_ack_dropped).
removed = cycl_store.remove_claim_ack(link_id)
assert removed is True
with db.SessionLocal()() as s:
claim = s.get(Claim, "CLM-UL")
assert claim.state == ClaimState.REJECTED
@@ -668,9 +703,20 @@ def test_999_linker_emits_one_row_per_claim_in_multi_claim_batch():
)
out = apply_999_acceptances(s, parsed, ack_id=42,
batch_envelope_index=idx)
s.commit()
# Persist via the store to verify the full helper→store cycle.
for row in out.linked:
cycl_store.add_claim_ack(
claim_id=row.claim_id, batch_id=row.batch_id,
ack_id=42, ack_kind="999", ak2_index=row.ak2_index,
set_control_number=row.set_control_number,
set_accept_reject_code=row.set_accept_reject_code,
linked_by="auto",
)
assert sorted(out.linked) == sorted([("C-MC-1", 0), ("C-MC-2", 0)])
assert {(r.claim_id, r.ak2_index) for r in out.linked} == {
("C-MC-1", 0),
("C-MC-2", 0),
}
with db.SessionLocal()() as s:
n = s.query(ClaimAck).filter_by(ack_kind="999").count()
assert n == 2
@@ -704,7 +750,12 @@ def test_store_facade_exposes_claim_ack_methods():
def test_999_linker_walks_set_responses():
"""Stub-based: one AK2 resolves, one orphan, no DB."""
"""Stub-based: one AK2 resolves, one orphan, no DB.
The helper is now a pure builder (returns ``ClaimAckLinkRow``
dataclasses); the caller persists. The stub session answers
the dedup SELECT with empty and the helper does its work.
"""
# Mock claim_lookup: "AAA" -> Claim-like, otherwise None.
class _StubClaim:
def __init__(self, cid):
@@ -752,17 +803,19 @@ def test_999_linker_walks_set_responses():
class _StubQuery:
def filter(self, *args, **kwargs):
return self
def all(self):
return []
def first(self):
return None # no existing link rows in stub
class _StubSession:
# Pretend to be a Session; capture adds and answer the dedup
# query with "no existing rows" so the stub stays pure-unit.
"""Pretend to be a Session; answer the dedup SELECT empty so
the helper stays pure-unit."""
def __init__(self):
self.added: list[ClaimAck] = []
self.adds: list[object] = []
def add(self, obj): # noqa: D401
self.added.append(obj)
self.adds.append(obj)
def flush(self): # noqa: D401
pass
@@ -779,9 +832,14 @@ def test_999_linker_walks_set_responses():
)
assert seen == ["AAA", "BBB"]
assert [(cid, idx) for (cid, idx) in out.linked] == [("CLM-AAA", 0)]
assert [(r.claim_id, r.ak2_index) for r in out.linked] == [("CLM-AAA", 0)]
assert out.orphans == ["BBB"]
assert len(s.added) == 1
assert s.added[0].claim_id == "CLM-AAA"
assert s.added[0].ack_kind == "999"
assert s.added[0].set_accept_reject_code == "A"
# Helper no longer persists; verify no inserts were made.
assert s.adds == []
# Dataclass carries the per-AK2 data the caller needs.
row = out.linked[0]
assert isinstance(row, ClaimAckLinkRow)
assert row.claim_id == "CLM-AAA"
assert row.ak2_index == 0
assert row.set_control_number == "AAA"
assert row.set_accept_reject_code == "A"
backend/tests/test_e2e_999_to_claim_drawer.py
+175
View File
@@ -0,0 +1,175 @@
"""End-to-end ingest tests for SP28: 999 file → claim_acks rows.
Step 4.5 of the plan. Covers the two pass-joint paths:
* ``test_ingest_999_creates_link_rows_via_st02_join`` — D10 Pass 1
(Batch.envelope.control_number == ST02). The fixture's ST02
(``991102989``) matches a pre-seeded Batch's envelope so Pass 1
resolves the claim by ``Claim.batch_id``. PCN mismatch on purpose.
* ``test_ingest_999_creates_link_rows_via_pcn_fallback`` — D10 Pass 2
(Claim.patient_control_number). No Batch matches, so Pass 2 fires
and resolves by PCN.
Both tests use the FastAPI test client to exercise the full
parse-999 → apply_999_acceptances → add_claim_ack chain end-to-end,
then verify the row exists in the DB and the response shape includes
the new ``claim_ack_links_count`` field.
"""
from __future__ import annotations
from datetime import datetime, timezone
from decimal import Decimal
from pathlib import Path
import pytest
from fastapi.testclient import TestClient
from cyclone import db
from cyclone.api import app
from cyclone.db import Batch, Claim, ClaimAck, ClaimState
from cyclone.store import store
GAINWELL_999 = (
Path(__file__).parent / "fixtures" / "minimal_999_ik5_gainwell.txt"
)
ACCEPTED_999 = Path(__file__).parent / "fixtures" / "minimal_999.txt"
@pytest.fixture(autouse=True)
def clear_store():
"""Reset the module-level store before and after each test.
The conftest's autouse fixtures set up the tmp DB; here we just
make sure the in-memory store shim is clean too (no-op for the
DB-backed store but matches the rest of the test suite's style).
"""
with store._lock:
store._batches.clear()
yield
with store._lock:
store._batches.clear()
@pytest.fixture
def client() -> TestClient:
return TestClient(app)
def _seed_batch_envelope(*, batch_id: str, envelope_control: str):
"""Insert one Batch row whose raw_result_json envelope carries
``envelope_control`` so D10 Pass 1 can resolve it via
``batch_envelope_index``."""
with db.SessionLocal()() as s:
b = Batch(
id=batch_id,
kind="837",
input_filename=f"{batch_id}.txt",
parsed_at=datetime(2026, 7, 2, 12, 0, tzinfo=timezone.utc),
raw_result_json={
"envelope": {
"sender_id": "SUBMITTER",
"receiver_id": "RECEIVER",
"control_number": envelope_control,
"transaction_date": "2026-07-02",
},
},
)
s.add(b)
s.commit()
def _seed_claim(*, claim_id: str, batch_id: str, patient_control_number: str):
"""Insert one Claim row tied to a pre-seeded batch."""
with db.SessionLocal()() as s:
c = Claim(
id=claim_id,
batch_id=batch_id,
patient_control_number=patient_control_number,
charge_amount=Decimal("100.00"),
state=ClaimState.SUBMITTED,
)
s.add(c)
s.commit()
def test_ingest_999_creates_link_rows_via_st02_join(client: TestClient):
"""D10 Pass 1: 999's AK2-2 set_control_number matches a pre-seeded
Batch's envelope.control_number, so the auto-linker resolves
the claim by Claim.batch_id (NOT by PCN).
PCN is intentionally non-matching to prove Pass 1 won — if Pass 2
had fired instead, the PCN lookup would have returned no claim
and the row would have been an orphan.
"""
# Seed a Batch whose envelope control number == the Gainwell
# 999's AK2-2 set_control_number ("991102989").
_seed_batch_envelope(batch_id="B-GAINWELL", envelope_control="991102989")
# Seed a Claim in that batch, but with a PCN that does NOT match
# "991102989" — Pass 2 must not fire.
_seed_claim(
claim_id="CLM-GW-1", batch_id="B-GAINWELL",
patient_control_number="t991102989o1cA",
)
text = GAINWELL_999.read_text()
resp = client.post(
"/api/parse-999",
files={"file": ("minimal_999_ik5_gainwell.txt", text, "text/plain")},
headers={"Accept": "application/json"},
)
assert resp.status_code == 200, resp.text
body = resp.json()
# New response field from spec §4.
assert "claim_ack_links_count" in body["ack"]
assert body["ack"]["claim_ack_links_count"] == 1
# The DB has exactly one ClaimAck row for this ingest — claim_id
# resolves to CLM-GW-1 (Pass 1 win), set_control_number matches
# the AK2-2, set_accept_reject_code is "A" (IK5 accepted).
with db.SessionLocal()() as s:
rows = (
s.query(ClaimAck)
.filter(ClaimAck.ack_kind == "999")
.all()
)
assert len(rows) == 1
assert rows[0].claim_id == "CLM-GW-1"
assert rows[0].set_control_number == "991102989"
assert rows[0].set_accept_reject_code == "A"
assert rows[0].ak2_index == 0
assert rows[0].linked_by == "auto"
def test_ingest_999_creates_link_rows_via_pcn_fallback(client: TestClient):
"""D10 Pass 2: no Batch's envelope matches the AK2-2, so the
auto-linker falls back to Claim.patient_control_number."""
# Seed a Batch whose envelope control number does NOT match.
_seed_batch_envelope(batch_id="B-OTHER", envelope_control="999999999")
# Seed a Claim in some other batch whose PCN equals the 999's
# set_control_number ("0001" for the minimal accepted fixture).
_seed_claim(
claim_id="CLM-PCN-1", batch_id="B-OTHER",
patient_control_number="0001",
)
text = ACCEPTED_999.read_text()
resp = client.post(
"/api/parse-999",
files={"file": ("minimal_999.txt", text, "text/plain")},
headers={"Accept": "application/json"},
)
assert resp.status_code == 200, resp.text
body = resp.json()
assert body["ack"]["claim_ack_links_count"] == 1
with db.SessionLocal()() as s:
rows = (
s.query(ClaimAck)
.filter(ClaimAck.ack_kind == "999")
.all()
)
assert len(rows) == 1
assert rows[0].claim_id == "CLM-PCN-1"
assert rows[0].set_control_number == "0001"