Files
accounted/lib/invoices/apply-invoice-payment.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

201 lines
8.3 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* Single source of truth for applying a payment amount to a customer invoice.
*
* Computes the new paid/remaining/status and: critically: REJECTS overpayment
* before the caller creates any journal entry, so a doomed match never burns a
* voucher number.
*
* Background: this math was copy-pasted across three sites: the dashboard
* match-invoice route (which had the overpayment guard), the v1 public API
* route, and `commitMatchTransactionInvoice` (the agent/MCP path). The latter
* two had drifted WITHOUT the guard, so they silently swallowed overpayment via
* `Math.max(0, …)`: recording e.g. 1500 paid on a 1000 invoice and
* over-crediting accounts receivable. Centralizing the math + guard here closes
* that drift; all three sites delegate to `planInvoicePayment`.
*
* FX: `paymentAmountInInvoiceCurrency` MUST already be in the invoice's
* currency. The caller owns any conversion (cross-currency settlement lives in
* the dashboard route), keeping this helper FX-agnostic.
*
* Extracted from the proven dashboard route with the same half-öre overshoot
* tolerance. Rounding goes through the canonical `roundOre` (@/lib/money) per
* guard rail #9: identical to the route's previous `Math.round(x*100)/100`
* except on exact-half-öre amounts, where `roundOre` rounds correctly.
*/
import { roundOre, ORE_TOLERANCE, ORE_ROUNDING_SETTLEMENT_MAX } from '@/lib/money'
/** Half an öre: anything over the remaining by more than this is a real overpayment. */
export const PAYMENT_OVERSHOOT_TOLERANCE = ORE_TOLERANCE
export interface InvoicePaymentTotals {
total: number
paid_amount?: number | null
remaining_amount?: number | null
}
export interface InvoicePaymentPlan {
newPaidAmount: number
newRemaining: number
isFullyPaid: boolean
newStatus: 'paid' | 'partially_paid'
/** True when a sub-krona öre residual was absorbed (full settlement of an
* inexact amount): the 3740 line carries it. Always false unless the caller
* opts in via `absorbOreRounding`. */
oreSettled: boolean
}
export type PlanInvoicePaymentResult =
| { ok: true; plan: InvoicePaymentPlan }
| {
ok: false
code: 'MATCH_AMOUNT_EXCEEDS_REMAINING'
details: { transaction_amount: number; remaining_amount: number; excess: number }
}
export function planInvoicePayment(
invoice: InvoicePaymentTotals,
paymentAmountInInvoiceCurrency: number,
opts?: { absorbOreRounding?: boolean },
): PlanInvoicePaymentResult {
const absorbOre = opts?.absorbOreRounding === true
const currentRemaining =
invoice.remaining_amount ?? invoice.total - (invoice.paid_amount || 0)
// A rounded-up whole-krona payment is not an overpayment: when absorbing öre,
// accept only an overshoot strictly inside the settlement band. The boundary
// must be >= : with a strict > guard an exact 1 kr overshoot passed the guard
// AND missed the |diff| < 1 absorb branch, falling through to record
// paid_amount = total + 1 kr with remaining clamped to 0 (silent over-credit).
// Without absorb, keep the strict half-öre float tolerance the legacy callers
// rely on.
const overshoot = roundOre(paymentAmountInInvoiceCurrency - currentRemaining)
const isOverpayment = absorbOre
? overshoot >= ORE_ROUNDING_SETTLEMENT_MAX
: paymentAmountInInvoiceCurrency > currentRemaining + PAYMENT_OVERSHOOT_TOLERANCE
if (isOverpayment) {
return {
ok: false,
code: 'MATCH_AMOUNT_EXCEEDS_REMAINING',
details: {
transaction_amount: paymentAmountInInvoiceCurrency,
remaining_amount: roundOre(currentRemaining),
excess: roundOre(paymentAmountInInvoiceCurrency - currentRemaining),
},
}
}
const diff = roundOre(currentRemaining - paymentAmountInInvoiceCurrency)
// Within the öre band (and absorbing) → settle in full; the 3740 line carries
// the residual. Covers both a short whole-krona payment and a rounded-up one.
if (absorbOre && Math.abs(diff) < ORE_ROUNDING_SETTLEMENT_MAX) {
return {
ok: true,
plan: {
newPaidAmount: roundOre((invoice.paid_amount || 0) + currentRemaining),
newRemaining: 0,
isFullyPaid: true,
newStatus: 'paid',
oreSettled: Math.abs(diff) >= ORE_TOLERANCE,
},
}
}
const newPaidAmount = roundOre((invoice.paid_amount || 0) + paymentAmountInInvoiceCurrency)
const newRemaining = Math.max(0, roundOre(currentRemaining - paymentAmountInInvoiceCurrency))
const isFullyPaid = newRemaining <= 0
return {
ok: true,
plan: {
newPaidAmount,
newRemaining,
isFullyPaid,
newStatus: isFullyPaid ? 'paid' : 'partially_paid',
oreSettled: false,
},
}
}
/** BAS öres- och kronutjämning: the only account that may carry an absorbed residual. */
const ORE_ROUNDING_ACCOUNT = '3740'
/** BAS 1513, Kundfordringar delad faktura: Skatteverket's ROT/RUT share. */
export const ROT_RUT_RECEIVABLE_ACCOUNT = '1513'
/**
* Derives the customer-settlement amount from caller-supplied booking lines.
*
* `remaining_amount` on a ROT/RUT invoice is stored NET of the deduction
* (total - deduction_total): the customer owes only their share, and
* Skatteverket's share sits on 1513 until the payout-request flow clears it.
* The kontantmetoden payment entry, however, correctly books TWO debit legs
* (bank = customer share, 1513 = deduction), so a naive sum of all debits
* yields the gross total and every ROT/RUT cash invoice fails the
* overpayment guard by exactly the deduction.
*
* The 1513 exclusion is netted against 1513 credits (a debit/credit
* correction pair in one entry must not shrink the settlement) and capped at
* the invoice's own deduction, so on an invoice without a deduction the
* result is the plain debit sum and behavior is unchanged, including the
* rejection of a hand-added 1513 debit that overshoots the remaining.
*
* `deductionCapSek` must be in SEK (the lines' currency); the caller owns
* converting a foreign-currency invoice's deduction_total.
*/
export function deriveCustomerSettlementAmount(
lines: Array<{ account_number: string; debit_amount: number; credit_amount: number }>,
deductionCapSek: number,
): number {
const totalDebit = lines.reduce((s, l) => s + l.debit_amount, 0)
if (deductionCapSek <= 0) return totalDebit
const net1513 = roundOre(
lines
.filter((l) => l.account_number === ROT_RUT_RECEIVABLE_ACCOUNT)
.reduce((s, l) => s + l.debit_amount - l.credit_amount, 0),
)
const excluded = Math.min(Math.max(net1513, 0), deductionCapSek)
return roundOre(totalDebit - excluded)
}
/**
* `planInvoicePayment` for caller-supplied booking lines (the mark-paid
* dialog and the v1 API), where the server does NOT build the verifikat.
*
* Absorbing an öre residual is only safe when the lines actually book it:
* in the server-built bank-match flow `buildInvoicePaymentClearingLines`
* guarantees 1510 is credited the full remaining and 3740 carries the exact
* residual, so plan and GL absorb together. Here the lines are caller-owned,
* so absorption is granted only when the net 3740 amount (debit − credit)
* equals the signed residual (remaining − payment). Otherwise fall back to
* the strict plan: a sub-krona short payment stays a real partial and a
* sub-krona overshoot is rejected, exactly as before absorption existed.
* Without this gate an invoice could flip to paid while the posted lines
* under-clear 1510, diverging the GL from the AR sub-ledger.
*/
export function planInvoicePaymentForLines(
invoice: InvoicePaymentTotals,
paymentAmountInInvoiceCurrency: number,
lines:
| Array<{ account_number: string; debit_amount: number; credit_amount: number }>
| undefined,
invoiceCurrency: string,
): PlanInvoicePaymentResult {
const absorbEligible = !!lines && invoiceCurrency === 'SEK'
const payment = planInvoicePayment(invoice, paymentAmountInInvoiceCurrency, {
absorbOreRounding: absorbEligible,
})
if (!absorbEligible || !payment.ok || !payment.plan.oreSettled) return payment
const currentRemaining =
invoice.remaining_amount ?? invoice.total - (invoice.paid_amount || 0)
const residual = roundOre(currentRemaining - paymentAmountInInvoiceCurrency)
const net3740 = roundOre(
lines!
.filter((l) => l.account_number === ORE_ROUNDING_ACCOUNT)
.reduce((s, l) => s + l.debit_amount - l.credit_amount, 0),
)
if (net3740 === residual) return payment
return planInvoicePayment(invoice, paymentAmountInInvoiceCurrency)
}