2706 — One path for a module's stats¶
Problem¶
GET /carbon-reports/{id}/modules/{module} ran two aggregates per request:
DataEntryEmissionRepository.get_stats (flat {emission_type_id: kg}) and,
for headcount, get_headcount_fte_breakdown. The pipeline meanwhile
persisted a richer, bucketed stats JSON on carbon_report_modules.stats
through compute_module_stats. Two formulas for one published number, two
shapes, and a per-GET aggregate on the hottest page.
What the frontend actually rendered from the live path: only
totals.total_kg_co2eq / total_tonnes_co2eq (module sidebar) and, for
headcount, the FTE-by-SIUS map feeding the bar chart. The flat emissions map
was dead payload for every other module.
Decision (maintainer, 2026-09-11)¶
Option A of the issue: the GET reads the persisted column. KISS — one path, one location. The persisted JSON gains what the read path needed:
| key | module | what |
|---|---|---|
total_excluding_additional |
all | headline: every bucket except the additional ones (commuting, food, waste, embodied energy) — what the sidebar shows |
planner_snapshot_kg |
all | share of that headline carried by Simulator prefill rows (source = PLANNER_SNAPSHOT); subtracted for viewers who may not see those rows (#1983) |
student_fte, member_fte_by_sius_code |
headcount | the bar-chart maps, from the existing get_headcount_fte_breakdown query, now run at recompute time |
get_stats_pair_many (the batched query behind recompute_stats_many)
gains one SUM(CASE WHEN source = 6 …) column. It keeps its
data_entries join because source lives there — the #2527 Phase 2 join
drop for this query is therefore off the table unless source is
denormalized onto emissions too.
Shipped¶
carbon_report_module.py—_module_totalsreads the keys above;statsinModuleResponseis the persisted JSON verbatim. A row written before this change lacks the keys and answers 503 pointing at the admin recompute-stats trigger. No silent zero.- Deleted:
DataEntryEmissionRepository.get_stats,get_stats_pair,DataEntryEmissionService.get_stats,DataEntryService.get_headcount_fte_breakdown(the repo query stays, the module service calls it). - Frontend:
ModuleResponse.statsisRecord<string, unknown> | null;headcountChartStatsbuilds the chart map from the persisted keys. - Emptied modules join the aggregation scope.
bulk_delete_by_source_year(CSV / Tableau full-year re-import) deletes a module's rows; no entry is left to put it in any recalc'saffected_module_ids, so its stats kept the old kg. The simulator already refreshed the modules its prefill left empty; the bulk path now does the same:aggregation_handlerunionsCarbonReportModuleService.emptied_module_ids(persistedentry_count0, zero entries left) into the scoped set. One grouped count over the slice; the full-slice fallback already covered it.
- Tests: repo (
get_stats_pair_manysnapshot split, rollup no-double-count, banner total), purecompute_module_statskeys, route (headline, hidden viewer, no stats, 503), Playwright unit spec for the chart adapter, and the_pgshape contract updated; handler + service tests for the emptied scope.
Deploy step¶
Every environment must run POST /sync/admin/recompute-stats right after
this deploys (backoffice pipeline operations). Until then non-headcount
module pages answer 503 by design.
Found on the way, not fixed here¶
- Stage drift: 4039 of 18096 modules on stage differ between the
persisted
by_emission_typeand a live sum — the first query also counted computed parent rollups, so the leaf-only figure is still to be read. breakdownTotal.tsstill re-sums non-additional buckets client-side for the results page;total_excluding_additionalcan retire it.