aeat.application.overview._backlog module

Overview backlog: past-due / triage cohort listing.

build_overview_backlog() is the application service backing aeat app overview backlog. It accepts a TaxpayerProfile, composes application.overview.build_overview_calendar() over an operator-supplied date window (defaulting to the last 365 days through today), and enumerates every OverviewCalendarEntry whose adjusted_closes_on precedes today and whose user_state indicates it has not yet been filed.

The verb is a read model only: it never mutates state and never contacts AEAT. Lifecycle continuation is owned by aeat app modelo work resume per the workflow-resumption-semantics ADR.

class OverviewBacklog(**data)[source]

Bases: BaseModel

Outcome of build_overview_backlog.

The model is the backlog-shaped projection of application.overview.OverviewCalendar. Items retain the original OverviewCalendarEntry rows, warnings remain CalendarWarning rows from the calendar build, and completeness is the inherited CalendarCompleteness report.

Variables:

  • range – Calendar window the backlog was scoped to.

  • as_of – Reference date the past-due cohort is computed against.

  • items – Past-due obligations whose user_state is LATE and whose adjusted_closes_on precedes as_of. Sorted ascending by deadline (oldest first) so operators triage the most-overdue obligations first.

  • late_count – Number of items in items (cached for renderers that show a header summary without re-walking the list).

  • generated_at – UTC timestamp of when the aggregator ran.

  • warnings – Calendar warnings inherited from the underlying calendar build (under-specified profile keys).

  • completeness – Calendar completeness inherited from the underlying calendar build.

  • taxpayer_model_declared – Whether the profile carries a usable three-axis taxpayer model. When False the backlog is empty and the operator must declare their taxpayer type first.

  • incomplete_reason – “declare your taxpayer type first” guidance, present only when taxpayer_model_declared is False.

Parameters:
range: OverviewCalendarRange
as_of: date
items: tuple[OverviewCalendarEntry, ...]
late_count: int
generated_at: datetime
warnings: tuple[CalendarWarning, ...]
completeness: CalendarCompleteness
coverage: ObligationCoverageReport
taxpayer_model_declared: bool
incomplete_reason: str | None
build_overview_backlog(profile, *, from_date=None, to_date=None, as_of=None, engine=None, raw_values=None, work_units=())[source]

Enumerate the operator’s past-due obligations.

Parameters:

  • profile (TaxpayerProfile) – The TaxpayerProfile whose filing obligations are evaluated.

  • from_date (date | None) – Start of the calendar window; defaults to 365 days before as_of.

  • to_date (date | None) – End of the calendar window; defaults to as_of.

  • as_of (date | None) – Reference date for past-due classification; defaults to today.

  • engine (DeadlineEngine | None) – Optional DeadlineEngine override.

  • raw_values (Mapping[str, object] | None) – Optional raw profile values passed through to the engine.

  • work_units (tuple[WorkUnit, ...]) – Optional Modelo work units loaded by the caller. When no explicit from_date is supplied, the default range expands back to the earliest active local work unit so historical in-progress work is not silently excluded by the 365-day lookback.

Return type:

OverviewBacklog

The default window is the 365 days preceding as_of (today when omitted), which is wide enough to surface every backlog item that survived a full annual filing cycle without overflowing the underlying deadline-engine schedule.

Past-due classification uses the application.overview.OverviewPeriodState taxonomy: an obligation is in the backlog iff its adjusted_closes_on precedes as_of AND its user_state is LATE. Filed obligations are excluded by the state mapping; the engine surfaces them as FILED rather than OVERDUE.

Returns an OverviewBacklog with the backlog items and the calendar range used for the computation.