cadrumo.domain.invoices.service module

Service helpers for invoice catalogues.

Exposes pure-function service operations over an InvoiceCatalogue: lookup (suggest_reconciliations()), in-memory linking (link_transaction()), reconciliation suggestions (suggest_reconciliations()), and bidirectional consistency checks (verify_link_consistency()). Operations that span both the invoice catalogue and the TransactionCatalogue accept each as an independent argument. Persisted cross-catalogue workflows belong in cadrumo.application.invoices.

class ReconciliationSuggestion(**data)[source]

Bases: BaseModel

Immutable suggestion emitted by the reconciliation heuristic.

Variables:

  • invoice_id – Stable invoice identifier.

  • transaction_id – Candidate transaction identifier.

  • amount_match – Whether the sign-aware amount matches within tolerance.

  • counterparty_match – Whether the counterparty name overlaps (case-insensitive substring match either direction).

  • score – Confidence in the inclusive 0..1 range.

Parameters:

data (Any)

invoice_id: InvoiceId
transaction_id: TransactionId
amount_match: bool
counterparty_match: bool
score: Decimal
class LinkInconsistency(**data)[source]

Bases: BaseModel

Immutable record describing a one-sided link between the two catalogues.

Variables:

  • invoice_id – Identifier of the invoice involved in the bad link.

  • transaction_id – Identifier of the transaction involved.

  • direction – Which side cites the other without being cited back, as a LinkInconsistencyDirection member.

Parameters:

data (Any)

invoice_id: str
transaction_id: TransactionId
direction: LinkInconsistencyDirection

Return a new catalogue with transaction_id linked to invoice_id.

Parameters:

  • catalogue (InvoiceCatalogue) – Source catalogue.

  • invoice_id (str) – Invoice identifier to update.

  • transaction_id (str) – Transaction identifier to append to the invoice’s linked_transaction_ids tuple.

Return type:

InvoiceCatalogue

Returns:

A fresh immutable InvoiceCatalogue with the updated invoice. Duplicate links are idempotent: calling this helper with an already-linked transaction returns a value-equal catalogue rather than raising.

Raises:

InvoiceLinkError – If transaction_id is not a 64-character lowercase hex digest.

suggest_reconciliations(invoices, transactions, *, amount_tolerance=Decimal('0.01'))[source]

Return auto-suggested invoice/transaction links sorted by score.

Only unlinked invoices (empty linked_transaction_ids) and transactions whose invoice_id is None are considered. Suggestions are emitted only when the amount matches within amount_tolerance. Counterparty similarity acts as a score-boost (case-insensitive substring match) but is never sufficient on its own.

Parameters:
Return type:

tuple[ReconciliationSuggestion, ...]

Returns:

Deterministic tuple of ReconciliationSuggestion objects sorted by (score desc, invoice_id asc, transaction_id asc).

Return every one-sided link between the two catalogues.

A link is invoice-only when an invoice cites a transaction that does not cite it back, and transaction-only when a transaction cites an invoice that does not cite it back.

Parameters:
Return type:

tuple[LinkInconsistency, ...]

Returns:

Deterministic tuple of LinkInconsistency items sorted by (invoice_id, transaction_id).