cadrumo.application.modelo.local_observation_actions module

Operator-supplied local filed observations for calculation prefill.

This module records local, non-official observations in the pending-local layer of the cross-period calculation observation store, and clears them again. Each recorded figure is an audited override: it names the actor, the reason and what it replaced, and the official layer it may sit above is never destroyed. It deliberately does not create a ModeloRecord and does not stamp ExternalEvidence: the values are operator-supplied scratch/local inputs that can feed relation and previous_filing calculation prefill, but they must never satisfy the filing-grade clean-state proof that requires AEAT-backed evidence.

Each persisted observation is grounded against the law-determined ModeloRevision – resolved structurally via select_revision, never a filing-grade snapshot, since recording a non-official local observation is not itself a filing act – and stored as provenance-bearing CasillaObservation rows, while the source kind stays explicitly non-official.

See also

persist_filed_revision_observation():

Local-filing projection that uses app_filing rather than operator-manual source.

cross_period_clean_state:

Classifies local observations as non-official for filing-grade readiness.

OPERATOR_MANUAL_OBSERVATION_SOURCE_KIND: Final

Non-official source kind for operator-supplied local observations.

class LocalObservationPorts(bucket_id, observation_repository, bucket_event_repository, work_unit_repository)[source]

Bases: object

Persistence authorities one operator observation override reads and co-commits.

Parameters:
bucket_id: str
observation_repository: CalculationObservationRepositoryProtocol
bucket_event_repository: BucketEventHistoryRepositoryProtocol
work_unit_repository: WorkUnitCatalogueRepositoryProtocol
LOCAL_OBSERVATION_ACTION_CARRIES_DETAIL: Mapping[str, bool]

Whether each local-observation outcome carries the observation’s own detail.

Recording an override states a revision, a source kind and the values it overrides; clearing one states none of them, because the layer it removed is what held them. The two results below are the typed halves of that split, and this mapping is what a projection of either consults rather than restating it.

class ModeloLocalObservationResult(**data)[source]

Bases: BaseModel

Result of recording one operator-supplied local observation.

Parameters:

data (Any)

modelo: str
filing_year: int
period: Period
member_nif: str | None
revision_id: RevisionId
observation_key: str
source_kind: ObservationSourceKind
casilla_values: dict[CasillaId, Decimal]
captured_at: datetime
captured_by: str
override: ObservationOverride
official_evidence: bool
filing_record_created: bool
aeat_accepted: bool
class ModeloLocalObservationClearResult(**data)[source]

Bases: BaseModel

Result of clearing one operator override from the pending-local layer.

Parameters:

data (Any)

modelo: str
filing_year: int
period: Period
member_nif: str | None
observation_key: str
cleared_override: ObservationOverride
cleared_at: datetime
cleared_by: str
reason: str
effective_source_kind: ObservationSourceKind | None
record_operator_local_observation(*, modelo, filing_year, period, casilla_values, reason, actor, ports, operation, member_nif=None, clock=None)[source]

Persist an audited operator figure in the pending-local layer of one coordinate.

The observation is grounded against the law-determined ModeloRevision for modelo / filing_year / period. Every supplied casilla id must be a canonical numeric casilla declared by that revision; printed-number aliases and unknown ids are refused before the observation store is touched.

The persisted envelope uses source_kind="operator_manual" and carries the revision id as its stamp plus an ObservationOverride naming the actor, the reason, and the envelope that was effective before. An official layer stays stored underneath. Calculation prefill then resolves the operator values, while cross-period clean-state verification still treats them as non-official local evidence. The envelope and a modelo.observation.overridden event commit together.

Return type:

ModeloLocalObservationResult

Returns:

A ModeloLocalObservationResult describing the persisted local observation stamp.

Parameters:
clear_operator_local_observation(modelo, filing_year, period, *, member_nif=None, reason, actor, ports, clock=None)[source]

Remove the operator override from the pending-local layer of one coordinate.

The official layer, when stored, becomes effective again. The removal and a modelo.observation.override_cleared event commit together.

Raises:

ModeloLocalObservationError – The coordinate holds no operator override in its pending-local layer, or the actor or reason is blank.

Return type:

ModeloLocalObservationClearResult

Parameters: