feat(sp31): add _content_keys_match pure helper (2-of-3 PCN/charge/NPI rule)

backend/src/cyclone/reconcile.py

@@ -117,6 +117,41 @@ def _pick_claim(
     return None
 
 
+# --- SP31: content-keys fallback matcher -----------------------------------
+
+CHARGE_TOLERANCE = Decimal("0.01")
+KEYS_REQUIRED = 2
+
+
+def _content_keys_match(remit, claim) -> bool:
+    """Return True when at least KEYS_REQUIRED of {PCN, charge, NPI} agree.
+
+    Charge compared with ``CHARGE_TOLERANCE`` tolerance (rounding drift).
+    NPI counts as "not matched" when the remit's NPI is empty.
+    """
+    keys_matched = 0
+
+    # PCN: payer_claim_control_number ↔ patient_control_number (stripped).
+    if (getattr(remit, "payer_claim_control_number", "") or "").strip() == \
+       (getattr(claim, "patient_control_number", "") or "").strip():
+        keys_matched += 1
+
+    # Charge: total_charge_amount ↔ total_charge (within $0.01).
+    remit_charge = getattr(remit, "total_charge_amount", None)
+    claim_charge = getattr(claim, "total_charge", None)
+    if remit_charge is not None and claim_charge is not None and \
+       abs(remit_charge - claim_charge) < CHARGE_TOLERANCE:
+        keys_matched += 1
+
+    # NPI: rendering_provider_npi ↔ rendering_provider_npi (must be non-empty).
+    remit_npi = (getattr(remit, "rendering_provider_npi", "") or "").strip()
+    claim_npi = (getattr(claim, "rendering_provider_npi", "") or "").strip()
+    if remit_npi and remit_npi == claim_npi:
+        keys_matched += 1
+
+    return keys_matched >= KEYS_REQUIRED
+
+
 @dataclass
 class ApplyIntent:
     """Result of applying a match. The caller persists this.