aeat.application.ledger._preflight module

Backend readiness preflight for bucket-scoped ledger transactions.

preflight_ledger_tax_readiness() loads a TransactionCatalogue via TransactionCatalogueRepository from the active bucket and delegates to preflight_transaction_catalogue() for pure in-memory analysis. The report is consumed by modelo readiness projection and ledger read surfaces; it is not a calculation engine and never mutates the catalogue it inspects.

See also

build_operator_state_projection()

Modelo readiness consumer that embeds blocking ledger issues in the operator state projection.

aeat.entrypoints.cli._ledger_read_cli

CLI read surface that reports these preflight issues without mutating ledger state.

aeat.application.aggregation

Calculation source mesh that consumes ledger facts only after this readiness layer has reported operator-facing gaps.

class LedgerPreflightIssueReason(*values)[source]

Bases: StrEnum

Machine-readable ledger facts missing before modelo calculation.

MISSING_BUSINESS_CLASSIFICATION
MISSING_CATEGORY
MISSING_TAXABLE_BASE
MISSING_IVA_AMOUNT
MISSING_IVA_RATE
MISSING_EUR_TAX_SUBSTRATE
MISSING_COUNTERPARTY_EU_MEMBER_STATE
DOMESTIC_COUNTERPARTY_ON_INTRA_COMMUNITY_TRANSACTION
EU_MEMBER_STATE_ON_EXPORT_TRANSACTION
MISSING_PROPORTIONALITY_REFERENCE
UNSUPPORTED_CURRENCY
UNSUPPORTED_PERIOD
CENSO_RATIO_MISMATCH
ANOMALY_NON_DECLARABLE_IVA_CATEGORY
ANOMALY_NON_DECLARABLE_RECARGO_EQUIVALENCIA
class LedgerPreflightIssue(**data)[source]

Bases: BaseModel

One model-readiness issue attached to a bucket-local transaction.

Parameters:
transaction_id: str
reason: LedgerPreflightIssueReason
detail: str
class LedgerPreflightReport(**data)[source]

Bases: BaseModel

Readiness report for ledger facts consumed by modelo calculation.

Parameters:

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

  • period (Period)

  • checked_transaction_count (int)

  • issues (Sequence[LedgerPreflightIssue])

bucket_id: BucketId
period: Period
checked_transaction_count: int
issues: Sequence[LedgerPreflightIssue]
property ready: bool
preflight_ledger_tax_readiness(*, bucket_id, period, transaction_repository=None, raw_afectacion_ratio=None)[source]

Load a bucket-local catalogue and report modelo-readiness gaps.

Parameters:

  • bucket_id (str) – Bucket whose ledger catalogue is being checked.

  • period (Period) – Filing period used to decide whether each transaction belongs in the readiness window.

  • transaction_repository (TransactionCatalogueRepository | None) – Optional TransactionCatalogueRepository used to load the bucket-local catalogue; a default repository is constructed when None.

  • raw_afectacion_ratio (Decimal | None) – Optional home-office usage ratio from censo data, used only to surface proportionality mismatches.

Return type:

LedgerPreflightReport

Returns:

A LedgerPreflightReport describing blocking or advisory ledger facts for modelo-readiness projection.

preflight_transaction_catalogue(*, bucket_id, period, transactions, censo_ratio_mismatch_detail=None)[source]

Report missing ledger facts without mutating the transaction catalogue.

Parameters:

  • bucket_id (str) – Stable bucket identifier for the ledger being checked.

  • period (Period) – Filing period as a typed Period instance.

  • transactions (TransactionCatalogue) – The TransactionCatalogue to inspect for missing facts.

  • censo_ratio_mismatch_detail (str | None) – Optional censo mismatch detail previously resolved from the secure ratio profile. When supplied, active HOME_OFFICE ratio rows surface it as a preflight issue.

Return type:

LedgerPreflightReport

Returns a LedgerPreflightReport.