aeat.application.overview._pipeline_health module

Pipeline health: cross-domain readiness summary for one filing period.

build_pipeline_health_report() is the application service backing aeat app overview pipeline --year YEAR --period PERIOD. It answers the operator-observable question “is my pipeline healthy for this period?” by composing three already-existing read models for the requested (filing_year, period) scope into one typed report:

The builder is READ-ONLY: it inspects the transaction catalogue, the modelo work-unit catalogue, the calculation-revision catalogue, and the verification-report catalogue for the requested scope. It persists nothing and never contacts AEAT. Every counter it reports is already produced by an existing read model or a direct repository read; this module composes them into one cross-domain dashboard rather than introducing a new aggregation (the composition-service-no-parallel-write-path discipline).

See also

overview

Sibling read-only overview builders (status, prepare, calendar, agenda, backlog, explain) this module follows the same shape as.

summarize_manual_transactions()

Owns the ledger status counters this report’s ledger section reuses rather than re-deriving.

WorkUnit

The modelo work-unit record the readiness rows resolve against.

VerificationReport

The findings source each readiness row’s outstanding-findings list is drawn from.

class ModeloReadinessState(*values)[source]

Bases: StrEnum

Closed lifecycle state for one modelo’s readiness within a period.

Variables:

  • NOT_STARTED – No WorkUnit exists yet for this (modelo, filing_year, period).

  • CALCULATED – A work unit exists and its current revision has computed casilla values but has not been verified.

  • VERIFIED – The current revision reached VERIFICADO_COMPLETO.

  • FILED – The work unit’s filed revision matches its current revision (PRESENTADO or superseded by a later filed revision of the same unit).

  • BLOCKED – The latest verification report against the current revision carries at least one BLOCKING finding.

NOT_STARTED
CALCULATED
VERIFIED
FILED
BLOCKED
class ModeloHealthRow(**data)[source]

Bases: BaseModel

One modelo’s readiness row within a period health report.

Variables:

  • modelo – AEAT modelo code (e.g. "130", "303").

  • work_unit_id – The matching WorkUnit id, or None when state is NOT_STARTED.

  • state – Current ModeloReadinessState for this modelo/period.

  • blocking_finding_count – Count of BLOCKING severity findings from the latest verification report against the current revision.

  • warning_finding_count – Count of WARNING severity (advisory) findings from the same report.

  • summary – Human-readable one-line progress summary.

  • next_command – The exact next aeat command to run to advance this modelo, or resolve its current gap.

Parameters:
modelo: str
work_unit_id: str | None
state: ModeloReadinessState
blocking_finding_count: int
warning_finding_count: int
summary: str
next_command: str
class PipelineHealthReport(**data)[source]

Bases: BaseModel

Outcome of build_pipeline_health_report().

Variables:

  • bucket_id – Active profile bucket the report is scoped to.

  • filing_year – Filing year for the requested scope.

  • period – Registry period token for the requested scope (e.g. 1T).

  • ledger – The reused LedgerStatusReport for the same (bucket_id, period) scope.

  • modelos – Ordered ModeloHealthRow rows, one per work unit found for the period, sorted by modelo code. Empty when no work unit has been created for this period yet.

  • total_blocking_findings – Sum of every row’s blocking_finding_count.

  • total_warning_findings – Sum of every row’s warning_finding_count.

  • ready – True only when the ledger reports no unresolved readiness issues (or was not scoped) and every modelo row is FILED or VERIFIED, with zero modelos in BLOCKED. False when any modelo has not started or is blocked, or the ledger still carries pending-review rows or readiness issues. A pipeline with zero work units for the period is never reported ready — there is nothing to be ready about yet.

Parameters:
bucket_id: str
filing_year: int
period: str
ledger: LedgerStatusReport
modelos: tuple[ModeloHealthRow, ...]
total_blocking_findings: int
total_warning_findings: int
ready: bool
build_pipeline_health_report(*, bucket_id, filing_year, period, ledger_report, work_units, revisions_by_id, reports_by_revision_id)[source]

Compose the cross-domain pipeline health report for one period.

Parameters:

  • bucket_id (str) – Active profile bucket the report is scoped to.

  • filing_year (int) – Filing year for the requested scope.

  • period (Period) – Typed filing Period for the requested scope.

  • ledger_report (LedgerStatusReport) – Already-built LedgerStatusReport for (bucket_id, period) (period-scoped, so ready and readiness_issue_count are populated).

  • work_units (tuple[WorkUnit, ...]) – Non-discarded WorkUnit rows for bucket_id matching (filing_year, period). Callers filter to the requested scope; this builder does not re-filter.

  • revisions_by_id (dict[str, CalculationRevision]) – Mapping of calculation_revision_id to the loaded CalculationRevision, covering every work unit’s current_calculation_revision_id. A work unit whose id is absent from this mapping is treated as having no revision yet.

  • reports_by_revision_id (dict[str, tuple[VerificationReport, ...]]) – Mapping of calculation_revision_id to its VerificationReport rows, sorted oldest-first (the shape list_verification_reports() returns). The latest (last) report is used.

Return type:

PipelineHealthReport

Returns:

A PipelineHealthReport with one ModeloHealthRow per work unit, findings totals, and an overall ready verdict.