aeat.application.filing._calculate module

Typed summary surface for filing draft calculation results.

This module does not run the registry formula graph. It summarises an already-built domain.filing.ModeloDraft into a frozen DeclaracionCalculateSummary so CLI renderers can display the draft status, finding counts, repair hints, and DeclaracionCalculateNextAction without re-implementing lifecycle policy.

The CLI contract requires modelo calculation to print a compact summary table, blocker counts, warnings, and the next action. When inputs are unresolved, repair hints must be present instead of allowing a silent success. The CLI cannot compute that summary by inspecting a draft ad hoc: the next-action heuristic is shared logic the application layer owns, and this typed record gives renderers and tests a stable schema.

The summarise_calculation() helper turns a draft into the typed summary consumed by renderers:

draft = build_draft(...)
summary = summarise_calculation(draft)
render(summary)

See also

application.filing.build_draft()

Registry-backed draft construction that produces the domain.filing.ModeloDraft summarised here.

domain.submission.ModeloDraftStatus

Lifecycle states that drive the next-action mapping.

application.modelo.calculation_result_summary()

Separate persisted-revision summary for headline casillas chosen from registry verification expectations.

class DeclaracionCalculateNextAction(*values)[source]

Bases: StrEnum

Closed catalogue of next operator actions surfaced after calculate.

The CLI uses this to render the “next action” line of the bare modelo calculation summary.

Variables:

  • RESOLVE_BLOCKERS – One or more validation findings at BaseSeverity.ERROR block forward motion. The operator must edit inputs or fix the upstream catalogue before any review/approve/export step.

  • REVIEW – The draft validated cleanly (or only carries informational findings) and is ready for human review via modelo review.

  • APPROVE – The draft has been reviewed and is awaiting human approval through the modelo workflow.

  • EXPORT – The draft is approved and may be exported via modelo export.

  • REFRESH_APPROVAL – The draft was previously approved but the approval is stale; the operator must re-approve.

  • AMEND – The draft is in a downstream lifecycle state (submitted / acknowledged / rejected / amended / cancelled); corrective work runs through a fresh recalculation rather than the calculate flow.

RESOLVE_BLOCKERS
REVIEW
APPROVE
EXPORT
REFRESH_APPROVAL
AMEND
class DeclaracionCalculateSummary(**data)[source]

Bases: BaseModel

Typed summary of a single modelo calculation run.

Variables:

  • draft_id – The domain.filing.ModeloDraft identity the summary was produced from.

  • modelo – AEAT modelo identifier.

  • period – Typed filing period for the draft.

  • status – The draft’s ModeloDraftStatus after validation.

  • blocker_count – Number of findings at BaseSeverity.ERROR. Always >= 0.

  • warning_count – Number of findings at BaseSeverity.WARNING. Always >= 0.

  • info_count – Number of findings at BaseSeverity.INFO. Always >= 0.

  • next_action – Closed DeclaracionCalculateNextAction. Derived deterministically from status and the finding mix.

  • repair_hints – Translation keys surfaced when next_action is DeclaracionCalculateNextAction.RESOLVE_BLOCKERS; empty otherwise. The CLI renders them under the summary line so the operator never sees a silent ERROR.

  • narrative – Translation key for summary line.

  • calculated_at – UTC timestamp of when the summary was produced.

Parameters:
draft_id: str
modelo: str
period: Period
status: ModeloDraftStatus
blocker_count: int
warning_count: int
info_count: int
next_action: DeclaracionCalculateNextAction
repair_hints: tuple[str, ...]
narrative: str
calculated_at: datetime
summarise_calculation(draft, *, repair_hints=(), narrative=None, calculated_at=None)[source]

Build a DeclaracionCalculateSummary from a validated draft.

Parameters:

  • draft (ModeloDraft) – The ModeloDraft returned by application.filing.build_draft().

  • repair_hints (tuple[str, ...]) – Translation keys for remediation hints. Required when the draft carries any ERROR finding (the CLI must not surface a silent blocker); rejected otherwise. Passing the existing draft findings unchanged is acceptable; callers that derive richer hints from upstream catalogues can provide their own.

  • narrative (str | None) – Optional override for the translation key summary line. When None, a default narrative key is used.

  • calculated_at (datetime | None) – Optional UTC timestamp. Defaults to the draft’s updated_at.

Return type:

DeclaracionCalculateSummary

Returns:

A frozen DeclaracionCalculateSummary.