ARCHIVED: This plan was not delivered. Preserved for context.
Implementation Plan: Reporting Aggregated Treemap Chart (#460)¶
Objective¶
Add an Emission Breakdown treemap chart to the backoffice reporting page, visualising aggregated emission data across the currently filtered unit set, with module-level tabs for drill-down (e.g. Professional Travel, Equipment, …).
The chart must react to the same filter state as the units table, using the
emission_breakdown already returned by GET /backoffice/units.
Final Architecture¶
- Data source: existing
GET /backoffice/unitsendpoint (unchanged) - Treemap hierarchy: built entirely on the frontend from
emission_breakdown.module_breakdownusinguseEmissionTreemap.tscomposable - Chart component: reuse existing
GenericEmissionTreeMapChart.vue - No new endpoint introduced
API Contract¶
- Endpoint:
GET /backoffice/units(unchanged) - Request filters (unchanged):
years,path_lvl2,path_lvl3,path_lvl4,completion_status,search,modules,page,page_size - Response fields consumed by the treemap:
emission_breakdown.module_breakdown— flat per-category rows used as treemap inputemission_breakdown.validated_categories— used to filter out unvalidated categories
Composable Contract¶
useEmissionTreemap.ts exposes:
export interface EmissionTreemapChild {
name: string;
value: number;
percentage: number;
}
export interface EmissionTreemapCategory {
name: string;
value: number;
percentage: number;
children: EmissionTreemapChild[];
}
// Builds treemap hierarchy from flat module_breakdown rows.
// Uses categoryChartKeys to determine which keys are children of each category.
export function buildModuleTreemapData(
rows: Array<{ category: string; [key: string]: number | string }>,
categoryChartKeys: Record<string, string[]>,
): EmissionTreemapCategory[];
// Builds treemap for the results summary from module_breakdown totals.
export function buildResultsTreemapData(
moduleBreakdown: Array<{ category: string; [key: string]: number | string }>,
): EmissionTreemapCategory[];
categoryChartKeys mirrors the backend constant:
const CATEGORY_CHART_KEYS: Record<string, string[]> = {
Processes: [],
"Buildings energy consumption": ["energy"],
"Buildings room": ["grey_energy"],
Equipment: ["scientific", "it", "other"],
"External cloud & AI": [
"stockage",
"virtualisation",
"calcul",
"ai_provider",
],
Purchases: [],
"Research facilities": [],
"Professional travel": ["plane", "train"],
};
Implementation Status¶
Backend¶
-
emission_breakdown.module_breakdownalready exposed by/backoffice/units - No additional backend changes required
Frontend¶
- Create
frontend/src/composables/useEmissionTreemap.ts - Export
EmissionTreemapChildandEmissionTreemapCategoryinterfaces - Implement
buildModuleTreemapData()— builds hierarchy from flatmodule_breakdownrows - Implement
buildResultsTreemapData()— top-level category totals for summary treemap - Update
GenericEmissionTreeMapChart.vue - Import
EmissionTreemapChild/EmissionTreemapCategoryfrom composable instead of defining them inline - Remove
TREEMAP_LABEL_KEY_MAP,resolveLabel,getCategoryScale,levelColor,getFixedSubcategoryColor— replace with simple colour assignment from category color map - Add treemap to
ReportingPage.vue - Derive
treemapDatafromreportingEmissionBreakdown.module_breakdownviabuildResultsTreemapData() - Render
<GenericEmissionTreeMapChart :data="treemapData" />below the existingModuleCarbonFootprintChart/CarbonFootPrintPerPersonChartpair - Gate rendering on
treemapData.length > 0 - Update
ModuleCharts.vue - Replace inline
buildTreemapFromRows()andbuildModuleTreemapData()withbuildModuleTreemapData()imported fromuseEmissionTreemap.ts - Remove local
BackendTreemapCategorytype; align to composable types
Validation Checklist¶
- Treemap categories match
module_breakdowncategory totals exactly - Children (subcategories) sum to their parent category value
- Year and hierarchy filters update table + treemap together
- Completion filter updates table + treemap together
- Treemap hides / shows correctly when filtered result set is empty
- Module-level tab selection renders correct subcategory breakdown
- Colour assignment is consistent with
ModuleCarbonFootprintChart
Non-Goals¶
- No backend treemap hierarchy construction (
module_treemap,module_breakdown_parents) - No new aggregation endpoint
- No multi-level colour scales (
CHART_CATEGORY_COLOR_SCALES,CHART_SUBCATEGORY_COLOR_SCHEMES) - No YY subcategory keys (
co2,ch4,n2o,refrigerants, …)
Risks / Follow-ups¶
module_breakdownis currently page-scoped (current page units only); full filtered aggregation across all pages requires a dedicated aggregate query in a follow-upGenericEmissionTreeMapChart.vueinline type definitions must be removed before the composable types can be shared withModuleCharts.vuewithout duplication