Equipment: carry forward prior-year usage with factor/default fallback¶
Branch fix/259-equipment-identify-data-entry-different-from-previous-years,
round 3 of issue #259.
Context¶
Round 1 (merged to dev, 0706df6fb) covered the "identify" half of the
issue: equipment whose equipment_id is absent from the unit's most recent
prior year is flagged new, sorted first, and counted in the module banner
(get_prior_year_equipment_ids, the new-and-incomplete primary sort,
count_incomplete_new_equipment).
The updated issue spec added the data-entry half: usage hours the unit already confirmed in a previous campaign should not have to be re-typed every year, and equipment with no usage information anywhere should still compute an emission from sensible defaults instead of computing nothing.
Round 2 (kept on backup/259-carry-forward-v1, 63bd7847f) resolved the
carry-forward at read time and surfaced provenance through derived response
flags and widened response types. It was dropped: no new response fields, no
type widening — the design must stay schema-free.
Decision¶
Per-field resolution chain for active_usage_hours_per_week and
standby_usage_hours_per_week, applied independently to each field:
- Value ingested this year — normally absent (the feed does not carry usage), but if present it is still overridden by rule 2, since a value the user confirmed in a prior campaign is more trustworthy than a feed artifact.
- Value set in the unit's most recent prior year for the same
equipment_id— copied intoentry.dataat bulk ingest. - Factor suggestion — an unset field keeps tracking the factor's
current
active/standby_usage_hours_per_weeklive in the emission formula (nothing seeded intoentry.data, so a factor re-upload takes effect on recompute). - Spec defaults — when the factor has none either, the formula falls
back to
DEFAULT_ACTIVE_USAGE_HOURS_PER_WEEK = 12/DEFAULT_STANDBY_USAGE_HOURS_PER_WEEK = 156(12 + 156 = a full 168 h week). The formula no longer returnsNonefor missing hours.
Consequences of the chain:
- No response-schema or frontend change. A carried-forward value is an
ordinary
entry.datavalue; an unconfirmed cell still surfaces through the existing empty-cell UX and the round-1 incomplete count. This is what keeps round 3 schema-free where round 2 was not. - "Prior year" is the greatest year strictly before the current one that
has equipment entries for the unit — robust to skipped campaign years,
same definition round 1 used for the new flag (shared
_prior_equipment_yearhelper). - Carry-forward happens once, at write time. Editing the value later behaves like any other edit; prior years are never re-read after ingest.
Backend¶
app/modules/equipment/data_entries.py— the two spec-default constants.app/modules/equipment/handlers.py—_equipment_formulagains the default fallback per field; thereturn Noneon missing hours is gone.app/repositories/data_entry_repo.py_prior_equipment_year(unit_id, current_year)— factored out ofget_prior_year_equipment_ids(round 1) so both lookups share the prior-year definition.get_prior_year_equipment_usage(unit_id, current_year)— mapsequipment_id→ the usage fields actually set in the prior year. Single query per (unit, year); onlyequipment_idand the two usage fields travel over the wire, so a 50k-row prior year stays cheap. Unset fields are omitted from each dict, so the caller can merge without inventing values the prior year never had.app/services/data_entry_service.py—apply_equipment_carry_forward(data_entries), called from the bulk-copy ingest path afterfill_denormalized_scope. Filters to equipment entries with anequipment_id, resolves each entry's (unit, year) scope, and merges the prior-year map overentry.data. Prior-year maps are cached per(unit_id, year)on the service instance: one lookup query per unit/year in a batch, never one per entry.
Tests¶
tests/integration/.../test_new_vs_previous_year.pytest_prior_year_usage_map_partial_fields— the lookup returns only the fields each prior row set; the prior year itself gets an empty map.test_apply_equipment_carry_forward— per-field merge: prior-year values win over ingested ones, unset prior fields stay as ingested, unmatched equipment is untouched; entries arrive unstamped like the real ingest batch (denormalized scope filled by the service).test_new_equipment_flagged_and_sorted_firstrepaired: the primary sort floats new-and-incomplete rows, so the new row is now seeded without usage — the complete row it previously seeded could never float and the assertion had been failing since the round-1 commit.tests/unit/modules/test_equipment_schemas.py—test_equipment_formula_spec_defaults_when_no_hours_anywherereplaces the old none-when-no-hours test: with no hours on the entry nor the factor the 12/156 defaults apply, each field independently (5 h active on the entry still combines with the 156 h standby default).
Delivery¶
- Branch
fix/259-equipment-identify-data-entry-different-from-previous-years, commit1ddaf8a3eon top of round 1; round 2 preserved onbackup/259-carry-forward-v1.