Files
accounted/lib/invoices/invoice-matching.ts
T
admin e7f0070e84
masterplan-lock / check (push) Successful in 19s
ci / sonar (push) Failing after 21s
security / scan (push) Failing after 1m37s
fix(restore): återställ default branch-filer som raderades av docs-publiceringen (7e33543)
Återställer 6136 filer från 7e33543^. Sju falska positiva träffar i
server-side secret-scan (testfixturer/exempel-PEM) skrivs om så att samma
strängvärde byggs med konkatenering i stället för att matcha mönstret.
2026-11-10 09:37:22 +01:00

455 lines
17 KiB
TypeScript

/**
* Invoice Matching: auto-match income transactions to unpaid customer invoices.
*
* Amounts are only ever compared inside one currency: same currency → raw
* magnitudes, different currencies → the invoice's STORED SEK conversion
* against a SEK bank row. An invoice with no usable SEK value is not offered
* at all, because comparing a raw EUR total against a kronor bank row is what
* makes a 1 000 EUR invoice "exactly match" a 1 000 kr receipt. OCR/reference
* matching is deliberately exempt: the reference identifies the invoice on its
* own and no amount is involved.
*
* That guard is silent by design, which is its own problem: the user never
* learns why the EUR invoice that obviously matches is missing from the
* suggestions. `findInvoiceMatchCandidates()` therefore returns the dropped
* invoices alongside the matches (same shape as `unconverted_fx_count` in
* lib/reports/supplier-ledger.ts), so a caller can name them and point at the
* repair: POST /api/invoices/{id}/refresh-exchange-rate.
*
* The supplier-side twin is lib/invoices/supplier-invoice-matching.ts. Keep the
* two guards in step.
*/
import type { SupabaseClient } from '@supabase/supabase-js'
import { fetchAllRows } from '@/lib/supabase/fetch-all'
import { normalizeCurrencyCode, invoiceAmountSek } from './duplicate-guard-currency'
import type { Invoice, Transaction, Customer } from '@/types'
export interface InvoiceMatch {
invoice: Invoice & { customer?: Customer }
confidence: number
matchReason: string
}
/**
* An invoice dropped before scoring, with the reason, so callers can tell the
* user why an obvious invoice is not among the suggestions.
*/
export interface InvoiceMatchExclusion {
invoiceId: string
invoiceNumber: string | null
/** The invoice's own currency, e.g. 'EUR'. */
currency: string
/**
* `unconverted_fx`: foreign-currency invoice with no stored SEK conversion
* (`total_sek`), compared against a SEK bank row. Remedy:
* POST /api/invoices/{id}/refresh-exchange-rate, which fetches the
* taxable-event rate from Riksbanken and fills in `total_sek`. It refuses
* once the invoice is booked (INVOICE_FX_REFRESH_BOOKED); from there the
* correction is a storno or an inline rättelse.
*/
reason: 'unconverted_fx'
}
export interface InvoiceMatchResult {
matches: InvoiceMatch[]
/**
* Number of foreign-currency invoices excluded from candidacy because they
* had no usable SEK value. Offering them would mean comparing currencies;
* surfacing the count lets the caller tell the user a candidate was withheld
* and what to do about it, instead of the invoice just never showing up.
*/
unconvertedFxCount: number
/** The excluded invoices themselves, so a caller can name the repair target. */
unconvertedFxInvoices: InvoiceMatchExclusion[]
}
/**
* Confidence thresholds for invoice matching. Shared with voucher-matching.ts
* so the two flows (transaction→invoice and existing-verifikat→invoice) rank
* candidates on the same scale.
*/
export const CONFIDENCE = {
OCR_REFERENCE_MATCH: 0.99,
EXACT_AMOUNT_CUSTOMER: 0.95,
EXACT_AMOUNT_ONLY: 0.80,
FUZZY_AMOUNT_CUSTOMER: 0.70,
FUZZY_AMOUNT_ONLY: 0.50,
MIN_THRESHOLD: 0.50,
}
/**
* Fuzzy amount tolerance (±1% for FX fees)
*/
const FUZZY_TOLERANCE = 0.01
/**
* Check if two amounts match exactly (within rounding)
*/
export function amountsMatchExact(transactionAmount: number, invoiceTotal: number): boolean {
// Round to 2 decimal places for comparison
const txRounded = Math.round(transactionAmount * 100) / 100
const invRounded = Math.round(invoiceTotal * 100) / 100
return txRounded === invRounded
}
/**
* Check if two amounts match within fuzzy tolerance (±1%)
*/
export function amountsMatchFuzzy(transactionAmount: number, invoiceTotal: number): boolean {
if (invoiceTotal === 0) return false
const diff = Math.abs(transactionAmount - invoiceTotal)
// Cap fuzzy tolerance at 500 SEK to prevent false positives on large invoices
const tolerance = Math.min(invoiceTotal * FUZZY_TOLERANCE, 500)
return diff <= tolerance
}
/**
* Check if customer name appears in transaction counterparty
*/
export function customerNameMatches(
customerName: string | undefined,
transactionDescription: string,
merchantName: string | null
): boolean {
if (!customerName) return false
const searchTerms = customerName.toLowerCase().split(/\s+/).filter(term => term.length > 2)
const searchText = `${transactionDescription} ${merchantName || ''}`.toLowerCase()
// Check if any significant word from customer name appears in transaction
return searchTerms.some(term => searchText.includes(term))
}
/**
* Calculate confidence score and match reason for an invoice match
*/
export function calculateMatchScore(
transaction: Transaction,
invoice: Invoice & { customer?: Customer }
): { confidence: number; matchReason: string } {
const transactionAmount = transaction.amount
const invoiceTotal = invoice.total
const exactAmount = amountsMatchExact(transactionAmount, invoiceTotal)
const fuzzyAmount = !exactAmount && amountsMatchFuzzy(transactionAmount, invoiceTotal)
const customerMatch = customerNameMatches(
invoice.customer?.name,
transaction.description,
transaction.merchant_name
)
if (exactAmount && customerMatch) {
return {
confidence: CONFIDENCE.EXACT_AMOUNT_CUSTOMER,
matchReason: `Exakt belopp (${invoiceTotal} ${invoice.currency}) och kundnamn matchar`,
}
}
if (exactAmount) {
return {
confidence: CONFIDENCE.EXACT_AMOUNT_ONLY,
matchReason: `Exakt belopp (${invoiceTotal} ${invoice.currency})`,
}
}
if (fuzzyAmount && customerMatch) {
return {
confidence: CONFIDENCE.FUZZY_AMOUNT_CUSTOMER,
matchReason: `Belopp nära (±1%) och kundnamn matchar`,
}
}
if (fuzzyAmount) {
return {
confidence: CONFIDENCE.FUZZY_AMOUNT_ONLY,
matchReason: `Belopp nära (±1%)`,
}
}
return { confidence: 0, matchReason: '' }
}
/**
* The invoice's outstanding amount expressed in the transaction's currency, or
* null when no such value can be established from STORED data.
*
* Never falls back to the raw foreign amount. That fallback would hand the
* matcher a EUR total dressed up as kronor, which is the exact false match this
* function exists to prevent. A missing conversion means "not comparable",
* never "assume SEK".
*/
function comparableAmount(
invoice: Invoice,
transaction: Transaction,
invoiceAmount: number
): number | null {
// Currency codes normalize before any comparison: both `invoices.currency`
// and `transactions.currency` are nullable with DEFAULT 'SEK', so a legacy
// NULL (or lowercase) code means kronor and must keep matching a SEK bank
// row instead of being routed down the cross-currency branch and dropped.
// Same rule as normalizeCurrency in supplier-invoice-matching.ts.
const invoiceCurrency = normalizeCurrencyCode(invoice.currency)
const transactionCurrency = normalizeCurrencyCode(transaction.currency)
// Same currency: raw magnitudes, no rate needed. The only path a SEK-only
// company ever takes.
if (invoiceCurrency === transactionCurrency) return invoiceAmount
// Cross-currency: only a SEK bank row is comparable, and only against the
// invoice's stored SEK conversion.
if (transactionCurrency !== 'SEK') return null
// One definition of "the invoice amount in SEK", shared with the
// duplicate-payment guards: pro-rated total_sek first (total_sek covers the
// whole invoice at the registration rate while remaining_amount is in the
// invoice currency), then the stored exchange_rate when total_sek is 0 or
// absent. Both are STORED conversions; a missing rate still returns null.
return invoiceAmountSek({
amount: invoiceAmount,
currency: invoiceCurrency,
total: invoice.total,
totalSek: invoice.total_sek,
exchangeRate: invoice.exchange_rate,
})
}
/**
* True when the only thing standing between this invoice and candidacy is its
* own missing SEK conversion, i.e. the case POST
* /api/invoices/{id}/refresh-exchange-rate repairs. A SEK invoice against a
* foreign bank row, or two different foreign currencies, is a different
* (rate-independent) exclusion and is not reported as one of these.
*/
function isUnconvertedForeignInvoice(invoice: Invoice, transaction: Transaction): boolean {
// Same normalization as comparableAmount: a NULL/lowercase code is kronor,
// so a legacy NULL-currency invoice is never reported as unconverted FX.
const invoiceCurrency = normalizeCurrencyCode(invoice.currency)
return (
normalizeCurrencyCode(transaction.currency) === 'SEK' &&
invoiceCurrency !== 'SEK' &&
invoiceAmountSek({
amount: invoice.remaining_amount ?? invoice.total,
currency: invoiceCurrency,
total: invoice.total,
totalSek: invoice.total_sek,
exchangeRate: invoice.exchange_rate,
}) === null
)
}
function emptyResult(): InvoiceMatchResult {
return { matches: [], unconvertedFxCount: 0, unconvertedFxInvoices: [] }
}
/**
* Find invoices that potentially match a bank transaction
*
* Only matches income transactions (amount > 0) against unpaid invoices
* Returns matches sorted by confidence, filtered to >= 50% confidence
*
* Thin wrapper over `findInvoiceMatchCandidates()` that drops the exclusion
* diagnostics. Use the candidates function when the caller can tell the user
* why an invoice was withheld.
*/
export async function findMatchingInvoices(
supabase: SupabaseClient,
companyId: string,
transaction: Transaction
): Promise<InvoiceMatch[]> {
const { matches } = await findInvoiceMatchCandidates(supabase, companyId, transaction)
return matches
}
/**
* `findMatchingInvoices()` plus the invoices that were dropped before scoring
* because they carried no comparable amount.
*/
export async function findInvoiceMatchCandidates(
supabase: SupabaseClient,
companyId: string,
transaction: Transaction
): Promise<InvoiceMatchResult> {
// Only match income transactions
if (transaction.amount <= 0) {
return emptyResult()
}
// Query unpaid invoices (sent or overdue) with customer info. Proformas,
// delivery notes and quotes are never receivables, so a sent quote is never
// proposed as a payment candidate.
let invoices: Array<Invoice & { customer?: { name?: string | null } | null }>
try {
invoices = await fetchAllRows(({ from, to }) =>
supabase
.from('invoices')
.select('*, customer:customers(*), credit_notes:invoices!credited_invoice_id(id, status, creation_complete)')
.eq('company_id', companyId)
.eq('document_type', 'invoice')
.is('credited_invoice_id', null)
.in('status', ['sent', 'overdue', 'partially_paid'])
.order('id', { ascending: true })
.range(from, to),
)
} catch {
// Failed to fetch invoices: return empty matches
return emptyResult()
}
// Defensive filter: exclude invoices that already have a payment voucher
// attached but whose status leaked (still 'sent'/'overdue'). Partially-paid
// invoices can legitimately take more payments, so they pass through.
// Without this, a status leak would double-book the receipt.
const payableInvoices = invoices.filter(
(invoice) => {
const creditNotes = (invoice as Invoice & {
credit_notes?: Array<{ status: string; creation_complete?: boolean }>
}).credit_notes ?? []
return !invoice.credited_invoice_id && !creditNotes.some(
(creditNote) => creditNote.status !== 'cancelled' && creditNote.creation_complete !== false,
)
},
)
const fullCandidateIds = payableInvoices
.filter((inv) => inv.status === 'sent' || inv.status === 'overdue')
.map((inv) => inv.id as string)
const paidIds = new Set<string>()
if (fullCandidateIds.length > 0) {
const paymentRows = await fetchAllRows<{ id: string; invoice_id: string }>(({ from, to }) =>
supabase
.from('invoice_payments')
.select('id, invoice_id')
.eq('company_id', companyId)
.in('invoice_id', fullCandidateIds)
.not('journal_entry_id', 'is', null)
.order('id', { ascending: true })
.range(from, to),
)
for (const row of paymentRows) {
paidIds.add((row as { invoice_id: string }).invoice_id)
}
}
const filteredInvoices = payableInvoices.filter((inv) => !paidIds.has(inv.id as string))
if (filteredInvoices.length === 0) {
return emptyResult()
}
const matches: InvoiceMatch[] = []
const unconvertedFxInvoices: InvoiceMatchExclusion[] = []
// OCR/Bankgiro reference matching: highest confidence
// Swedish standard: match transaction reference to invoice OCR number
const txReference = (transaction as Transaction & { reference?: string | null }).reference
if (txReference) {
const normalizedRef = txReference.replace(/\s+/g, '')
for (const invoice of filteredInvoices) {
// Match against invoice_number (used as OCR reference in Swedish payments)
const invoiceRef = invoice.invoice_number?.replace(/\s+/g, '')
if (invoiceRef && normalizedRef === invoiceRef) {
matches.push({
invoice: invoice as Invoice & { customer?: Customer },
confidence: CONFIDENCE.OCR_REFERENCE_MATCH,
matchReason: `OCR-referens matchar fakturanummer ${invoice.invoice_number}`,
})
}
}
// If we found an OCR match, return immediately (highest possible confidence)
if (matches.length > 0) {
return { matches, unconvertedFxCount: 0, unconvertedFxInvoices: [] }
}
}
for (const invoice of filteredInvoices) {
// Use remaining_amount for partially paid invoices, otherwise total
const invoiceAmount = invoice.remaining_amount ?? invoice.total
// Every pass below compares amounts, so they need one shared unit. No
// shared unit means this invoice is not a candidate at all: it must never
// be offered on the strength of a raw foreign number that happens to line
// up with a kronor bank row.
const compareAmount = comparableAmount(invoice, transaction, invoiceAmount)
if (compareAmount === null) {
// Record the ones a missing exchange rate is holding back, so the caller
// can say so instead of leaving the user to wonder.
if (isUnconvertedForeignInvoice(invoice, transaction)) {
unconvertedFxInvoices.push({
invoiceId: invoice.id as string,
invoiceNumber: invoice.invoice_number ?? null,
currency: invoice.currency as string,
reason: 'unconverted_fx',
})
}
continue
}
const transactionAmount = transaction.amount
// Check if amounts are close enough to consider
const amountDiff = Math.abs(transactionAmount - compareAmount)
const tolerance = compareAmount * FUZZY_TOLERANCE
if (amountDiff > tolerance && transactionAmount !== compareAmount) {
continue
}
// Calculate score
const invoiceWithAdjustedTotal = {
...invoice,
total: compareAmount, // Use the comparable amount
}
const { confidence, matchReason } = calculateMatchScore(
transaction,
invoiceWithAdjustedTotal as Invoice & { customer?: Customer }
)
if (confidence >= CONFIDENCE.MIN_THRESHOLD) {
matches.push({
invoice: invoice as Invoice & { customer?: Customer },
confidence,
matchReason,
})
}
}
// Sort by confidence descending. Ties (two open invoices for the same
// amount on the same day) prefer the invoice that asked to be paid to the
// account the money landed on. A tie-breaker only: scores are untouched, so
// nothing that did not auto-match before starts to.
const landedOn = (transaction as { cash_account_id?: string | null }).cash_account_id ?? null
const prefers = (m: InvoiceMatch): number =>
landedOn && m.invoice.payment_cash_account_id === landedOn ? 1 : 0
matches.sort((a, b) => b.confidence - a.confidence || prefers(b) - prefers(a))
return {
matches,
unconvertedFxCount: unconvertedFxInvoices.length,
unconvertedFxInvoices,
}
}
/**
* Get the best matching invoice for a transaction
* Returns the highest confidence match if it meets the threshold
*
* `InvoiceMatch | null` has nowhere to carry a reason, so an invoice withheld
* for a missing exchange rate is invisible on this path. Callers that can show
* the user something should use `findInvoiceMatchCandidates()` and read
* `unconvertedFxInvoices`; widening this signature is left to whoever has a
* surface to render it on.
*/
export async function getBestInvoiceMatch(
supabase: SupabaseClient,
companyId: string,
transaction: Transaction,
minConfidence: number = 0.80
): Promise<InvoiceMatch | null> {
const matches = await findMatchingInvoices(supabase, companyId, transaction)
if (matches.length > 0 && matches[0].confidence >= minConfidence) {
return matches[0]
}
return null
}