cadrumo.application.overview.calendar_models module

Typed DTOs for the overview calendar read model.

The models separate legal obligation rows (OverviewCalendarEntry), observed local events (OverviewCalendarEvent), and filing evidence (OverviewCalendarFilingEvidence). Filing evidence keeps OverviewLocalFilingState distinct from OverviewAeatSubmissionState so local readiness, AEAT submission, and justificante verification remain auditable independent axes.

These DTOs are consumed by application.overview.calendar.build_overview_calendar() and serialized by the overview CLI payload layer. Period-bearing models hydrate serialized Period values back into typed periods so merge keys stay aligned with the registry-token authority.

class OverviewPeriodState(*values)

Bases: StrEnum

Closed user-facing state derived from deadline obligation status.

DUE

LATE

FILED

UNKNOWN

class OverviewCensoEnrolmentState(*values)

Bases: StrEnum

Live Modelo 036 / censo provenance state for one calendar obligation.

NOT_CHECKED

NOT_REQUIRED

UNVERIFIED

VERIFIED

class OverviewCalendarEntrySource(*values)

Bases: StrEnum

Origin of one overview calendar row.

REGISTRY_DEADLINE

LOCAL_WORK_UNIT

class OverviewLocalFilingState(*values)

Bases: StrEnum

Local application-side filing axis for one calendar obligation.

These values describe the application’s internal filing lifecycle only. They are intentionally separate from OverviewAeatSubmissionState so a ready or imported local record cannot imply official AEAT submission.

NOT_READY_TO_FILE

READY_TO_FILE

EXTERNAL_BASELINE_IMPORTED

OverviewLocalFilingStateValue

The local filing lifecycle where a CLI payload must accept the plain token.

Rooted in the enum above rather than respelled; the separation from OverviewAeatSubmissionState that the enum’s own docstring insists on is preserved exactly, because this literal admits only these three members.

alias of Literal[NOT_READY_TO_FILE, READY_TO_FILE, EXTERNAL_BASELINE_IMPORTED]

class OverviewAeatSubmissionState(*values)

Bases: StrEnum

Observed AEAT-side submission evidence for one calendar obligation.

OverviewAeatSubmissionState.NOT_OBSERVED is the default until already-loaded official evidence proves a submitted, accepted, or justificante-verified state. Overview calendar commands never create this evidence by contacting AEAT.

NOT_OBSERVED

SUBMITTED_OBSERVED

ACCEPTED

JUSTIFICANTE_VERIFIED

OverviewAeatSubmissionStateValue

The same vocabulary in the form a payload boundary can accept.

A bare enum under strict validation refuses the plain token a serialised payload carries, and a coercing annotation cannot be used on a surface that forbids a customised core schema. A literal over the enum’s own members accepts the token and adds no hook. Rooted in the vocabulary above, so a member added there reaches this form too.

alias of Literal[NOT_OBSERVED, SUBMITTED_OBSERVED, ACCEPTED, JUSTIFICANTE_VERIFIED]

user_state_for(obligation_status)

Return the OverviewPeriodState for a deadline engine status.

Return type:

OverviewPeriodState

Parameters:

obligation_status (ObligationStatus)

class OverviewCalendarRange(**data)

Bases: BaseModel

Inclusive date window for the overview calendar query.

application.overview.calendar.build_overview_calendar() expands the window to the covered filing years and filters legal obligation rows back to this inclusive range.

Parameters:

data (Any)

from_date: date

to_date: date

covered_years()

Every filing year this range can touch, including the prior one.

The year before the range start is included because a filing window opens in the year after the period it covers.

Return type:

tuple[int, ...]

covers(candidate)

Whether candidate falls inside this range, both ends included.

Return type:

bool

Parameters:

candidate (date)

class OverviewCalendarFilingEvidence(**data)

Bases: _CalendarJustificanteStateInvariant

Filing evidence attached to one legal calendar obligation.

The local fields describe the application’s filing-record axis; the AEAT fields describe observed submission evidence from persisted official sources. Validators require justificante_verified and verified_justificante_csv to agree exactly with OverviewAeatSubmissionState.JUSTIFICANTE_VERIFIED, preventing a malformed event from claiming receipt verification without CSV evidence.

modelo: str | None

filing_year: FilingYear | None

period: _CalendarPeriod | None

local_filing_state: OverviewLocalFilingState

local_filing_record_id: FilingRecordId | None

local_calculation_revision_id: CalculationRevisionId | None

local_filed_at: datetime | None

aeat_submission_state: OverviewAeatSubmissionState

aeat_submitted_at: datetime | None

aeat_reference_id: str | None

aeat_snapshot_id: SnapshotId | None

aeat_evidence_kind: str | None

aeat_evidence_conflict_reference_ids: tuple[str, ...]

verified_justificante_csv: AeatCsv | None

justificante_required: bool

justificante_verified: bool

evidence_source: str | None

class OverviewCalendarEntry(**data)

Bases: BaseModel

One legal (modelo, period) row in the calendar view.

The deadline fields mirror ModeloDeadline. The optional OverviewCalendarFilingEvidence row attaches local and AEAT evidence without changing the legal deadline status from the deadline engine.

Parameters:

data (Any)

modelo: str

period: _CalendarPeriod

opens_on: date

closes_on: date

adjusted_closes_on: date

shift_reason: str

holiday_refs: tuple[str, ...]

jurisdictions: tuple[_HolidayJurisdiction, ...]

payment_cutoff_on: date | None

status: _ObligationStatus

user_state: OverviewPeriodState

recovery: _Recovery | None

recovery_action: DeclaredNextAction | None

filing_year: FilingYear | None

censo_enrolment_state: OverviewCensoEnrolmentState

filing_evidence: OverviewCalendarFilingEvidence

source: OverviewCalendarEntrySource

local_work_unit_id: WorkUnitId | None

local_work_unit_name: str | None

local_work_unit_revision_id: RevisionId | None

class OverviewCalendarEventType(*values)

Bases: StrEnum

Observed event categories shown alongside legal filing windows.

FILING

MESSAGE

OverviewCalendarEventTypeValue

The same event categories for a CLI payload field.

alias of Literal[FILING, MESSAGE]

class OverviewCalendarEvent(**data)

Bases: _CalendarJustificanteStateInvariant

One observed local event attached to an overview calendar range.

Filing events may carry OverviewAeatSubmissionState when a persisted snapshot already observed it. Messages and unverified filings remain event-only observations and do not imply OverviewCalendarFilingEvidence or receipt verification.

post_filing_kind carries the fine-grained PostFilingEventKind procedural category (requerimiento, propuesta de liquidación, diligencia de embargo, …) classified from the pulled notification / expediente, so the coarse event_type axis does not collapse a demand for documents and an informational comunicación onto the same message row.

notificacion_estado_servicio carries the orthogonal NotificacionEstadoServicio service state — whether the notification is still inside its Ley 39/2015 art. 43.2 window, was accessed, or has lapsed into rechazo tácito and is therefore legally served. It is populated only for message rows projected from notification snapshots, where a fecha de notificación and an access flag exist to compute it from; every other event source leaves it None.

event_type: OverviewCalendarEventType

post_filing_kind: _PostFilingEventKind | None

notificacion_estado_servicio: _NotificacionEstadoServicio | None

event_date: date

source: str

summary: _EventSummary

reference_id: str

snapshot_id: SnapshotId | None

modelo: str | None

filing_year: FilingYear | None

period: _CalendarPeriod | None

status: str | None

source_url: SourceUrl | None

authenticated_identity: str | None

aeat_submission_state: OverviewAeatSubmissionState | None

aeat_submitted_at: datetime | None

justificante_verified: bool | None

verified_justificante_csv: AeatCsv | None

class CalendarWarning(**data)

Bases: BaseModel

One under-specified-profile warning attached to a calendar query.

Variables:

• code – Stable warning identity; for a profile-completeness gap this is the profile field’s declared selector token.

• message – Locale key for the operator-facing explanation.

• fix_action –

  The catalogue action that answers this warning. It carries no command string and no CLI path: resolution against the live command surface belongs to the presentation boundary, which projects the resolved form onto this warning’s envelope notice.

  It is excluded from serialization deliberately. An unresolved declaration on the wire would be a second, weaker statement of the same remedy the notice already carries fully resolved, and a remedy field inside a result payload is the shape the envelope contract reserves for the notice channel.

• affected_modelos – Obligation rows this gap can distort.

Parameters:

data (Any)

code: str

message: str

fix_action: DeclaredNextAction

affected_modelos: tuple[str, ...]

class CalendarCompleteness(**data)

Bases: BaseModel

Breakdown of explicit profile values versus deadline-engine defaults.

Parameters:

data (Any)

explicitly_set_keys: tuple[str, ...]

defaulted_keys: tuple[str, ...]

computable_modelos: tuple[str, ...]

defaulted_modelos: tuple[str, ...]

class SuppressedCalendarEntry(**data)

Bases: BaseModel

One non-applicable obligation retained by --show-suppressed.

Parameters:

data (Any)

modelo: str

period: _CalendarPeriod

verdict: ApplicabilityVerdict

reason: str

class OverviewCalendar(**data)

Bases: BaseModel

Result of an aeat app overview calendar query.

entries contains legal filing windows, events contains additive local observations, and suppressed_entries preserves filtered applicability rows only when the caller explicitly requests them. coverage is the always-populated reconciliation of the full registry modelo set against entries: its advised bucket names every filing obligation the surface would otherwise have silently dropped, so a machine consumer never has to infer coverage from the presence or absence of a row.

Parameters:

data (Any)

range: OverviewCalendarRange

entries: tuple[OverviewCalendarEntry, ...]

generated_at: datetime

warnings: tuple[CalendarWarning, ...]

completeness: CalendarCompleteness

taxpayer_model_declared: bool

incomplete_reason: str | None

suppressed_entries: tuple[SuppressedCalendarEntry, ...]

events: tuple[OverviewCalendarEvent, ...]

coverage: ObligationCoverageReport

class OverviewStatusReport(**data)

Bases: BaseModel

Current active-profile readiness counters for overview status.

Produced from OperatorStateProjection by application.overview.status_report.overview_status_report_from_projection().

Parameters:

data (Any)

active_profile_name: str | None

transactions: NonNegativeInt

invoices: NonNegativeInt

drafts: NonNegativeInt

work_units: int

discarded_work_units: int

calculation_revisions: int

unreadable_rows: NonNegativeInt

filing_obligation_advisories: tuple[str, ...]

unsupported_work_create_modelos: tuple[str, ...]