cadrumo.domain.modelos.filing_record module

Filing-record store paired with filed calculation revisions.

A ModeloRecord is the durable receipt of an internal filing event: at time T, actor A marked calculation revision R of work unit W as the current filed answer for (bucket, modelo, year, period). The filing record holds filing-event state (filed timestamp, actor, notes, origin, AEAT confirmation state, declaration kind, supersession and amendment links); the filed calculation revision holds the immutable calculation result. The two are paired so the calculation revision never accretes filing-side concerns.

There is at most one current filing record per (bucket_id, modelo, filing_year, period) tuple. When a later verified revision is filed, the previous current record is superseded — its superseded_by_filing_record_id is set, the calculation revision it pointed at moves from FILED to FILED_SUPERSEDED, and the new filing record becomes current. Both records remain in the catalogue for audit.

The records of one tuple form a linear chain. A local filing is only an intention (PENDIENTE) until an AEAT register entry proves it was presented (CONFIRMADA); only confirmed records carry ExternalEvidence, and the filing record itself never initiates a live submission.

class ModeloRecordStatus(*values)[source]

Bases: StrEnum

Closed enumeration of filing-record lifecycle states.

  • VIGENTE — the record is the currently-effective filed answer for its (bucket, modelo, year, period) tuple.

  • SUPERSEDIDO — a later filing replaced this one. The record remains for audit; superseded_by_filing_record_id points at the successor.

VIGENTE
SUPERSEDIDO
class ExternalEvidenceKind(*values)[source]

Bases: StrEnum

Closed catalogue of external-evidence kinds.

A ModeloRecord marked with one of these kinds carries imported official evidence (justificante, CSV register, or live capture) rather than a tool-computed calculation revision. This is the gate amend_modelo_revision() requires before it accepts an amendment baseline.

AEAT_JUSTIFICANTE_PDF
AEAT_CSV_REGISTER
AEAT_LIVE_CAPTURE
is_justificante_backed_external_evidence(kind)[source]

Return whether kind requires matching persisted receipt metadata.

Every current external-evidence kind is filing-grade only after its reference resolves to a matching domain.justificante.schema.Justificante. Keeping this closed policy beside the enum prevents application consumers from silently disagreeing when a new evidence kind is introduced.

Return type:

bool

Parameters:

kind (ExternalEvidenceKind)

is_receipt_bound_external_evidence(kind)[source]

Return whether kind requires persisted Justificante metadata.

Return type:

bool

Parameters:

kind (ExternalEvidenceKind)

class ExternalEvidence(**data)[source]

Bases: BaseModel

Imported-evidence metadata for an externally-filed return.

Populated by import_external_filing_evidence() for a current ModeloRecord; consumed by amend_modelo_revision() as the gate that proves the baseline is AEAT-attested and not a fabricated local draft.

Parameters:

data (Any)

kind: ExternalEvidenceKind
reference_id: EvidenceReference
imported_at: UtcInstant
class FilingOrigin(*values)[source]

Bases: StrEnum

Who authored a chain entry: this application, or AEAT’s own register.

LOCAL
AEAT
class AeatConfirmationState(*values)[source]

Bases: StrEnum

Whether AEAT has been seen to hold a chain entry.

  • PENDIENTE – filed locally, not yet observed at AEAT.

  • CONFIRMADA – backed by an AEAT register entry and its evidence.

  • DISCREPANTE – AEAT holds different content for the presentation; the entry is superseded by the AEAT entry.

  • DESCARTADA – a pending entry replaced before it was ever presented.

PENDIENTE
CONFIRMADA
DISCREPANTE
DESCARTADA
class FilingDeclarationKind(*values)[source]

Bases: StrEnum

Legal kind of a declaration in a period’s chain.

ORIGINAL
COMPLEMENTARIA
SUSTITUTIVA
RECTIFICATIVA
declaration_kind_for_tipo_solicitud(tipo_solicitud)[source]

Return the correction kind an AEAT register tipo_solicitud names, or None.

Only a value naming exactly one correction kind is read; any other value, including one describing an original declaration, stays None so the caller never assumes a kind AEAT did not state.

Return type:

FilingDeclarationKind | None

Parameters:

tipo_solicitud (str | None)

class AeatRegisterRef(**data)[source]

Bases: BaseModel

AEAT’s own identifiers for one presented declaration.

The register expediente and the receipt identifiers (CSV and número de justificante) are different AEAT namespaces; each is None when the source did not state it, and at least the expediente or the CSV is present. presented_at is optional because a printed justificante states a Europe/Madrid wall-clock time without an offset, and no instant may be invented from it.

Parameters:

data (Any)

expediente_id: EvidenceReference | None
csv: AeatCsv | None
justificante_number: AeatPresentationId | None
tipo_solicitud: _TipoSolicitud | None
presented_at: UtcInstant | None
derive_filing_record_id(*, work_unit_id, calculation_revision_id, filed_by, member_nif=None)[source]

Deterministic 64-char SHA-256 id for a filing record.

Content-addressed by the filing outcome - the parent work unit, the filed calculation revision, the actor, and (for member-scoped group filings) the member NIF. filed_at is deliberately excluded from the identity so a re-file of the same revision by the same actor resolves to the same record (an idempotent re-file is a no-op, not a new time-stamped duplicate); filed_at is retained on ModeloRecord as a non-identity last-seen field. Member-scoped group filings include the member NIF in the identity; single-filer records omit it.

Return type:

str

Parameters:

  • work_unit_id (str)

  • calculation_revision_id (CalculationRevisionId)

  • filed_by (str)

  • member_nif (str | None)

class ModeloRecord(**data)[source]

Bases: BaseModel

Durable receipt of one internal filing event for an AEAT modelo (tax form).

Pairs a filed CalculationRevisionId with the filing event metadata (actor, timestamp, notes, origin, confirmation state, declaration kind, supersession and amendment links). The id is content-addressed by the filing outcome - work_unit_id, calculation_revision_id, filed_by, and (for member-scoped group filings) member_nif - via derive_filing_record_id(); filed_at is a non-identity last-seen field, so a re-file of the same revision by the same actor is an idempotent no-op rather than a new record. A model_validator enforces the derivation on construction.

confirmation records externally-observed AEAT acceptance; it does not imply that the application submitted anything. CONFIRMADA travels with ExternalEvidence and no other state carries it. An AEAT-origin record is always CONFIRMADA; the retired states (DISCREPANTE, DESCARTADA) are local entries that are no longer in force.

Parameters:

data (Any)

filing_record_id: FilingRecordId
work_unit_id: WorkUnitId
calculation_revision_id: CalculationRevisionId
bucket_id: BucketId
modelo: ModeloCode
filing_year: FilingYear
period: Period
member_nif: _MemberNif | None
filed_at: UtcInstant
filed_by: ModeloActorLabel
notes: FilingNotes | None
origin: FilingOrigin
confirmation: AeatConfirmationState
declaration_kind: FilingDeclarationKind
aeat_register: AeatRegisterRef | None
status: ModeloRecordStatus
superseded_at: UtcInstant | None
superseded_by_filing_record_id: FilingRecordId | None
external_evidence: ExternalEvidence | None
amends_filing_record_id: FilingRecordId | None
source_transaction_ids: tuple[TransactionId, ...]
property aeat_accepted: bool

Return whether AEAT has been observed to hold this entry.

property is_retired: bool

Return whether the entry left the chain without being the presented declaration.

class ModeloRecordCatalogue(**data)[source]

Bases: BaseModel

Immutable catalogue of every filing record in a bucket’s storage.

Keyed by filing_record_id; the model validator enforces that every key equals the id of the ModeloRecord it maps to, and that at most one record per (bucket_id, modelo, filing_year, period, member_nif) tuple carries status=VIGENTE. Iteration yields ModeloRecord values (not key–value pairs) — the override is annotated with a suppression comment on __iter__.

Parameters:

data (Any)

records: Mapping[str, ModeloRecord]
get(filing_record_id)[source]

Return the ModeloRecord for filing_record_id, or None.

Return type:

ModeloRecord | None

Parameters:

filing_record_id (str)

current_for(*, bucket_id, modelo, filing_year, period, member_nif=None)[source]

Return the current (non-superseded) ModeloRecord for a filing tuple.

Returns None when no filing has ever happened for the tuple. member_nif=None means the single-filer or aggregate record, not every member. Returns the active filing record when one exists. Never returns a superseded record — callers must iterate records directly to walk audit history.

Return type:

ModeloRecord | None

Parameters:
latest_confirmed_for(*, bucket_id, modelo, filing_year, period, member_nif=None)[source]

Return the most recent AEAT-confirmed record for a filing tuple.

This is the declaration a correction must reference. It differs from current_for() while a local entry is pending.

Return type:

ModeloRecord | None

Parameters:
history_for(*, bucket_id, modelo, filing_year, period, member_nif=None)[source]

Return every filing record for a tuple, ordered by filed_at.

Return type:

tuple[ModeloRecord, ...]

Returns:

Tuple of ModeloRecord objects ordered by filing timestamp.

Parameters:
values()[source]

Return a view of all ModeloRecord values in the catalogue.