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

feat(db): migration 0014 relaxes claims/remittances PK to (batch_id, id)

Browse Source 
Migration 0014 changes the PRIMARY KEYs of claims and remittances from
single-column id to composite (batch_id, id). Enables the spec'd
cross-batch CLM01 / CLP01 collision workflow: same CLM01 in multiple
batches is now representable (resubmits), pre-flight dedup 409 path is
genuinely exercisable, force-insert can skip pre-existing duplicates.

Strategy: PRAGMA defer_foreign_keys = ON + table recreation for every
table whose FKs pointed at the old single-column PK. Tables recreated:
remittances, claims, matches, cas_adjustments, service_line_payments,
line_reconciliations. Each child table gains a batch_id (or
remittance_batch_id) column for the composite FK side; INSERT INTO new
SELECT FROM old JOINs populate it from the already-recreated parent.

Cross-table FKs (remittances.claim_id, claims.matched_remittance_id)
cannot be SQL-enforced with composite PKs (SQLite has no ALTER
CONSTRAINT). Dropped at SQL level; enforced via application-layer
invariants in store.manual_match / manual_unmatch / reconcile.run and
the dedup.preflight_* helpers.

ORM updates (db.py):
- Claim / Remittance: composite PK via explicit PrimaryKeyConstraint in
  __table_args__ (column order matches SQL: batch_id, id).
- New Claim.matched_remittance_batch_id column.
- Match / CasAdjustment / ServiceLinePayment / LineReconciliation:
  added the batch side of their composite FK to the parent table.
- SQLAlchemy before_insert events auto-populate the batch side of the
  composite FK from session.new, then identity_map, then SQL fallback.

Production code updates:
- store.manual_match / manual_unmatch: also write
  matched_remittance_batch_id on the claim (was missing).
- api.py manual-match endpoint: same fix.
- reconcile.run: same fix for auto-matched pairs.

Test updates: replaced s.get(Claim, X) with the composite key
(batch_id, id) where batch_id is known, or s.query().filter().first()
where the test only knows the id. Tests that previously inserted a Match
row pointing at a non-existent Remittance now seed the parent Remittance
so the new NOT NULL composite FK is satisfied.
This commit is contained in:
Tyler
2026-06-21 18:56:18 -06:00
parent 890207f40d
commit 534130ee2b
18 changed files with 895 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files
backend/tests/test_db_models.py
+31 -17
View File
@@ -72,8 +72,9 @@ def test_create_and_query_claim_with_default_state():
s.add(c)
s.commit()
# Migration 0014: composite PK (batch_id, id). PK lookups use tuples.
with db.SessionLocal()() as s:
loaded = s.get(Claim, "CLM-1")
loaded = s.get(Claim, ("b1", "CLM-1"))
assert loaded is not None
assert loaded.state == ClaimState.SUBMITTED
assert loaded.charge_amount == Decimal("124.00")
@@ -99,7 +100,7 @@ def test_claim_uses_db_default_when_state_omitted():
s.commit()
with db.SessionLocal()() as s:
loaded = s.get(Claim, "CLM-1")
loaded = s.get(Claim, ("b1", "CLM-1"))
assert loaded is not None
assert loaded.state == ClaimState.SUBMITTED
@@ -123,7 +124,7 @@ def test_state_before_reversal_round_trips():
s.commit()
with db.SessionLocal()() as s:
loaded = s.get(Claim, "CLM-1")
loaded = s.get(Claim, ("b1", "CLM-1"))
assert loaded is not None
assert loaded.state_before_reversal == ClaimState.PAID
@@ -154,7 +155,8 @@ def test_batch_cascade_delete_drops_claims():
with db.SessionLocal()() as s:
assert s.get(Batch, "b1") is None
assert s.get(Claim, "CLM-1") is None
# Composite PK lookup — both batch_id AND id are required.
assert s.get(Claim, ("b1", "CLM-1")) is None
def test_create_and_query_remittance():
@@ -178,7 +180,7 @@ def test_create_and_query_remittance():
s.commit()
with db.SessionLocal()() as s:
loaded = s.get(Remittance, "CLP-1")
loaded = s.get(Remittance, ("b1", "CLP-1"))
assert loaded is not None
assert loaded.status_code == "1"
assert loaded.total_paid == Decimal("124.00")
@@ -201,10 +203,14 @@ def test_cas_adjustment_aggregation():
)
s.add(r)
s.flush()
# Migration 0014: remittance_batch_id is required (NOT NULL) on
# CasAdjustment; it mirrors remittance_id's batch.
s.add_all([
CasAdjustment(remittance_id="CLP-1", group_code="CO", reason_code="45",
CasAdjustment(remittance_id="CLP-1", remittance_batch_id="b1",
group_code="CO", reason_code="45",
amount=Decimal("30.00")),
CasAdjustment(remittance_id="CLP-1", group_code="PR", reason_code="1",
CasAdjustment(remittance_id="CLP-1", remittance_batch_id="b1",
group_code="PR", reason_code="1",
amount=Decimal("32.00")),
])
s.commit()
@@ -235,15 +241,16 @@ def test_remittance_raw_json_round_trips_dict():
s.commit()
with db.SessionLocal()() as s:
loaded = s.get(Remittance, "CLP-1")
loaded = s.get(Remittance, ("b1", "CLP-1"))
assert loaded.raw_json == {"x12_segments": ["CLP", "NM1", "SVC"], "version": "005010X221A1"}
def test_remittance_allows_duplicate_pcn_in_same_batch():
"""An 835 ERA can carry multiple CLP segments with the same
payer_claim_control_number (e.g. reversals re-referencing the
original PCN). Remittance identity is by ``id`` (CLP01), not by
(batch_id, PCN). This test documents the absence of the constraint
original PCN). Remittance identity is by the composite PK
(batch_id, id) — id (CLP01) distinguishes rows in the same batch.
This test documents the absence of the (batch_id, PCN) constraint
removed in migration 0003.
"""
with db.SessionLocal()() as s:
@@ -286,12 +293,13 @@ def test_remittance_cascade_delete_drops_cas_adjustments():
)
s.add(r)
s.flush()
s.add(CasAdjustment(remittance_id="CLP-1", group_code="CO",
reason_code="45", amount=Decimal("30.00")))
s.add(CasAdjustment(remittance_id="CLP-1", remittance_batch_id="b1",
group_code="CO", reason_code="45",
amount=Decimal("30.00")))
s.commit()
with db.SessionLocal()() as s:
r = s.get(Remittance, "CLP-1")
r = s.get(Remittance, ("b1", "CLP-1"))
s.delete(r)
s.commit()
@@ -318,8 +326,10 @@ def test_create_match_and_activity_event():
status_code="1", total_charge=Decimal("124.00"), total_paid=Decimal("124.00"),
received_at=datetime(2026, 6, 19, tzinfo=timezone.utc),
))
# Migration 0014: Match needs batch_id + remittance_batch_id (NOT NULL).
m = Match(
claim_id="CLM-1", remittance_id="CLP-1",
claim_id="CLM-1", batch_id="b1",
remittance_id="CLP-1", remittance_batch_id="b1",
strategy="auto", is_reversal=False,
matched_at=datetime(2026, 6, 19, 13, 0, tzinfo=timezone.utc),
)
@@ -361,9 +371,13 @@ def test_match_multiple_rows_per_claim():
status_code="1", received_at=datetime.now(timezone.utc)))
s.add(Remittance(id="CLP-2", batch_id="b1", payer_claim_control_number="y",
status_code="1", received_at=datetime.now(timezone.utc)))
s.add(Match(claim_id="CLM-1", remittance_id="CLP-1", strategy="auto",
matched_at=datetime.now(timezone.utc)))
s.add(Match(claim_id="CLM-1", remittance_id="CLP-2", strategy="manual",
# Migration 0014: batch_id + remittance_batch_id required on Match.
s.add(Match(claim_id="CLM-1", batch_id="b1",
remittance_id="CLP-1", remittance_batch_id="b1",
strategy="auto", matched_at=datetime.now(timezone.utc)))
s.add(Match(claim_id="CLM-1", batch_id="b1",
remittance_id="CLP-2", remittance_batch_id="b1",
strategy="manual",
matched_at=datetime.now(timezone.utc),
is_reversal=True, prior_claim_state=ClaimState.PAID))
# No IntegrityError — two Match rows per claim are now allowed.