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

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
+16 -8
View File
@@ -70,7 +70,9 @@ class TestApply277CARejectionsHappyPath:
assert outcome.matched == ["c1"]
assert outcome.orphans == []
with db.SessionLocal()() as s:
c = s.get(Claim, "c1")
# Migration 0014: composite PK; only one claim with id "c1"
# exists in this test, so filter-by-id returns it.
c = s.query(Claim).filter(Claim.id == "c1").first()
assert c.payer_rejected_at is not None
assert c.payer_rejected_status_code == "A6"
assert "A6" in (c.payer_rejected_reason or "")
@@ -116,14 +118,16 @@ class TestApply277CARejectionsIdempotent:
return s.query(Claim).filter_by(patient_control_number="CLAIM001").first()
outcome1 = apply_277ca_rejections(s, result, claim_lookup=_lookup, two77ca_id="ACK-1")
assert outcome1.matched == ["c1"]
original_reason = s.get(Claim, "c1").payer_rejected_reason
original_at = s.get(Claim, "c1").payer_rejected_at
# Migration 0014: composite PK — see test_rejected_status_stamps_matching_claim.
original_reason = s.query(Claim).filter(Claim.id == "c1").first().payer_rejected_reason
original_at = s.query(Claim).filter(Claim.id == "c1").first().payer_rejected_at
# Run again with same code.
outcome2 = apply_277ca_rejections(s, result, claim_lookup=_lookup, two77ca_id="ACK-1")
assert outcome2.matched == []
assert outcome2.already_rejected == ["c1"]
with db.SessionLocal()() as s:
c = s.get(Claim, "c1")
# Migration 0014: see above — composite PK.
c = s.query(Claim).filter(Claim.id == "c1").first()
# Reason and timestamp unchanged.
assert c.payer_rejected_reason == original_reason
assert c.payer_rejected_at == original_at
@@ -143,7 +147,8 @@ class TestApply277CAOnlyRejectsRejected:
outcome = apply_277ca_rejections(s, result, claim_lookup=_lookup, two77ca_id="ACK-1")
assert outcome.matched == []
with db.SessionLocal()() as s:
c = s.get(Claim, "c1")
# Migration 0014: composite PK.
c = s.query(Claim).filter(Claim.id == "c1").first()
assert c.payer_rejected_at is None
@@ -183,9 +188,12 @@ class TestApply277CAMultipleStatuses:
outcome = apply_277ca_rejections(s, result, claim_lookup=_lookup, two77ca_id="ACK-1")
assert outcome.matched == ["c2"]
with db.SessionLocal()() as s:
assert s.get(Claim, "c1").payer_rejected_at is None
assert s.get(Claim, "c2").payer_rejected_at is not None
assert s.get(Claim, "c3").payer_rejected_at is None
# Migration 0014: composite PK — filter-by-id returns the
# single claim with that id (no cross-batch duplicates in
# this test fixture).
assert s.query(Claim).filter(Claim.id == "c1").first().payer_rejected_at is None
assert s.query(Claim).filter(Claim.id == "c2").first().payer_rejected_at is not None
assert s.query(Claim).filter(Claim.id == "c3").first().payer_rejected_at is None
# --------------------------------------------------------------------------- #