Project Planner: default reference year + no locked modules¶
Part of the planner feedback batch (#1556, #1557). Previously a plan year was locked until a reference year was set: every module drawer was disabled, and factor lookups fell back to the plan year itself (usually a future year with no factors, so entries computed no emissions).
Decision (with the lead, 2026-08-04)¶
- Default the reference year itself. When the year range is set and new
plan-year reports are created, each gets
reference_year= the workspace year the planner page is under (the Assessment Year selector), and the normal prefill runs from it — exactly as if the user had picked it in the dialog. Changing it later keeps today's destructive rebuild. - No migration. Three designs were discarded: persisting a
factor_yearcolumn oncarbon_projects(workspace year frozen at plan creation), deriving the default from the latest opened year configuration, and anassessment_yearcolumn scoping the plan list per workspace year (implemented then rolled back at the lead's request). - The reference year is removable. The dialog offers a "No reference
year (manual data entry)" option; removal empties the prefilled modules
exactly like a change does (
SimulatorPlanReferenceYearUpdate.reference_yearis nullable,_prefill_reference_moduleswipes before the None early-return), and any change now requires the acknowledgment checkbox, since manual rows can exist before a first set. - Modules are never locked. All planner modules (not just the four the
spec names) accept manual input even when a year's reference is unset
(legacy plans, duplicated plans —
duplicate_plancopies the range but not the reference years). For those, factor lookups fall back to the year of the unit's most recent Calculator report, derived by joiningcarbon_projects(type Calculator) withcarbon_reports; stored emissions of such entries keep their old factors until an entry is edited (same staleness rule as factor re-uploads).
Backend¶
SimulatorPlanUpdate.default_reference_year— sent by the frontend with the range PATCH;_sync_year_reportsapplies it (create report withreference_year, run_prefill_reference_modules, refresh the report rollup) only to reports the sync creates — existing reports keep their reference year.app/utils/factor_year.py—resolve_factor_year(session, report), the single factor-year chain:reference_year→ (Simulator Plan reports only) unit's latest Calculator report year →report.year. Backed byCarbonProjectRepository.get_latest_calculator_year(unit_id).- Routed through the helper (was three hand-rolled copies of "reference_year wins"):
DataEntryEmissionService._get_year_from_data_entry- the inline fallback in
DataEntryEmissionService.prepare_create _get_report_year_for_moduleinapp/modules/professional_travel/handlers.pySimulatorPlanRead.default_factor_year(derived, read-only) exposes the unset-reference fallback so the frontend's dropdowns use the same year the backend computes with.
Frontend¶
PlannerProjectInfo.vuesendsdefault_reference_year: Number(route.params.year)with the range PATCH; the store gives that PATCH the same 5-minute timeout assetReferenceYear(it now prefills).PlannerYearSection.vue: the!hasReferenceYeardrawer gate is removed;factorYearmirrors the backend chain (reference_year ?? plan.default_factor_year ?? yearData.year) and feedsModuleTableSection's:factor-yearand thefactorMountKeyremount keys; the "% of reference year" columns only render when a reference year exists.planner_reference_year_hint(en/fr) presents the reference year as optional and names the fallback factor year. The print composable's taxonomy year follows the same chain.
Tests¶
backend/tests/unit/utils/test_factor_year.py— the resolution chain (reference year wins; plan without reference → latest Calculator year; no Calculator report → own year; Calculator report → own year).test_simulator_plan_service.py— range sync defaults the reference year on newly created reports only; withoutdefault_reference_yearthe reference stays unset; removal wipes the prefilled modules.