Doc_ShopPro_Portal / src /reconciliation_engine.py
jonels1988's picture
Create reconciliation_engine.py
e1267ce verified
Raw History Blame Contribute Delete
7.44 kB
"""
reconciliation_engine.py
Reconciliation engine that uses exact-only matching.
It:
- Converts canonical DataFrames into InvoiceRecord / PaymentRecord objects
- Uses FuzzyMatcher (configured as exact-only) to find payment suggestions
- Builds ReconciliationMatch objects and wraps them in a ReconciliationResult
- Supports admin corrections and exporting to Excel/CSV
This matches the interface expected by app.py:
engine = ReconciliationEngine()
result = engine.reconcile(open_invoices_df, payment_notifications_df)
engine.apply_correction(record_id, correction)
engine.get_results()
engine.export_to_excel()
engine.export_to_csv()
"""
from __future__ import annotations
from typing import List, Tuple, Optional
from datetime import datetime
import os
import uuid
import tempfile
import pandas as pd
from .data_models import (
InvoiceRecord,
PaymentRecord,
ReconciliationMatch,
MatchStatus,
ReconciliationResult,
AdminCorrection,
)
from .matching_algorithms import MatchScorer, FuzzyMatcher
class ReconciliationEngine:
"""
High-level reconciliation engine.
- Uses exact-only matching (via FuzzyMatcher/MatchScorer).
- Produces ReconciliationResult compatible with the UI in app.py.
"""
def __init__(self) -> None:
self._results: ReconciliationResult = ReconciliationResult(matches=[])
# ------------------------------------------------------------------
# Public API used by app.py
# ------------------------------------------------------------------
def reconcile(
self,
open_invoices_df: pd.DataFrame,
payment_notifications_df: pd.DataFrame,
) -> ReconciliationResult:
"""
Run reconciliation given the canonical DataFrames and return ReconciliationResult.
"""
invoices = self._df_to_invoices(open_invoices_df)
payments = self._df_to_payments(payment_notifications_df)
scorer = MatchScorer()
matcher = FuzzyMatcher(scorer=scorer, threshold=1.0)
matches: List[ReconciliationMatch] = []
# For each invoice, find exact payment suggestions
for inv in invoices:
suggestions = matcher.get_suggestions(inv, payments)
if suggestions:
# We treat the first exact suggestion as the main match
best_payment, score = suggestions[0]
match_status = MatchStatus.EXACT_MATCH
linked_payment_id = best_payment.id
applied_payment_amount = best_payment.payment_amount
final_ar_status = "Paid"
confidence_score = score
else:
match_status = MatchStatus.UNMATCHED
linked_payment_id = None
applied_payment_amount = None
final_ar_status = inv.ar_status or "Unpaid"
confidence_score = 0.0
suggestions = [] # no payment suggestions
match = ReconciliationMatch(
record_id=inv.id,
invoice_record=inv,
match_status=match_status,
linked_payment_id=linked_payment_id,
payment_suggestions=suggestions,
applied_payment_amount=applied_payment_amount,
final_ar_status=final_ar_status,
admin_notes=None,
confidence_score=confidence_score,
is_approved=False,
approved_by=None,
approved_at=None,
)
matches.append(match)
self._results = ReconciliationResult(matches=matches)
return self._results
def apply_correction(self, record_id: str, correction: AdminCorrection) -> bool:
"""
Apply an admin correction to a specific ReconciliationMatch by record_id.
- Updates linked_payment_id, payment_amount, ar_status, notes.
- If action == 'approve', sets match_status=APPROVED and is_approved=True.
- If action == 'discrepancy', sets match_status=DISCREPANCY.
"""
if not self._results or not self._results.matches:
return False
target: Optional[ReconciliationMatch] = None
for m in self._results.matches:
if m.record_id == record_id:
target = m
break
if target is None:
return False
# Apply corrections
if correction.linked_payment_id is not None:
target.linked_payment_id = correction.linked_payment_id
if correction.payment_amount is not None:
target.applied_payment_amount = correction.payment_amount
if correction.ar_status is not None:
target.final_ar_status = correction.ar_status
if correction.admin_notes is not None:
target.admin_notes = correction.admin_notes
# Handle action
action = (correction.action or "").lower()
now = datetime.utcnow()
if action == "approve":
target.is_approved = True
target.match_status = MatchStatus.APPROVED
target.approved_at = now
# approved_by can be set later if you have user context
elif action == "discrepancy":
target.match_status = MatchStatus.DISCREPANCY
return True
def get_results(self) -> ReconciliationResult:
"""Return the current reconciliation results."""
return self._results
def export_to_excel(self) -> str:
"""
Export current reconciliation results to an Excel file and return the file path.
Used by app.export_results().
"""
df = self._results.to_dataframe()
if df.empty:
raise ValueError("No data to export")
tmp_dir = tempfile.gettempdir()
file_path = os.path.join(
tmp_dir,
f"reconciliation_results_{uuid.uuid4().hex}.xlsx",
)
df.to_excel(file_path, index=False)
return file_path
def export_to_csv(self) -> str:
"""
Export current reconciliation results to a CSV file and return the file path.
"""
df = self._results.to_dataframe()
if df.empty:
raise ValueError("No data to export")
tmp_dir = tempfile.gettempdir()
file_path = os.path.join(
tmp_dir,
f"reconciliation_results_{uuid.uuid4().hex}.csv",
)
df.to_csv(file_path, index=False)
return file_path
# ------------------------------------------------------------------
# Internal helpers
# ------------------------------------------------------------------
def _df_to_invoices(self, df: pd.DataFrame) -> List[InvoiceRecord]:
"""Convert canonical invoice DataFrame to list of InvoiceRecord objects."""
if df is None or df.empty:
return []
records: List[InvoiceRecord] = []
for row in df.to_dict(orient="records"):
records.append(InvoiceRecord(**row))
return records
def _df_to_payments(self, df: pd.DataFrame) -> List[PaymentRecord]:
"""Convert canonical payment DataFrame to list of PaymentRecord objects."""
if df is None or df.empty:
return []
records: List[PaymentRecord] = []
for row in df.to_dict(orient="records"):
records.append(PaymentRecord(**row))
return records