aeat.application.overview._calendar module

Calendar aggregation and evidence merge for the overview read model.

The facade composes a Schedule from TaxpayerProfile facts and projects already-loaded local state into OverviewCalendar DTOs. Legal obligation rows come from the deadline engine; observed OverviewCalendarEvent rows and OverviewCalendarFilingEvidence rows come from persisted Modelo records, local live-read snapshots, and loaded justificante metadata supplied by the caller.

This module is local-only and pure with respect to I/O: it never starts a live AEAT read and never verifies a justificante by fetching external state. It only reconciles evidence the storage or CLI layer has already loaded, preserving distinct OverviewLocalFilingState and OverviewAeatSubmissionState axes.

See also

aeat.application.overview

Public facade that re-exports these calendar builders and DTOs.

DeadlineEngine

Deadline authority that produces the legal obligation schedule merged into the overview calendar.

calendar_filing_evidence_from_sources()

Pure evidence merge for local filing records, live captures, filed-declaration observations, and loaded justificante metadata.

JustificanteCaptureSnapshot

Persisted live justificante capture projected as AEAT-side evidence only when matching metadata is already loaded.

ModeloRecord

Local filing record projected on the local filing axis, separate from AEAT submission state.

calendar_events_from_expedientes_snapshots(snapshots, calendar_range, *, expected_tax_id=None)[source]

Project persisted declaration-register snapshots into calendar events.

Each in-range declaration becomes an OverviewCalendarEvent when its authenticated identity matches expected_tax_id. Only active ALTA rows carry OverviewAeatSubmissionState.SUBMITTED_OBSERVED; non-active rows remain historical events and cannot upgrade OverviewCalendarFilingEvidence.

Return type:

tuple[OverviewCalendarEvent, ...]

Parameters:
calendar_events_from_notification_snapshots(snapshots, calendar_range, *, expected_tax_id=None)[source]

Project persisted AEAT notifications into message events.

Notifications become OverviewCalendarEventType.MESSAGE rows only; they are additive calendar observations and never imply OverviewAeatSubmissionState or filing evidence for an obligation.

Return type:

tuple[OverviewCalendarEvent, ...]

Returns:

A tuple of OverviewCalendarEvent message observations inside calendar_range.

Parameters:
calendar_events_from_justificante_capture_snapshots(snapshots, calendar_range, *, justificantes=(), expected_tax_id=None)[source]

Project verified live justificante captures into calendar filing events.

A JustificanteCaptureSnapshot becomes an OverviewCalendarEvent only after loaded Justificante metadata proves the same CSV/model/year/period/taxpayer tuple. The event therefore carries OverviewAeatSubmissionState.JUSTIFICANTE_VERIFIED without opening a new live read.

Return type:

tuple[OverviewCalendarEvent, ...]

Parameters:
build_overview_calendar_events(*, calendar_range, expedientes_snapshots=(), notification_snapshots=(), justificante_capture_snapshots=(), justificantes=(), expected_tax_id=None)[source]

Build observed events from persisted live-read snapshots.

The snapshots are inputs loaded by the caller. This helper only fans out through calendar_events_from_expedientes_snapshots(), calendar_events_from_notification_snapshots(), and calendar_events_from_justificante_capture_snapshots(), then dedupes OverviewCalendarEvent rows by their stable observation keys. It performs no storage or AEAT I/O.

Return type:

tuple[OverviewCalendarEvent, ...]

Parameters:
actionable_post_filing_events(events)[source]

Return the observed OverviewCalendarEvent rows that demand operator attention.

An event is actionable when its post_filing_kind is a member of ACTIONABLE_POST_FILING_EVENT_KINDS — a requerimiento, a propuesta / acuerdo de liquidación, a procedimiento sancionador, or a recaudación enforcement act (providencia de apremio or diligencia de embargo). These are the post-filing events an operator must not miss; the overview surfaces them so a pulled requerimiento is not buried in an undifferentiated message list.

The result preserves the input order (the callers pass deduped, sort-stable event tuples).

Return type:

tuple[OverviewCalendarEvent, ...]

Parameters:

events (tuple[OverviewCalendarEvent, ...])

calendar_events_from_modelo_records(filing_records, calendar_range, *, justificantes=(), expected_tax_id=None)[source]

Project persisted Modelo filing records into calendar filing events.

A ModeloRecord always contributes on the OverviewLocalFilingState axis. It only contributes OverviewAeatSubmissionState when its external evidence reference is corroborated by loaded Justificante metadata for the same taxpayer and filing target.

Parameters:
Return type:

tuple[OverviewCalendarEvent, ...]

Returns:

A tuple of OverviewCalendarEvent, one per in-range record.

build_overview_calendar(profile, calendar_range, *, today, engine=None, raw_values=None, show_suppressed=False, events=(), filing_evidence=(), work_units=(), live_censo_verified_profile_keys=None)[source]

Build a typed calendar view for profile over calendar_range.

Composes the existing DeadlineEngine over each year the range spans, filters obligations to those whose filing window intersects the range, attaches the user-state mapping, merges already-loaded OverviewCalendarFilingEvidence, enriches OverviewCalendarEvent rows, and returns the typed OverviewCalendar. The builder does not load repositories and does not contact AEAT.

Parameters:

  • profile (TaxpayerProfile) – The operator’s TaxpayerProfile.

  • calendar_range (OverviewCalendarRange) – Inclusive date window to enumerate.

  • today (date) – Reference date for engine status classification.

  • engine (ScheduleProducer | None) – Optional ScheduleProducer the caller wants to share across queries — a concrete DeadlineEngine or any object satisfying the schedule-producing protocol. When None, a default DeadlineEngine is constructed.

  • raw_values (Mapping[str, object] | None) – Optional mapping of casilla id to raw value, forwarded to the engine for user-state annotation. When None, the engine uses an empty mapping.

  • show_suppressed (bool) – When True, populate OverviewCalendar.suppressed_entries with the obligations filtered out by a non-APPLICABLE applicability verdict. Default is False — the standard calendar view excludes suppressed rows from the payload entirely.

  • events (tuple[OverviewCalendarEvent, ...]) – Optional observed calendar events, usually projected from persisted local live-read snapshots by the CLI.

  • filing_evidence (tuple[OverviewCalendarFilingEvidence, ...]) – Optional local/AEAT evidence rows keyed to calendar obligations. These rows are preloaded by callers that own storage access; the calendar builder only merges them onto legal deadline entries.

  • work_units (tuple[WorkUnit, ...]) – Optional active or audit-loaded Modelo work units. Active units are merged onto matching registry rows or projected as local-work-unit rows when registry windows do not cover the historical target.

  • live_censo_verified_profile_keys (tuple[str, ...] | None) – Optional profile paths whose current values carry live Modelo 036 / censo provenance. When supplied, active Modelo rows whose applicability cannot be tied to any such path receive a blocking calendar warning.

Return type:

OverviewCalendar

A year inside the range with no registered deadline windows is treated as a “no data yet” state: that year contributes zero entries and the calendar still succeeds for every year that does have window data. This is the same graceful degradation overview explain applies to a modelo/year pair with no registered windows.

Return type:

OverviewCalendar

Returns:

A OverviewCalendar with one entry per (modelo, period) whose filing window intersects the range.

Parameters: