aeat.application.modelo._quickfile module

One-command modelo filing orchestration: readiness → calculate → verify → export.

run_modelo_quickfile sequences the existing single-stage modelo application services for one (modelo, filing_year, period) target and returns a typed QuickfileResult recording every stage’s outcome. It resolves readiness, resumes or creates the work unit (application.modelo.ensure_modelo_work_unit_for_visible_target()), calculates a draft revision (application.modelo.calculate_modelo_work_revision()), verifies it (application.modelo.verify_modelo_revision()), and exports the verified revision to a local fichero-BOE artefact (application.modelo.export_modelo_revision()).

This orchestrator re-implements no stage: every step delegates to the authoritative application service, preserving each service’s guards, lifecycle events, and provenance. It stops instructively at the first stage that refuses — a missing calculation binding, an ungranted verification, or an export gate — marking the remaining stages skipped so the operator sees exactly where the chain halted and why.

The chain is BUILD + EXPORT only. It never performs a live AEAT submission and never contacts AEAT: the terminal step is the local fichero-BOE export the human files themselves through the AEAT sede (see application.modelo.export_modelo_revision(), which is local-only, and the aeat-safety-legal-gates rule). The internal file record step is deliberately excluded: export consumes the VERIFICADO_COMPLETO revision directly.

See also

application.modelo.calculate_modelo_work_revision():

The calculate stage this orchestrator drives.

application.modelo.verify_modelo_revision():

The verify stage; a non-granted report halts the chain.

application.modelo.export_modelo_revision():

The terminal local export stage.

class QuickfileStage(*values)[source]

Bases: StrEnum

The ordered stages of the quickfile filing chain.

READINESS
CREATE
CALCULATE
VERIFY
EXPORT
QUICKFILE_STAGE_ORDER: tuple[QuickfileStage, ...]

Canonical stage order the orchestrator walks. Every stage after the one that refuses is recorded as QuickfileStageStatus.SKIPPED.

class QuickfileStageStatus(*values)[source]

Bases: StrEnum

Outcome status for one quickfile stage.

OK — the stage completed and the chain may proceed. WARNING — the stage completed but surfaced a non-blocking advisory (e.g. readiness reported the profile is not yet source-ready, which a caller-supplied --binding may still satisfy). REFUSED — the stage refused and the chain halted here. SKIPPED — a downstream stage that never ran because an earlier stage refused.

OK
WARNING
REFUSED
SKIPPED
class QuickfileStageOutcome(stage, status, message='', translated_message=None, context=<factory>)[source]

Bases: object

The typed result of one quickfile stage.

translated_message and context carry the originating core.errors.AeatError metadata verbatim so the transport layer can localise the refusal without the application layer depending on i18n.

Parameters:
stage: QuickfileStage
status: QuickfileStageStatus
message: str
translated_message: str | None
context: Mapping[str, str]
class QuickfileResult(modelo, filing_year, period, registry_revision_id, stages, completed, stopped_at_stage, readiness, work_unit, calculation_revision, verification_report, export_result)[source]

Bases: object

Aggregate outcome of one run_modelo_quickfile invocation.

completed is True only when the export stage succeeded and a local fichero-BOE artefact was written. stopped_at_stage names the stage that refused when the chain halted early. The intermediate domain records (work_unit, calculation_revision — a CalculationRevision when the calculate stage ran —, verification_report, export_result) are surfaced so the transport can render each stage’s detail, and are None for stages that never ran.

Parameters:
modelo: str
filing_year: int
period: Period
registry_revision_id: str
stages: tuple[QuickfileStageOutcome, ...]
completed: bool
stopped_at_stage: QuickfileStage | None
readiness: ProjectionModeloReadiness | None
work_unit: WorkUnit | None
calculation_revision: CalculationRevision | None
verification_report: VerificationReport | None
export_result: ModeloExportResult | None
class QuickfileCommand(**data)[source]

Bases: BaseModel

Strict input contract for run_modelo_quickfile().

Variables:

  • bucket_id – The active profile bucket the chain runs against.

  • modelo – AEAT modelo code (e.g. 111, 130, 303).

  • filing_year – Filing year of the target period.

  • period – Typed Period for the filing target.

  • registry_revision_id – Optional assertion of the law-determined registry revision. When supplied it is validated against resolve_registry_revision_for_work_target(); it never overrides the law-determined pick.

  • output_path – Destination for the terminal fichero-BOE export.

  • actor – Operator label recorded into each stage’s lifecycle event.

  • refund_election – Per-filing negative-result disposition threaded into the export’s fichero declaration type.

Parameters:
bucket_id: str
modelo: str
filing_year: int
period: Period
registry_revision_id: str | None
output_path: Path
actor: str
refund_election: RefundElection
run_modelo_quickfile(command, *, workflow_profile, build_calculation_inputs)[source]

Run readiness → create → calculate → verify → export for one modelo target.

Each stage delegates to its authoritative application service. The chain halts at the first stage that refuses (a raised core.errors.AeatError, or an ungranted verification), records the refusal, and marks the remaining stages skipped.

build_calculation_inputs is the transport-supplied factory that turns the resolved work-unit id into a validated WorkCalculateInputBundle; the input bundle can only be validated once the work unit (and therefore its registry revision) is known, so the factory is invoked after the create stage.

Parameters:
Return type:

QuickfileResult

Returns:

A QuickfileResult whose completed flag is True only when the terminal export wrote a local fichero-BOE artefact.