aeat.domain.iva_compensation._reconciliation module

IVA compensation reconciliation decision data models.

The live AEAT wallet is external state. Local Modelo 303 recurrence is internal reconstruction. These pure typed records describe the evidence sources, the explicit taxpayer override, and the effective binding decision consumed by Modelo 303 calculation. They carry no adapter or application coupling: the orchestration that produces them from live wallet observations and prior-filing recurrence stays in the application layer.

The IvaCompensationReconciliationDecision model encodes the regulatory invariant relating selected_authority to selected_amount and the blocked-wallet refusal in its model_validator.

class IvaCompensationOverride(**data)[source]

Bases: BaseModel

Explicit taxpayer override for Modelo 303 prior compensation.

Parameters:
amount: Decimal
reason: str
evidence_locator: str
recorded_at: datetime
class IvaCompensationAuthoritySource(**data)[source]

Bases: BaseModel

One evidence source considered by an IVA compensation decision.

Parameters:

  • source_kind (IvaCompensationAuthorityKind)

  • amount (Decimal | None)

  • source_locator (str)

  • captured_at (datetime | None)

  • source_modelo (str | None)

  • source_filing_year (int | None)

  • source_periods (tuple[Period, ...])

source_kind: IvaCompensationAuthorityKind
amount: Decimal | None
source_locator: str
captured_at: datetime | None
source_modelo: str | None
source_filing_year: int | None
source_periods: tuple[Period, ...]
class IvaCompensationReconciliationDecision(**data)[source]

Bases: BaseModel

Effective prior-compensation binding decision for Modelo 303.

This record is persisted and replayed by calculation. A live wallet fetch creates evidence; this decision says whether that evidence can safely drive the binding or whether review is required.

Parameters:
taxpayer_nif: str
target_year: int
target_period: Period
selected_authority: IvaCompensationAuthority
selected_amount: Decimal | None
wallet_amount: Decimal | None
local_recurrence_amount: Decimal | None
override_amount: Decimal | None
divergence: IvaCompensationDivergence
blocked: bool
stale_wallet: bool
reason: str
wallet_captured_at: datetime | None
authority_sources: tuple[IvaCompensationAuthoritySource, ...]
decided_at: datetime
class IvaCompensationWalletObservationProtocol(*args, **kwargs)[source]

Bases: Protocol

Structural port for an AEAT IVA-compensation wallet observation.

Lets the reconciliation decision logic stay in the domain without importing the Sede adapter record that produces it; the adapter’s IvaCompensationWalletObservation satisfies this protocol structurally. Members are read-only (the reconciliation only reads them), which keeps the protocol covariant so a record whose attributes are subtypes (e.g. an AnyHttpUrl source_url) still satisfies it.

property taxpayer_nif: str
property target_year: int
property target_period: Period
property total_pending: Decimal
property source_url: object
property captured_at: datetime
class LocalIvaCompensationRecurrenceProtocol(*args, **kwargs)[source]

Bases: Protocol

Structural port for a local Modelo 303 recurrence record.

The application’s LocalIvaCompensationRecurrence satisfies this protocol structurally; the domain projects it into an authority source without importing the application layer. Members are read-only for covariance.

property amount: Decimal
property binding_id: object
property source_kind: str
property source_modelo: object
property source_filing_year: int
property source_periods: tuple[Period, ...]
property resolved_at: datetime
reconcile_iva_compensation_wallet(*, taxpayer_nif, target_year, target_period, wallet, local_recurrence_amount, local_recurrence_source=None, override=None, decided_at=None, max_wallet_age_days=31, is_first_iva_period=False)[source]

Return the IvaCompensationReconciliationDecision for casilla 110.

Return type:

IvaCompensationReconciliationDecision

Parameters:
local_recurrence_authority_source(recurrence)[source]

Project a local Modelo 303 recurrence record into an IvaCompensationAuthoritySource.

Return type:

IvaCompensationAuthoritySource | None

Parameters:

recurrence (LocalIvaCompensationRecurrenceProtocol | None)

validate_wallet_matches_snapshot(wallet, *, taxpayer_nif, target_year, target_period)[source]

Refuse a wallet observation that does not match the requested Modelo 303 target.

Return type:

None

Parameters: