cadrumo.application.modelo.work_plazo module

Application summaries for modelo work-unit filing deadlines.

This module turns a WorkUnit into the deadline summary used by the calculate CLI payload. It asks the registry deadline-window surface for the voluntary filing close date, derives either days_remaining or days_overdue against a reference date, and attaches the Ley 58/2003 art. 27 recargo band when the filing is late and the band table resolves.

An unknown registry deadline is deliberately represented as None rather than a blocking error. A recargo lookup failure still returns the overdue posture, logs the validation problem, and lets the rendering layer emit the generic extemporaneous-filing warning.

See also

cadrumo.domain.deadlines.plazo.resolve_filing_closes_on():

Registry-backed lookup for the plazo voluntario close date.

cadrumo.domain.deadlines.recargo.build_recovery_for_overdue():

Resolves the Art. 27 LGT recargo band for overdue filing.

cadrumo.entrypoints.cli._modelo_rendering.work_unit_deadline_output():

Projects this summary onto JSON payloads and warning notices.

class M210PlazoResolution(closes_on, context)[source]

Bases: object

The resolved Modelo 210 filing window, carried as facts.

Deliberately NOT a Notice. A notice carries localized operator-facing prose, and rendering it here would put presentation inside the application layer; the frontends build the notice from these facts instead, so the same resolution can be spoken in any surface’s own voice.

Variables:

  • closes_on – ISO date the voluntary filing window closes.

  • context – Deterministic diagnostic metadata, already in the shape a notice context takes – window identity, legal and source refs.

Parameters:
closes_on: str
context: Mapping[str, str]
class ModeloWorkConditionalRecargoPreview(band_id, surcharge_pct, interest_applies, legal_ref, rate_reference_on, assessment_status='unassessed')[source]

Bases: object

Unassessed Article 27 rate preview for an overdue work unit.

This is a governed calendar-rate preview, not an Article 27 statutory assessment. It preserves the deadline engine’s band id, percentage, interest applicability, and legal reference so an operator can see the consequence that may apply at rate_reference_on. It does not carry an amount, eligibility decision, interest amount, or proof of the Article 27 predicates.

rate_reference_on is the explicit as-of date used for deadline posture and the conditional preview. It is never represented as an actual filing presentation date. assessment_status is intentionally a one-value contract: this calculate surface cannot assess Article 27 liability until a complete provenance-bearing assessment boundary exists.

Parameters:

  • band_id (str)

  • surcharge_pct (Decimal)

  • interest_applies (bool)

  • legal_ref (str)

  • rate_reference_on (date)

  • assessment_status (Literal['unassessed'])

band_id: str
surcharge_pct: Decimal
interest_applies: bool
legal_ref: str
rate_reference_on: date
assessment_status: Literal['unassessed']
class ModeloWorkDeadlinePosture(closes_on, days_remaining=None, days_overdue=None, conditional_recargo_preview=None)[source]

Bases: object

Voluntary-filing deadline posture for a modelo work unit.

closes_on is the voluntary filing close date. Exactly one posture is populated by modelo_work_deadline_posture(): days_remaining for an in-time reference date, or days_overdue for an overdue reference date. conditional_recargo_preview is optional rate guidance only; it never represents a determined surcharge or interest liability.

Parameters:
closes_on: date
days_remaining: int | None
days_overdue: int | None
conditional_recargo_preview: ModeloWorkConditionalRecargoPreview | None
validate_modelo_work_deadline_posture(*, closes_on, days_remaining, days_overdue)[source]

Enforce the canonical one-sided voluntary-deadline state contract.

Return type:

None

Parameters:

  • closes_on (date)

  • days_remaining (int | None)

  • days_overdue (int | None)

modelo_work_deadline_posture(work_unit, *, reference_on=None)[source]

Return voluntary-deadline posture and rate-only preview, if known.

The work unit supplies the modelo, filing year, and typed period used to match a registry deadline window. When no window matches, the function returns None so callers can omit the deadline block. When the filing is still inside the voluntary window, the posture carries days_remaining. When the close date has passed, it carries days_overdue and, when the deadline engine resolves a band, a ModeloWorkConditionalRecargoPreview.

This function deliberately has no statutory-assessment inputs. An Article 27 determination needs provenance-bearing filing, amount, prior-requirement, identity, legal-regime, and additional statutory facts that the calculate path does not possess. The returned preview is therefore always unassessed. The reference date drives an observable deadline posture and a conditional rate preview only; it is never an actual presentation date.

Parameters:

  • work_unit (WorkUnit) – The WorkUnit whose modelo, filing year, and Period select a registry filing window.

  • reference_on (date | None) – Optional date from which the caller observes the voluntary deadline. Defaults to the current Europe/Madrid civil date (cadrumo.core.time.clock.today_madrid()) — the AEAT filing plazo is a Spanish-calendar boundary — which derives from the clock seam so a frozen_clock() scope pins it. It drives the deadline posture and conditional preview rate; it is not a presentation date.

Return type:

ModeloWorkDeadlinePosture | None

Returns:

A ModeloWorkDeadlinePosture, or None when the registry has no deadline window for the work unit’s filing axis.

See also

cadrumo.entrypoints.cli._modelo_rendering._work_unit_deadline_output_from_posture():

Converts the summary into operator-facing payloads and notices.

calculated_m210_plazo_resolution(*, work_unit, revision, workflow_profile)[source]

Return the grounded post-calculation Modelo 210 plazo facts, if known.

Modelo 210 annual filing windows depend on the calculated declaration result and the operator’s persisted official two-digit tipo-renta code. Those facts do not exist at work-unit creation time, so this projection is deliberately separate from modelo_work_deadline_posture(), which remains the unqualified pre-calculation extemporaneidad surface.

The function derives the result through the same application resolver used by filing/export and delegates window matching to the canonical deadline resolver. It owns no result vocabulary, tipo-renta map, date catalogue, or matching rule. A missing window produces no notice; notably, tipo 28 stays silent until its event-relative offset has authoritative registry backing.

Core types: CalculationRevision, TaxpayerProfile.

Return type:

M210PlazoResolution | None

Parameters: