aeat.application.modelo._filing_actions module

Filing-record actions for modelo calculation revisions.

file_modelo_revision() promotes a verified CalculationRevision into a current ModeloRecord after the WorkflowEngine preflight gate passes. Filing transitions and audit entries are persisted through the BucketEventHistoryRepository path shared by the modelo revision services.

The action records the operator’s local/internal filing state only. It never submits to AEAT, never marks AEAT acceptance, and never fabricates official external evidence. A successful transition sets the target revision to PRESENTADO, creates a VIGENTE ModeloRecord with aeat_accepted=False, and delegates cross-period carry projection to persist_filed_revision(), which stamps locally-filed observations as non-official app_filing evidence.

See also

import_external_filing_evidence():

Separate AEAT-attested import path that creates ExternalEvidence baselines; this local filing action deliberately does not.

persist_filed_revision():

Persists the filing catalogue, revision state, work-unit pointers, bucket events, participation index rows, and optional carry observation.

persist_filed_revision_observation():

Projects filed casillas into non-official cross-period observations.

resolve_modelo_result_disposition():

Resolves the shared Modelo 303 refund/carry disposition before the file transition persists.

_require_cross_period_clean_state():

Rechecks cross-period dependencies before local filing state is written.

exception ModeloFilingEvidenceMissingError(message=None, *, context=None, suggestion=None, translated_message=None)[source]

Bases: ModeloError

Raised when internal filing would seal deductible IVA without evidence.

Parameters:

  • message (str | None)

  • context (Mapping[str, object] | None)

  • suggestion (str | None)

  • translated_message (str | None)

Return type:

None

code: ClassVar[ErrorCode]
file_modelo_revision(calculation_revision_id, *, actor, workflow_profile, notes=None, refund_election=RefundElection.COMPENSAR, work_unit_repository=None, calculation_repository=None, filing_repository=None, verification_repository=None, bucket_event_repository=None, iva_compensation_decision_repository=None, calculation_observation_repository=None, cross_period_expected_member_sets=(), workflow_engine=None, workflow_runs_dir=None, settings=None, clock=None)[source]

Mark a verified-complete revision as the current internal filed answer.

This is the application service behind aeat app modelo work file. It is a local state transition, not an AEAT presentation: the resulting ModeloRecord has aeat_accepted=False and no external evidence.

Preconditions and state changes:

  1. Verify the revision is in VERIFICADO_COMPLETO state.

  2. Recheck profile readiness, persisted Modelo 303 IVA-wallet decision compatibility, and cross-period clean state.

  3. Run the WorkflowEngine gate for the revision’s modelo and period.

  4. Resolve the Modelo 303 refund/carry disposition from RefundElection and TaxpayerProfile.

  5. If a prior current filing exists, mark its ModeloRecord as SUPERSEDIDO and its prior CalculationRevision as PRESENTADO_SUPERSEDIDO.

  6. Create the new filing record with status VIGENTE and transition the target calculation revision from VERIFICADO_COMPLETO to PRESENTADO.

  7. Advance the work unit’s filed_calculation_revision_id and current_filing_record_id pointers, emit MODELO_FILED/ MODELO_FILED_SUPERSEDED bucket events, and persist any local app_filing carry observation.

Parameters:

  • calculation_revision_id (str) – The id of the verified-complete revision to file.

  • actor (str) – Operator identifier recorded in the filing record and audit trail.

  • workflow_profile (TaxpayerProfile) – The TaxpayerProfile used to evaluate WorkflowEngine gate conditions and cross-period clean-state applicability.

  • notes (str | None) – Optional operator-supplied filing notes.

  • refund_election (RefundElection) – The operator’s per-filing Modelo 303 negative-result disposition election. Defaults to COMPENSAR (carry the credit forward). DEVOLVER requests the credit back as a refund and is honoured only when the period is a lawful refund period (the year’s last filing period for a non-REDEME taxpayer; every period for REDEME). An out-of-window DEVOLVER is refused.

  • work_unit_repository (WorkUnitCatalogueRepositoryProtocol | None) – Optional work-unit catalogue repository override.

  • calculation_repository (CalculationRevisionCatalogueRepositoryProtocol | None) – Optional calculation-revision catalogue repository override.

  • filing_repository (ModeloRecordCatalogueRepositoryProtocol | None) – Optional filing-record catalogue repository override.

  • verification_repository (VerificationReportCatalogueRepositoryProtocol | None) – Optional verification-report catalogue repository override used by the cross-period clean-state proof.

  • bucket_event_repository (BucketEventHistoryRepositoryProtocol | None) – Optional bucket-event history repository override.

  • iva_compensation_decision_repository (IvaWalletDecisionRepository | None) – Optional IVA wallet decision repository override used to require that a persisted decision still matches the target revision.

  • calculation_observation_repository (CalculationObservationRepository | None) – Optional calculation-observation repository override used by the cross-period clean-state proof and the non-official local carry projection.

  • cross_period_expected_member_sets (Iterable[CrossPeriodExpectedMemberSet]) – Optional expected grupo member rosters used by the cross-period clean-state proof.

  • workflow_engine (WorkflowEngine | None) – Optional workflow engine override for the preflight gate.

  • workflow_runs_dir (Path | None) – Optional workflow runs directory override.

  • settings (Settings | None) – Optional settings override.

  • clock (datetime | None) – Optional UTC timestamp override.

Return type:

ModeloRecord

Returns:

The newly created local ModeloRecord in VIGENTE status.

Raises:

See also

persist_filed_revision():

Performs the repository writes once all gates pass.

import_external_filing_evidence():

Creates official-evidence baselines for imported filings; use that path when a ExternalEvidence reference must be carried.

persist_filed_revision_observation():

Saves the non-official app_filing observation used by later previous_filing calculations.

export_modelo_revision():

Sibling local finish line that writes the fichero-BOE artefact without requiring this internal file marker.

list_filing_records(*, bucket_id=None, modelo=None, include_superseded=False, filing_repository=None)[source]

List ModeloRecord rows, optionally filtered to a bucket and modelo.

Superseded records are excluded unless include_superseded is true. Results are sorted by (bucket_id, filing_year, modelo, period, filed_at).

Return type:

tuple[ModeloRecord, ...]

Parameters:
get_filing_record(filing_record_id, *, filing_repository=None)[source]

Return the ModeloRecord for the given id, or raise.

Return type:

ModeloRecord

Parameters:
list_verification_reports(*, calculation_revision_id=None, verification_repository=None)[source]

List VerificationReport records.

Optionally filtered to one CalculationRevision. The VerificationReportCatalogueRepositoryProtocol supplies the persisted report catalogue. Results are sorted by (calculation_revision_id, run_at).

Return type:

tuple[VerificationReport, ...]

Parameters:
get_verification_report(verification_report_id, *, verification_repository=None)[source]

Return one VerificationReport by id, or raise.

The optional VerificationReportCatalogueRepositoryProtocol supplies the persisted report catalogue for tests or alternate storage boundaries.

Return type:

VerificationReport

Parameters: