aeat.application.workflow._engine module

Composition root for the end-user composite workflow engine.

WorkflowEngine walks the filing pipeline in strict linear order. Every stage lives in its own small _stage_* method so the bailout matrix is trivially auditable — a reader drops into a single stage method to see exactly which abort reasons it can produce. The engine derives a Schedule from the injected deadline adapter to gate the filing window against the active obligation calendar.

Safety invariants enforced by this module:

  • The engine never touches AEAT-side state directly; every boundary call flows through an injected Protocol or callable seam.

class WorkflowEngine(*, deadline_engine, filing_draft_builder, submission_engine, session, certificate_bundle, inputs_provider, settings, expedientes_source=None, notifications_source=None)[source]

Bases: object

Ordered orchestrator across every AEAT building block.

Construction takes one Protocol handle per component. The authenticated AEAT session and the certificate bundle are optional: when None, the stages that consume them run in skip mode and surface a diagnostic instead of failing.

Parameters:
async run_next(profile, *, fail_on_warning=False, today=None)[source]

Drive the workflow for the caller’s next obligation.

Parameters:

  • profile (TaxpayerProfile) – The TaxpayerProfile to run for.

  • fail_on_warning (bool) – Forwarded to the filing draft builder.

  • today (date | None) – Reference date for deadline / preflight checks. Defaults to date.today().

Return type:

WorkflowResult

Returns:

A fully populated WorkflowResult.

async run_for_period(profile, modelo, period, *, fail_on_warning=False, today=None, resumed_from=None, purpose=WorkflowPurpose.FILE)[source]

Drive the workflow for a caller-specified (modelo, period).

Parameters:

  • profile (TaxpayerProfile) – The TaxpayerProfile to run for.

  • modelo (str) – Target modelo identifier.

  • period (Period) – Target period identifier.

  • fail_on_warning (bool) – See run_next().

  • today (date | None) – See run_next().

  • resumed_from (str | None) – Optional prior workflow run_id that this invocation continues. When set, the produced WorkflowResult carries the linkage so callers can trace the resume chain. The engine does not validate the prior run by itself; the upstream resume action resolves and gates the prior context before invoking.

  • purpose (WorkflowPurpose) – Why the run is being driven. FILE (the default) treats the filing-window deadline as an abort gate; VERIFY records it as informational context and never aborts on it, so a calculation can be verified independently of the AEAT calendar.

Return type:

WorkflowResult

Returns:

A fully populated WorkflowResult.

Raises:

WorkflowInputMismatchError – When resumed_from is supplied but is not a valid 16-character lowercase hex run id.