aeat.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, AEAT-acceptance bit, supersession link); 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 aeat_accepted flag defaults to False and is independent of internal filing. It exists only to record an externally-observed AEAT acceptance imported into the bucket through evidence channels such as justificante/CSV imports or read-only live capture. When true, external_evidence must carry ExternalEvidence; the filing record itself never initiates a live submission.

ModeloActorLabel

Validated string identifying the operator who filed or triggered a filing event.

Strips surrounding whitespace; must be 1–64 characters after stripping. Used as filed_by on ModeloRecord and feeds into the content-addressed derive_filing_record_id().

alias of Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=64, pattern=None, ascii_only=None)]

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
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:

  • kind (ExternalEvidenceKind)

  • reference_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

  • imported_at (datetime)

kind: ExternalEvidenceKind
reference_id: _EvidenceReference
imported_at: datetime
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 (str)

  • 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, AEAT-acceptance bit, supersession link). 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.

aeat_accepted records externally-observed AEAT acceptance imported through evidence channels; it does not imply that the application submitted anything. It must travel with ExternalEvidence, while locally filed records created by file_modelo_revision() carry neither.

Parameters:

  • filing_record_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[0-9a-f]{64}$, ascii_only=None)])

  • work_unit_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[0-9a-f]{64}$, ascii_only=None)])

  • calculation_revision_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[0-9a-f]{64}$, ascii_only=None)])

  • bucket_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=128, pattern=None, ascii_only=None)])

  • modelo (ModeloCode)

  • filing_year (Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=2000), Le(le=2099)])])

  • period (Period)

  • member_nif (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=32, pattern=None, ascii_only=None)] | None)

  • filed_at (datetime)

  • filed_by (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=64, pattern=None, ascii_only=None)])

  • notes (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=500, pattern=None, ascii_only=None)] | None)

  • aeat_accepted (bool)

  • status (ModeloRecordStatus)

  • superseded_at (datetime | None)

  • superseded_by_filing_record_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[0-9a-f]{64}$, ascii_only=None)] | None)

  • external_evidence (ExternalEvidence | None)

  • amends_filing_record_id (Annotated[str, StringConstraints(strip_whitespace=True, to_upper=None, to_lower=None, strict=None, min_length=64, max_length=64, pattern=^[0-9a-f]{64}$, ascii_only=None)] | None)

  • source_transaction_ids (tuple[str, ...])

filing_record_id: FilingRecordId
work_unit_id: WorkUnitId
calculation_revision_id: CalculationRevisionId
bucket_id: BucketId
modelo: ModeloCode
filing_year: Annotated[int, Field(ge=2000, le=2099)]
period: Period
member_nif: _MemberNif | None
filed_at: datetime
filed_by: ModeloActorLabel
notes: _Notes | None
aeat_accepted: bool
status: ModeloRecordStatus
superseded_at: datetime | None
superseded_by_filing_record_id: FilingRecordId | None
external_evidence: ExternalEvidence | None
amends_filing_record_id: FilingRecordId | None
source_transaction_ids: tuple[str, ...]
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:

records (Mapping[str, ModeloRecord])

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:
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.