aeat.application.filing._review module

Draft approval persistence and stale-detection helpers.

Provides the approve_draft() / unapprove_draft() / refresh_review_status() lifecycle on top of domain.filing.ModeloDraft and domain.submission.ModeloDraftStatus, plus the deterministic domain.filing.ModeloApprovalBasis fingerprint pipeline that lets approval_stale_reasons() detect when a APROBADO draft has been invalidated by upstream changes.

The compute_current_approval_basis() helper accepts optional domain.transactions.TransactionCatalogue and category-profile overrides. When the catalogue override is omitted, it loads the TransactionCatalogue from the encrypted secure-object backend through TransactionCatalogueRepository.

See also

application.filing.build_runtime_schema_provider()

Builds the registry-backed schema provider whose casilla and formula surface participates in the approval basis.

application.review.drafts_pending()

Emits stale filing approvals as high-severity review queue items.

domain.filing.ModeloApprovalBasis

Persisted digest bundle compared during stale detection.

class ModeloApprovalStaleReason(*values)[source]

Bases: StrEnum

Stable reason codes surfaced when a draft approval becomes stale.

Variables:

  • APPROVAL_BASIS_VERSION_CHANGED – The domain.filing.ModeloApprovalBasis schema version has been bumped since approval.

  • DRAFT_PAYLOAD_CHANGED – The draft’s payload fingerprint (draft_id) no longer matches the stored basis.

  • DRAFT_REVIEW_CHANGED – The draft’s validation findings or machine status changed since approval.

  • TRANSACTION_CATALOGUE_CHANGED – Upstream classified transactions have been updated since approval.

  • INVOICE_CATALOGUE_CHANGED – Upstream issued/received invoices (a calculation source resolved through the source mesh) have been updated since approval.

  • PRIOR_FILING_OBSERVATIONS_CHANGED – Prior filed observations in the bucket (the previous_filing carry and relation fold-in source) have been updated since approval.

  • PROFILE_ACTIVITY_CHANGED – The taxpayer profile facts that scope relation resolution (activity-start date, m111 no-retenciones attestations, declared income categories) have changed since approval.

  • CATEGORY_PROFILES_CHANGED – The fiscal category profile catalog has been edited since approval.

  • SCHEMA_FORMULA_CHANGED – The registry-backed casilla schema or formula set has changed since approval.

APPROVAL_BASIS_VERSION_CHANGED
DRAFT_PAYLOAD_CHANGED
DRAFT_REVIEW_CHANGED
TRANSACTION_CATALOGUE_CHANGED
INVOICE_CATALOGUE_CHANGED
PRIOR_FILING_OBSERVATIONS_CHANGED
PROFILE_ACTIVITY_CHANGED
CATEGORY_PROFILES_CHANGED
SCHEMA_FORMULA_CHANGED
compute_current_approval_basis(draft, *, bucket_id, schema_provider, transaction_catalogue=None, invoice_catalogue=None, prior_filing_observations_fingerprint=None, profile_activity_fingerprint=None, category_profiles=None)[source]

Return the ModeloApprovalBasis digests for current upstream state.

The basis hashes the draft identity and validation surface, the supplied or persisted TransactionCatalogue, the supplied or persisted InvoiceCatalogue (a calculation source resolved through the source mesh), the bucket’s prior filed observations (the previous_filing carry and relation fold-in source), the bucket’s taxpayer profile facts that scope relation resolution, the supplied or bundled CategoryProfile mapping, and the active registry schema/formula surface exposed by schema_provider.

The invoice-catalogue, prior-filing-observations, and profile-activity digests make an APROBADO draft stale when its upstream invoices, prior filed values, or relation-scoping profile facts change, closing the gap left by fingerprinting only the ledger transaction catalogue. Like the transaction catalogue they are self-loaded from bucket_id so stale detection is reproducible at refresh time without running the source mesh in the review layer.

Parameters:
Return type:

ModeloApprovalBasis

Returns:

A freshly computed ModeloApprovalBasis.

compute_review_checksum(approval_basis)[source]

Return the canonical SHA-256 hex checksum for approval_basis.

Parameters:

approval_basis (ModeloApprovalBasis) – The basis to hash.

Return type:

str

Returns:

Lowercase hex SHA-256 of the basis’s canonical JSON dump.

approval_stale_reasons(draft, *, bucket_id, schema_provider, transaction_catalogue=None, invoice_catalogue=None, prior_filing_observations_fingerprint=None, profile_activity_fingerprint=None, category_profiles=None)[source]

Return the ordered stale reasons for draft.

The return value is empty when the draft has no approval metadata or when its stored approval basis still matches the freshly recomputed basis.

Parameters:
Return type:

tuple[ModeloApprovalStaleReason, ...]

Returns:

Tuple of ModeloApprovalStaleReason values in evaluation order; empty when the basis is fresh.

approve_draft(draft, *, bucket_id, approved_by, schema_provider, transaction_catalogue=None, invoice_catalogue=None, prior_filing_observations_fingerprint=None, profile_activity_fingerprint=None, category_profiles=None, approved_at=None)[source]

Stamp approval metadata on draft and promote it to APROBADO.

Parameters:
Return type:

ModeloDraft

Returns:

A new ModeloDraft with approval metadata populated.

Raises:

ModeloDraftError – When approved_by is blank or the draft is not in ModeloDraftStatus.LISTO_PARA_PRESENTAR.

unapprove_draft(draft, *, unapproved_at=None)[source]

Remove approval metadata and restore the machine validation status.

Parameters:

  • draft (ModeloDraft) – The draft to revert.

  • unapproved_at (datetime | None) – Optional timestamp; defaults to the canonical clock helper.

Return type:

ModeloDraft

Returns:

A new ModeloDraft with approval metadata cleared and status set to the validation status derived from ModeloDraft.findings.

refresh_review_status(draft, *, bucket_id, schema_provider, transaction_catalogue=None, invoice_catalogue=None, prior_filing_observations_fingerprint=None, profile_activity_fingerprint=None, category_profiles=None, refreshed_at=None)[source]

Return draft with its approval status synchronised to current state.

Downstream-status drafts (submitted / acknowledged / rejected / amended / cancelled) get any leftover approval metadata cleared so historical state cannot pretend to be current. APROBADO drafts transition to ModeloDraftStatus.APROBACION_CADUCADA when approval_stale_reasons() returns a non-empty tuple.

Parameters:
Return type:

ModeloDraft

Returns:

Either draft unchanged (when no transition was needed) or a new ModeloDraft with the appropriate status update.

describe_stale_reason(reason)[source]

Return a short localized explanation for reason.

Parameters:

reason (ModeloApprovalStaleReason) – The ModeloApprovalStaleReason to describe.

Return type:

str

Returns:

A localized phrase suitable for inline UI display.

empty_prior_filing_observations_fingerprint()[source]

Return the digest of an empty prior-filing observation set.

A caller passes this to compute_current_approval_basis() / approve_draft() to stamp a deterministic prior-filing digest without a bucket self-load (e.g. a test approving against a non-active/sentinel bucket with no prior observations), mirroring the empty-InvoiceCatalogue override the invoice fingerprint accepts.

Return type:

str

empty_profile_activity_fingerprint()[source]

Return the digest of an absent taxpayer profile.

A caller passes this to compute_current_approval_basis() / approve_draft() to stamp a deterministic profile digest without a bucket self-load (e.g. a test approving against a non-active/sentinel bucket with no profile), mirroring the empty overrides the other source fingerprints accept.

Return type:

str