Matching heuristic: normalise debit/credit sign and revisit the date window #47

New issue

Closed

opened 2026-07-04 12:11:41 +00:00 by momsse · 0 comments

momsse commented

2026-07-04 12:11:41 +00:00

Owner

Migré depuis viziertronic/octant#104 — ouvert le 2026-06-27 par @momsse.

Surfaced in the #32 local review against the merged matcher (#38).

Two correctness concerns in packages/application/transaction-matching/src/matching/exact-match.ts:

Signed amounts. amountsMatch requires identical signed amountMinor. Bank outflows are conventionally negative while invoice/document amounts are positive, so a -15000 payment never equals a +15000 invoice — the common payment-vs-invoice case produces zero candidates. Needs a sign-normalisation rule (e.g. compare absolute values, or normalise debit/credit by direction) decided at the domain level.
Date window. MATCH_DATE_WINDOW = 5 days between document.issuedAt and transaction.valueDate. Invoices on net-15/net-30 terms are issued well before payment, so legitimate pairs fall outside the window and never get a candidate. Revisit the window (or make it configurable via @octant/config).

Both were deliberate first-cut choices for the exact-match heuristic; this ticket tracks tuning them against real-world invoice/payment data before the matcher is relied upon.

> _Migré depuis [viziertronic/octant#104](https://github.com/viziertronic/octant/issues/104) — ouvert le 2026-06-27 par @momsse._ Surfaced in the #32 local review against the merged matcher (#38). Two correctness concerns in `packages/application/transaction-matching/src/matching/exact-match.ts`: 1. **Signed amounts.** `amountsMatch` requires identical signed `amountMinor`. Bank outflows are conventionally negative while invoice/document amounts are positive, so a -15000 payment never equals a +15000 invoice — the common payment-vs-invoice case produces zero candidates. Needs a sign-normalisation rule (e.g. compare absolute values, or normalise debit/credit by direction) decided at the domain level. 2. **Date window.** `MATCH_DATE_WINDOW = 5 days` between `document.issuedAt` and `transaction.valueDate`. Invoices on net-15/net-30 terms are issued well before payment, so legitimate pairs fall outside the window and never get a candidate. Revisit the window (or make it configurable via `@octant/config`). Both were deliberate first-cut choices for the exact-match heuristic; this ticket tracks tuning them against real-world invoice/payment data before the matcher is relied upon.

momsse closed this issue

2026-07-04 12:11:41 +00:00

momsse referenced this issue

2026-07-04 12:19:01 +00:00

Real external adapters (BankApi/PartyDocumentApi/DocumentAnalyzer) + activate sync/analysis in apps/api #50