aeat.domain.transactions._service module

Service helpers for transaction catalogues.

Pure functions over domain.transactions.TransactionCatalogue: each helper returns a fresh immutable catalogue rather than mutating the input. The module brokers the classification/percentage coupling rules and history-chain bookkeeping that callers must not implement ad-hoc.

find_transaction(catalogue, transaction_id)[source]

Return one transaction from a catalogue if present.

Parameters:
Return type:

Transaction | None

Returns:

The matching Transaction, or None when absent.

Return a new catalogue with invoice_id linked to one transaction.

Parameters:

  • catalogue (TransactionCatalogue) – Source catalogue.

  • transaction_id (str) – Stable transaction identifier to update.

  • invoice_id (str) – Invoice foreign key to attach.

Return type:

TransactionCatalogue

Returns:

A fresh immutable TransactionCatalogue with the linked invoice.

set_classification(catalogue, transaction_id, *, classification, business_pct=None, category_id=None, notes=None, classified_by, reason='', confidence=None)[source]

Return a new catalogue with updated classification metadata.

Appends a ClassificationHistoryEntry to the transaction’s classification_history chain whenever the incoming decision differs (by state, percentage, classified_by, reason, category_id, notes, or confidence) from the transaction’s current head. Byte-identical re-classifies are skipped so rule engines can run idempotently without inflating history.

Parameters:

  • catalogue (TransactionCatalogue) – Source catalogue.

  • transaction_id (str) – Stable transaction identifier to update.

  • classification (BusinessClassification) – New business-classification state.

  • business_pct (Decimal | None) – Business-use percentage for MIXED classifications.

  • category_id (str | None) – Optional category ID for the transaction.

  • notes (str | None) – Optional notes or reasoning for the classification.

  • classified_by (str) – Classifier source string: auto, manual, or rule:<rule-id>.

  • reason (str) – Free-text override justification; embedded in the history entry, not on the top-level transaction.

  • confidence (Decimal | None) – Caller-supplied decision confidence in the inclusive [0, 1] range. When omitted, manual decisions default to Decimal("1.0") and all other classifier paths default to None.

Return type:

TransactionCatalogue

Returns:

A fresh TransactionCatalogue with updated classification metadata.

snapshot_classification_state(transaction, *, fallback_at=None)[source]

Return a ClassificationHistoryEntry capturing the transaction’s current active state.

When no explicit classified_at is present (the pipeline has never run against this transaction), fall back to the provenance ingested_at timestamp so the synthesised entry reflects when the transaction first entered the catalogue. This keeps the chain in chronological order. fallback_at is an optional final fallback for callers that want to cap the synthesised timestamp (e.g. set_classification uses the canonical clock helper).

Return type:

ClassificationHistoryEntry

Parameters: