cadrumo.domain.submission.models module

Strict pydantic v2 records for the filing submission engine.

Every type that crosses a public boundary is a strict+frozen pydantic.BaseModel or a closed enum.StrEnum. No dataclasses; no bare dict[str, Any].

The records describe a local or imported filing audit trail. They do not authorize a live AEAT write; live-write refusal stays with the core access gate and application facades compose these records into draft/import flows.

See also

cadrumo.domain.submission.engine.SubmissionEngine

Runs preflight and reads these records from the repository.

cadrumo.application.modelo.external_import_actions.import_external_filing_evidence()

Attaches external filing evidence to a modelo record from a validated justificante.

ModeloRecord

Work-unit filing record used by the modelo application facade.

cadrumo.application.live

Read-only live-capture surface that may attach AEAT evidence to existing local filing records.

class SubmissionStatus(*values)[source]

Bases: StrEnum

Lifecycle status of a ModeloPresentado.

Values are retained for historical records imported from AEAT, even though live AEAT submission is now permanently forbidden. Member names and values mirror the AEAT Sede labels.

Variables:

  • PENDIENTE_DE_PRESENTAR – Filing recorded but no attempt has run.

  • EN_TRAMITACION – An attempt is currently underway.

  • PRESENTADA – Attempt completed; awaiting AEAT acknowledgement.

  • ACEPTADA – AEAT issued a justificante CSV and PDF.

  • RECHAZADA – AEAT explicitly rejected the filing.

  • FALLIDA – Attempt could not complete (transport / browser).

PENDIENTE_DE_PRESENTAR
EN_TRAMITACION
PRESENTADA
ACEPTADA
RECHAZADA
FALLIDA
class ModeloDraftStatus(*values)[source]

Bases: StrEnum

Lifecycle status of a modelo draft, spanning preparation and submission.

The state machine carries a draft from creation through validation, operator approval, submission, and the AEAT-side terminal states. The preflight engine consumes only APROBADO and APROBACION_CADUCADA on its happy path; the broader filing / submission stack consumes the full lifecycle. Member names and values mirror the AEAT Sede labels.

Variables:

  • BORRADOR – New draft, not yet validated.

  • VALIDADO – Validation rules executed without errors.

  • LISTO_PARA_PRESENTAR – Draft fully prepared for an attempt.

  • APROBADO – Operator-approved for submission.

  • APROBACION_CADUCADA – Approval timestamp aged out.

  • PRESENTADA – A submission attempt is recorded.

  • ACEPTADA – AEAT acknowledged the filing.

  • RECHAZADA – AEAT rejected the filing.

  • ENMENDADO – Superseded by an amendment record.

  • ANULADO – Operator cancelled before submission.

BORRADOR
VALIDADO
LISTO_PARA_PRESENTAR
APROBADO
APROBACION_CADUCADA
PRESENTADA
ACEPTADA
RECHAZADA
ENMENDADO
ANULADO
class SubmissionAttempt(**data)[source]

Bases: BaseModel

A historical attempt record imported or retained locally.

Variables:

  • attempt_id – Stable identifier for this attempt (<submission_id>.<ordinal>).

  • started_at – UTC timestamp when the attempt began.

  • ended_at – UTC timestamp when the attempt ended (success or failure).

  • status – Terminal SubmissionStatus for the attempt.

  • error_code – Optional machine-readable error code.

  • error_message – Optional multilingual error message.

  • browser_trace_path – Optional path to a Playwright trace file written for this attempt.

Parameters:

data (Any)

attempt_id: SubmissionAttemptId
started_at: UtcInstant
ended_at: UtcInstant
status: SubmissionStatus
error_code: str | None
error_message: str | None
browser_trace_path: Path | None
class ModeloPresentado(**data)[source]

Bases: BaseModel

The typed audit record for one historical filing.

Variables:

  • submission_id – Stable SHA-256-derived hex digest of f"{draft_id}:{attempt_ordinal}". See the SubmissionId digest form.

  • draft_id – The upstream draft identifier.

  • modelo – The AEAT modelo identifier.

  • period – The Period covered, serialised as {"filing_year": int, "code": str} across the persistence boundary.

  • profile_tax_id – The validated taxpayer identity value carried by the upstream draft or imported receipt.

  • status – The overall SubmissionStatus for the filing.

  • justificante_csv – The AEAT-issued CSV, when present.

  • justificante_pdf_path – Local path to the justificante PDF, when present.

  • submitted_at – UTC timestamp of the first attempt start.

  • acknowledged_at – UTC timestamp the user acknowledged the filing, when set.

  • attempts – Non-empty tuple of SubmissionAttempt records in chronological order.

Parameters:

data (Any)

submission_id: SubmissionId
draft_id: str
modelo: Modelo
period: Period
profile_tax_id: SubjectTaxId
status: SubmissionStatus
justificante_csv: AeatCsv | None
justificante_pdf_path: Path | None
submitted_at: UtcInstant
acknowledged_at: UtcInstant | None
attempts: tuple[SubmissionAttempt, ...]