File size: 7,442 Bytes
e1267ce
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
"""
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