aeat.application.overview._explain module

Overview explain: per-(modelo, year) applicability decomposition.

build_overview_explain() is the application service backing aeat app overview explain MODELO [--year YYYY]. The applicable verdict is DERIVED from the three-axis TaxpayerProfile taxpayer model through the registry-grounded derive_modelo_applicability() rule table, never assumed from an autónomo default. An undeclared taxpayer model yields an explicit incomplete verdict: the service reports “declare your taxpayer type first” rather than a confident wrong obligation.

The deadline-engine explain text is still surfaced as the scheduling rationale (when the modelo’s filing windows are registered for the year), but it no longer drives the applicability flag. The service also enumerates the profile keys the answer depends on so the operator can audit them. Local-only: never contacts AEAT.

See also

ModeloRevision

Compiled revision whose deadline windows are matched against the taxpayer profile to build the scheduling rationale.

class DeadlineExplanationEngine(*args, **kwargs)[source]

Bases: Protocol

Protocol for the deadline engine’s scheduling-rationale method.

explain(profile, modelo, *, year=None)[source]
Return type:

str

Parameters:
class OverviewExplain(**data)[source]

Bases: BaseModel

Outcome of build_overview_explain.

The model separates the registry-applicability verdict from the optional deadline-engine scheduling rationale. That keeps ApplicabilityVerdict authoritative even when a known modelo has no registered filing window for the requested year.

Variables:

  • modelo – AEAT modelo identifier the explanation is for.

  • year – The fiscal year the applicability was evaluated against.

  • applicable – Whether the modelo positively applies to the profile this year. Only an ApplicabilityVerdict.APPLICABLE verdict is True; NOT_APPLICABLE and INCOMPLETE are both False — the operator is never told a modelo applies unless the taxpayer model positively justifies it.

  • verdict – The three-state ApplicabilityVerdict derived from the taxpayer model. INCOMPLETE means the operator must declare their taxpayer type first.

  • rationale – Operator-facing prose explaining the verdict, derived from the registry-grounded applicability rule.

  • legal_refs – Opaque BOE / AEAT citation keys grounding the applicability rule. Always at least one entry.

  • scheduling_rationale – The deadline engine’s registry-backed scheduling text, when the modelo’s filing windows are registered for the year. None when no deadline-window data exists (registry-track gap R1) — the applicability verdict is independent of it.

  • out_of_plazo_warning – Warning text when the matching registry filing window closed more than twelve months before the reference date. The warning annotates the voluntary-deadline state and the ordinary four-year LGT prescription horizon without changing the applicability verdict.

  • profile_facts – Subset of the operator’s TaxpayerProfile fields the answer depends on. Keys are stable field names; values are JSON-serialisable scalars.

  • generated_at – UTC timestamp of when the aggregator ran.

Parameters:
modelo: str
year: int
applicable: bool
verdict: ApplicabilityVerdict
rationale: str
legal_refs: tuple[LegalRefId, ...]
scheduling_rationale: str | None
out_of_plazo_warning: str | None
profile_facts: dict[str, _ProfileFactValue]
generated_at: datetime
build_overview_explain(profile, *, modelo, year=None, engine=None, today=None)[source]

Decompose a modelo’s applicability against the operator’s profile.

The applicable flag and the verdict are DERIVED from the three-axis taxpayer model through derive_modelo_applicability() — never from an autónomo default. An undeclared taxpayer model yields an INCOMPLETE verdict: the service reports “declare your taxpayer type first” instead of a confident wrong obligation.

The deadline engine’s explain text is still surfaced as scheduling_rationale when the modelo’s filing windows are registered for the year. When the modelo is a known registry modelo but no deadline windows are registered (registry-track gap R1), the scheduling rationale is left None; the applicability verdict is unaffected. A genuinely unknown modelo identifier still raises OverviewExplainError.

Parameters:
Return type:

OverviewExplain

Returns:

An OverviewExplain carrying the applicability verdict, optional scheduling rationale, and profile facts used by the verdict.

Raises:

OverviewExplainError – When the modelo identifier is blank or unknown to the registry, or when the deadline engine fails for a reason other than a missing deadline-window dataset.