Simulator Plan — Backend¶
Backend slice of #404 Simulator Module (PRD: #1555, task: #1556).
Context¶
The Simulator Plan lets a user project a research project's footprint over a
year range, reusing reference-year data and factors, without writing back to
the Calculator. Commit #1804 shipped an esquisse: plan CRUD
(api/v1/simulator_plan.py, services/simulator_plan_service.py,
repositories/carbon_project_repo.py), CarbonProject.start_year/end_year/
is_viewable_by_unit_members/created_by, and CarbonReport.reference_year.
That esquisse survives; this plan extends it.
Core principle¶
Plan data is ordinary Calculator data under a different project. A
plan-year is a CarbonReport with carbon_project_id → Simulator_Plan
project, year = simulated year, reference_year = chosen baseline.
Entries are ordinary data_entries; emissions flow through the existing
compute pipeline (data_entry_emission_service.py). Consequences:
- Zero new tables. "No write-back" is structural (separate report rows).
- Calculator-identical forms reuse the existing module/data-entry API.
- Full per-year emissions — including headcount — come from the existing
recalc + stats machinery (headcount already computes
fte × factor,modules/headcount/schemas.pyresolve_computations). - The
% of reference yearslider already exists:_get_percentage_override_kgindata_entry_emission_service.pyhonorsdata.percentage_of_reference_year(renamed frompercentage_of_last_year2026-07-16), matching the reference-year entry by stable identifiers.
Cardinality (per project type)¶
| Type | Projects per unit | Reports under project |
|---|---|---|
| Calculator | 1 | 1 per year (open years; in practice users work one year at a time) |
| Simulator_Explore | 1 | n per reference year — create_explore always creates a new one; resolution is "latest wins" (get_explore_by_unit_and_reference_year orders by last_updated, limit 1) |
| Simulator_Plan | n (unique by name) | exactly 1 per year in start_year..end_year |
Unlike Explore's latest-wins, plan-year reports must be individually
addressable — hence direct carbon_report_id addressing below.
Range shrink is destructive by design (confirmed with product 2026-07-15): out-of-range reports and their entries are deleted.
The plan's report set is derived from the project's year range: setting or
changing start_year/end_year syncs child reports (create missing years
with their modules via create_all_modules_for_report; delete out-of-range
years and their entries — the user shrank the range deliberately).
Design decisions¶
1. Factor year = reference year¶
Flip precedence to reference_year if set else year in
DataEntryEmissionService._get_year_from_data_entry and
modules/professional_travel/schemas.py::_get_report_year_for_module.
No behavior change for Calculator (reference_year is NULL) or Explore
(year == reference_year); mandatory for Plan (future years have no
factors). Reference-year dropdown = years open in the Calculator, from
existing year_configuration.
2. Split modules/<name>/schemas.py¶
Each Calculator module's schemas.py splits into (delivered — all 8
modules, no schemas.py remains):
data_entries.py— entry Create/Update/Response validation schemasfactors.py— factor handler schemas (BaseFactorHandlersubclasses)handlers.py—BaseModuleHandlersubclass (factor resolution + emission-compute config)emissions.py— emission-computation helpers (grew out of the split; not in the original three-file spec)
__init__.py re-exports; one mechanical pass over all 8 modules. This is
what lets the planner reuse the factor/emission side while owning its own
data-entry schemas.
3. app/modules_planner/ — only for genuinely new kinds¶
Planner modules that differ from the Calculator get a subpackage with their
own schemas + handler, registered in the same MODULE_HANDLERS registry
under new DataEntryTypeEnum values (80+ range). Their FactorQuery points
at existing Calculator factors — no new factor rows.
- Headcount (new kind,
planner_headcount = 80): manual aggregate FTE per SIUS-code category — noname/user_institutional_id, FTE unbounded (Calculator'sHeadCountCreatecaps FTE ≤ 1 per person). Reuses member/student factors viaFactorQuery(data_entry_type=member|student). - Travel: no new kind. Same plane/train handlers and factors; the
traveler dropdown sends a category token (
internal/external epfl/internal epfl) inuser_institutional_idinstead of a person — frontend concern, backend unchanged. - Purchases (delivered):
planner_purchase/planner_purchase_budgetinapp/modules_planner/purchase/— CHF per submodule XOR one global budget, enforced at creation; average EFs arrive as factor rows. - Type-2 modules (Process Emissions, Buildings, Equipments, Research
Facilities, External Clouds & AI): no new kinds — Calculator entries +
snapshot prefill +
percentage_of_reference_year.
4. API surface¶
Extends the esquisse in api/v1/simulator_plan.py:
PATCH /simulator-plan/{plan_id}growsstart_year,end_year,is_viewable_by_unit_members(today: rename only). The service syncs child reports to the range (see Cardinality).PATCH /simulator-plan/{plan_id}/years/{year}{reference_year}— sets the baseline for one plan-year report. Changing it re-snapshots type-2 modules (wipe module entries, re-copy) — slice 2.GET /simulator-plan/{plan_id}/years— list plan-year reports (id, year, reference_year, stats) for the results chart.- Identity addressing — lookup once, then identity.
(unit_id, year, carbon_project_type)is a query, not an identity — ambiguous once a unit has several plans. The identity-route family already exists inapi/v1/carbon_report.py(GET /carbon-reports/{id},GET /carbon-reports/{id}/modules/,PATCH /carbon-reports/{id}/modules/{module_type_id}/status) and the frontend already trackscurrentCarbonReportId(stores/modules.ts). Extend that family verbatim with the module/data-entry operations currently under/{unit_id}/{year}/{module_id}/...(~15 routes incarbon_report_module.py):
/carbon-reports/{carbon_report_id}/modules/{module_type_id}/{submodule_id}/{item_id}
carbon_report_id alone pins unit (authz), year, and project — no
redundant parent segments (a /project/{id}/report/{id}/... chain would
need per-request consistency checks or silently ignore segments).
module_type_id over carbon_report_module_id: unique within a report,
and the frontend already thinks in module-type constants.
The unit/year natural key survives as exactly one lookup (get/create
report for unit/year/type → report + modules) used when the Calculator
workspace selects unit+year; all subsequent operations use report-id
routes. Legacy unit/year module routes are then deleted (no dual path).
Genuinely unit/year-scoped aggregates (modules-stats/.../totals,
results-summary) are workspace queries, not resource addressing — they
keep their shape.
- Frontend:
utils/modulePath.ts::buildModulePathis the single source of truth for legacy module paths (plus ~4 stragglers instores/modules.ts/api/modules.ts) — its signature switches from(moduleType, unit, year)to(moduleType, carbonReportId);carbon_project_typequery juggling disappears. Planner stores (stores/simulatorPlans.ts) key state bycarbon_project_id(plan) andcarbon_report_idper year (fromGET .../years). Browser URLs are unchanged:.../project-planner/:name(plan name is the URL identifier; all year sections on one page). - Rollout, all under #1556 (decided 2026-07-15; delivered 2026-07-16
as a single-branch rewrite rather than three sequenced PRs): the ~11
module routes were rewritten in place to the identity paths (no
transitional delegation), the frontend swapped in the same branch, and
the
carbon_project_typeparam removed — no dual-path window ever existed. The modules router now mounts under/carbon-reports. - Module Active checkbox: new nullable
is_activebool oncarbon_report_modules(migration viamake db-revision), default true. Inactive modules are excluded from reportstatsaggregation. - Snapshot prefill (slice 2):
POST /carbon-reports/{carbon_report_id}/modules/{module_type}/prefillcopies reference-year Calculator entries into the plan module withpercentage_of_reference_year = 100. Note: the slider override computes against the live reference entry when it still exists (existing_get_percentage_override_kgmatching); if the source disappears, the snapshot data at its stored quantities is the fallback.
5. Permissions¶
Decided with product (2026-07-15): plans stay unit-scoped (esquisse's
require_unit_access; unit-less users out of scope). A plan is visible to
non-creator unit members only when is_viewable_by_unit_members is true,
and shared plans were read-only for non-creators — only the creator (or
backoffice) mutated. Superseded: #1922 made shared plans editable by unit
members (deletion stays creator-only), and #2043 moved the rule into
PlanPolicy — see 2043.
Slices¶
Slice 1 — Travel + Headcount end-to-end (delivered 2026-07-16)¶
- Split
modules/<name>/schemas.py→data_entries.py/factors.py/handlers.py/emissions.py(all 8 modules, mechanical). - Factor-year flip (
reference_year or year) in the two resolution helpers. - Plan year-range lifecycle: PATCH plan (start/end year, visibility) +
report sync in
simulator_plan_service.py; reference-year PATCH per plan-year report; GET years. - Identity routes: extend
/carbon-reports/{id}/modules/{module_type}with the entry CRUD/stats operations (legacy unit/year routes delegate to the shared impl). - Frontend: planner stores keyed by project/report ids (incl.
constant/planner-module-configdefining each module's planner behavior in Calculator order);buildModulePathswapped to(moduleType, carbonReportId)for Calculator/Explore; then delete legacy unit/year module routes +carbon_project_typeparam (rollout steps 2–3). -
carbon_report_modules.is_activemigration + PATCH + stats exclusion. - Permissions: hide unshared plans from non-creators in list/get; reject
writes (plan, plan-year reports, their entries) from non-creators —
including data-entry writes arriving via the module routes when the
target report belongs to a
Simulator_Planproject. -
modules_planner/headcount/: schemas + handler (planner_headcount = 80), reusing member/student factors. - Travel: verify plane/train entry CRUD + emissions work against a
plan-year report (category token in
user_institutional_id); no code expected beyond the disambiguation param. - Tests: plan lifecycle sync, disambiguation, reference-year factor lookup, planner-headcount emissions, is_active exclusion.
Slice 2 — Snapshot prefill (delivered 2026-07-16, generic for all type-2 modules)¶
- Snapshot-prefill endpoint + service:
POST /carbon-reports/{id}/modules/{module}/prefillcopies the reference-year Calculator entries atpercentage_of_reference_year = 100withsource = PLANNER_SNAPSHOTandsource_data_entry_id(the slider matches its exact source row; deleted sources fall back to the snapshot data). Generic — works for every type-2 module, no per-module code. - Re-snapshot on reference-year change (wipe snapshot rows + re-copy from the new baseline; user-added rows survive).
- Slider override verified:
source_data_entry_idmatching unit tests + SQLite prefill/re-snapshot lifecycle tests. - Snapshot rows expose
reference_kg_co2eq(the source entry's summed emissions) on the planner submodule items, and the data-entry response surfacespercentage_of_reference_year— the shared table's reference column + slider read both (2026-07-16).
Slice 3 — Remaining modules + results¶
- Buildings, Equipments, Research Facilities, External Clouds & AI
(type-2): delivered 2026-07-16 — all five type-2 modules are
behavior: 'prefilled'inconstant/planner-module-config; the shared table renders the reference-kg column + 0–200% slider in planner context, and setting a section's reference year auto-prefills every prefilled module. - Purchases planner kinds (delivered 2026-07-16):
planner_purchase = 81(CHF total per submodule, emission type resolved per category) andplanner_purchase_budget = 82(one global budget →purchases__goods_and_services). XOR + duplicate rules enforced at entry creation (422 codes). Emissions computeamount_chf × ef_kg_co2eq_per_chffrom factors keyed on the planner kinds — the average-EF methodology ships as factor data (CSV upload), not code; entries carry no kg_co2eq until those factors exist. - Results aggregation across active modules/years for the chart; exports (PDF/CSV) per #404 scope decision.
Verification¶
uv run pytest backend/tests/unit/services/test_simulator_plan_service.pyplus new tests above (user runs the suite)./verifyskill: create a plan, set years 2027–2029 with reference year 2024, add planner-headcount FTE rows and a travel entry, confirm non-zero per-year emissions in the plan-year report stats and zero writes to the Calculator reports.