@golemio/energetics 1.16.2-dev.2870938995 → 1.17.0-dev.2892367644

package/db/example/00_clear_test_data.sql

@@ -26,6 +26,7 @@ truncate enapo_ppas_commercial_invoice_installations;
 truncate enapo_ppas_commercial_invoice_device;
 truncate enapo_ppas_commercial_invoice_price;
 truncate enapo_budova_spotrebic;
+truncate enapo_eb_consumption;
 truncate enapo_porsenna_buildings;
 truncate enapo_porsenna_devices;
 truncate enapo_porsenna_consumption;

package/db/example/09_enapo_consumption_history.sql

@@ -187,5 +187,47 @@ INSERT INTO enapo_porsenna_consumption (source, device_id, "var", "period", valu
 	('prague-7', '9a000000-0000-0000-0000-000000000002', 'monthly', '2025-13', 5.0, 'm3', 'water', 30);
 
 
+-- =================================================================================================
+-- Energy Broker history (enapo_eb_consumption), on its own GID so GIDCH1 keeps one electricity series
+-- =================================================================================================
+
+INSERT INTO eno_budova (gid, zdroj, nazev, oznaceni, platnost_od) VALUES
+	('GIDCH4', 'mhmp', 'Objekt s historií EB', 'OHE', '2019-01-01');
+
+INSERT INTO enapo_gid_mapping (place_id, id_type, commodity, gid, is_first_gid, link_source, valid_from, valid_to) VALUES
+	('859182400000000401', 'ean', 'electricity', 'GIDCH4', true, 'mock', '2022-01-01', NULL),
+	('27ZG100Z0000CH41', 'eic', 'gas', 'GIDCH4', true, 'mock', '2022-01-01', NULL);
+
+-- Values are MWh; the view serves kWh.
+INSERT INTO enapo_eb_consumption (idodbmisto_rspotrebyfa, idodbmistoom, ean_eic, komodita, datum_od, datum_do,
+	spotreba_vt, spotreba_nt, spotreba_mwh, rok) VALUES
+	-- 2026-01: 1500 kWh. The second row is the same month under a re-registered OM (production has
+	-- these with identical values) - it must not double the month to 3000.
+	(9000001, 90401, '859182400000000401', 1, '2026-01-01', '2026-01-31', 1.0, 0.5, 1.5, 2026),
+	(9000002, 90402, '859182400000000401', 1, '2026-01-01', '2026-01-31', 1.0, 0.5, 1.5, 2026),
+	-- 2026-02: 800 kWh, kept although PRE reports 10 days of February - a partial live month loses.
+	(9000003, 90401, '859182400000000401', 1, '2026-02-01', '2026-02-28', 0.5, 0.3, 0.8, 2026),
+	-- 2026-03: PRE read the whole month (310 kWh), so this 9000 kWh must not show up anywhere.
+	(9000004, 90401, '859182400000000401', 1, '2026-03-01', '2026-03-31', 6.0, 3.0, 9.0, 2026),
+	-- Two-month and mid-month billing periods are out of scope and must be skipped, not allocated.
+	(9000005, 90401, '859182400000000401', 1, '2025-11-01', '2025-12-31', 4.0, 2.0, 6.0, 2025),
+	(9000006, 90401, '859182400000000401', 1, '2025-10-15', '2025-10-31', 1.0, 0.0, 1.0, 2025),
+	-- Gas: kWh as well, EB has no combustion heat to derive m3.
+	(9000007, 90403, '27ZG100Z0000CH41', 2, '2026-01-01', '2026-01-31', 12.345, NULL, 12.345, 2026);
+
+-- The PPAS meter reads all of January too, but in m3 only: EB must still serve the month, being its only kWh.
+INSERT INTO enapo_measurements (id, id_type, value, "timestamp", var, source, place_id, device_serial_number) VALUES
+	('27ZG100Z0000CH41', 'eic', 1200.0, '2026-02-01 01:00:00+01', 'corediff', 'ppas_ave_api', '9900041', 'GAS-CH-4'),
+	('27ZG100Z0000CH41', 'eic', 600000.0, '2026-01-01 01:00:00+01', 'core', 'ppas_ave_api', '9900041', 'GAS-CH-4'),
+	('27ZG100Z0000CH41', 'eic', 601200.0, '2026-02-01 01:00:00+01', 'core', 'ppas_ave_api', '9900041', 'GAS-CH-4');
+
+INSERT INTO enapo_measurements (id, id_type, value, "timestamp", var, source, place_id, device_serial_number)
+SELECT '859182400000000401', 'ean', 10.0, d, 'EActi_VT_NT_DaySum', 'predi_input', '8110000401', 'EL-CH-4'
+FROM generate_series(timestamptz '2026-03-01 00:00:00+00', timestamptz '2026-03-31 00:00:00+00', interval '1 day') d;
+INSERT INTO enapo_measurements (id, id_type, value, "timestamp", var, source, place_id, device_serial_number)
+SELECT '859182400000000401', 'ean', 10.0, d, 'EActi_VT_NT_DaySum', 'predi_input', '8110000401', 'EL-CH-4'
+FROM generate_series(timestamptz '2026-02-19 00:00:00+00', timestamptz '2026-02-28 00:00:00+00', interval '1 day') d;
+
+
 REFRESH MATERIALIZED VIEW mv_ded_building_search;
 REFRESH MATERIALIZED VIEW mv_enapo_om_consumption;

package/db/migrations/postgresql/20260923090000-enapo-consumption-history-eb.js

@@ -0,0 +1,53 @@
+'use strict';
+
+var dbm;
+var type;
+var seed;
+var fs = require('fs');
+var path = require('path');
+var Promise;
+
+/**
+  * We receive the dbmigrate dependency from dbmigrate initially.
+  * This enables us to not have to rely on NODE_PATH.
+  */
+exports.setup = function(options, seedLink) {
+  dbm = options.dbmigrate;
+  type = dbm.dataType;
+  seed = seedLink;
+  Promise = options.Promise;
+};
+
+exports.up = function(db) {
+  var filePath = path.join(__dirname, 'sqls', '20260923090000-enapo-consumption-history-eb-up.sql');
+  return new Promise( function( resolve, reject ) {
+    fs.readFile(filePath, {encoding: 'utf-8'}, function(err,data){
+      if (err) return reject(err);
+      console.log('received data: ' + data);
+
+      resolve(data);
+    });
+  })
+  .then(function(data) {
+    return db.runSql(data);
+  });
+};
+
+exports.down = function(db) {
+  var filePath = path.join(__dirname, 'sqls', '20260923090000-enapo-consumption-history-eb-down.sql');
+  return new Promise( function( resolve, reject ) {
+    fs.readFile(filePath, {encoding: 'utf-8'}, function(err,data){
+      if (err) return reject(err);
+      console.log('received data: ' + data);
+
+      resolve(data);
+    });
+  })
+  .then(function(data) {
+    return db.runSql(data);
+  });
+};
+
+exports._meta = {
+  "version": 1
+};

package/db/migrations/postgresql/sqls/20260923090000-enapo-consumption-history-eb-down.sql

@@ -0,0 +1,452 @@
+DROP MATERIALIZED VIEW IF EXISTS mv_enapo_om_consumption;
+
+CREATE MATERIALIZED VIEW mv_enapo_om_consumption AS
+WITH bounds AS (
+	SELECT
+		((date_trunc('month', now() AT TIME ZONE 'Europe/Prague') - interval '48 months')
+			AT TIME ZONE 'Europe/Prague') AS month_from_tstz,
+		(date_trunc('month', now() AT TIME ZONE 'Europe/Prague') - interval '48 months') AS month_from,
+		(date_trunc('month', now() AT TIME ZONE 'Europe/Prague')
+			AT TIME ZONE 'Europe/Prague') AS month_to_tstz,
+		date_trunc('month', now() AT TIME ZONE 'Europe/Prague') AS month_to
+),
+
+point AS (
+	SELECT DISTINCT gid, place_id, id_type, commodity
+	FROM v_enapo_building_consumption_points
+),
+
+electricity_metered AS (
+	SELECT
+		em.id AS place_id,
+		date_trunc('month', em."timestamp" AT TIME ZONE 'Europe/Prague')::date AS period_start,
+		sum(em.value) FILTER (WHERE em.var = 'EActi_VT_NT_DaySum') AS total_kwh,
+		sum(em.value) FILTER (WHERE em.var = 'EActi_VT_DaySum')    AS vt_kwh,
+		sum(em.value) FILTER (WHERE em.var = 'EActi_NT_DaySum')    AS nt_kwh,
+		-- Coverage is the max day-count across the three vars, not just the total's.
+		GREATEST(
+			count(*) FILTER (WHERE em.var = 'EActi_VT_NT_DaySum'),
+			count(*) FILTER (WHERE em.var = 'EActi_VT_DaySum'),
+			count(*) FILTER (WHERE em.var = 'EActi_NT_DaySum')
+		) AS days_covered
+	FROM enapo_measurements em
+	CROSS JOIN bounds b
+	WHERE em.source = 'predi_input'
+		AND em.var IN ('EActi_VT_NT_DaySum', 'EActi_VT_DaySum', 'EActi_NT_DaySum')
+		AND em."timestamp" >= b.month_from_tstz
+		AND em."timestamp" < b.month_to_tstz
+	GROUP BY em.id, date_trunc('month', em."timestamp" AT TIME ZONE 'Europe/Prague')::date
+),
+
+gas_registration AS (
+	SELECT DISTINCT ON (em.id, em.device_serial_number)
+		em.id,
+		em.device_serial_number,
+		em.place_id
+	FROM enapo_measurements em
+	CROSS JOIN bounds b
+	WHERE em.source = 'ppas_ave_api'
+		AND em.var IN ('core2', 'corediff')
+		AND em."timestamp" >= b.month_from_tstz
+	GROUP BY em.id, em.device_serial_number, em.place_id
+	ORDER BY em.id, em.device_serial_number, max(em."timestamp") DESC, em.place_id DESC
+),
+gas_core_month AS (
+	-- Cumulative 'core' reading (m3) at the first measured hour of each first-of-month day, kept
+	-- per (id, device_serial_number, place_id) - an id can carry several registrations (see
+	-- gas_registration) whose diffs must be summed separately, not collapsed into one reading.
+	SELECT DISTINCT ON (em.id, em.device_serial_number, em.place_id,
+		date_trunc('month', em."timestamp" AT TIME ZONE 'Europe/Prague'))
+		em.id,
+		em.device_serial_number,
+		em.place_id,
+		date_trunc('month', em."timestamp" AT TIME ZONE 'Europe/Prague')::date AS month_start,
+		em.value
+	FROM enapo_measurements em
+	CROSS JOIN bounds b
+	INNER JOIN gas_registration gr
+		ON gr.id = em.id
+		AND gr.device_serial_number = em.device_serial_number
+		AND gr.place_id = em.place_id
+	WHERE em.source = 'ppas_ave_api'
+		AND em.var = 'core'
+		AND (em."timestamp" AT TIME ZONE 'Europe/Prague')::date
+			= date_trunc('month', em."timestamp" AT TIME ZONE 'Europe/Prague')::date
+		AND em."timestamp" >= b.month_from_tstz
+		AND em."timestamp" < (b.month_to_tstz + interval '1 month')
+	ORDER BY em.id, em.device_serial_number, em.place_id,
+		date_trunc('month', em."timestamp" AT TIME ZONE 'Europe/Prague'), em."timestamp"
+),
+gas_metered AS (
+	SELECT
+		cur.id AS place_id,
+		cur.month_start AS period_start,
+		-- A negative diff means the meter was exchanged/reset between the two boundary readings -
+		-- null rather than a nonsense negative volume.
+		(CASE WHEN sum(nxt.value - cur.value) < 0 THEN NULL ELSE sum(nxt.value - cur.value) END) AS m3_sum,
+		((cur.month_start + interval '1 month')::date - cur.month_start) AS days_covered
+	FROM gas_core_month cur
+	INNER JOIN gas_core_month nxt
+		ON nxt.id = cur.id
+		AND nxt.device_serial_number = cur.device_serial_number
+		AND nxt.place_id = cur.place_id
+		AND nxt.month_start = (cur.month_start + interval '1 month')::date
+	GROUP BY cur.id, cur.month_start
+),
+
+distribution_device AS (
+	SELECT DISTINCT ON (ins.eic, d.place_id, d.device_serial_number, d.date_from, d.date_to, d.kind, d.unit)
+		ins.eic,
+		d.place_id,
+		d.invoice_id,
+		d.date_from,
+		d.date_to,
+		d.kind,
+		d.unit,
+		d.consumption,
+		d.normometers_nm3,
+		d.gas_consumption_kwh,
+		d.combustion_heat
+	FROM enapo_ppas_distribution_invoice_device d
+	INNER JOIN enapo_ppas_distribution_invoice i
+		ON i.id = d.invoice_id
+	INNER JOIN enapo_ppas_distribution_installation ins
+		ON ins.invoice_id = d.invoice_id
+		AND ins.customer_id = i.customer_id
+		AND ins.place_id = d.place_id
+	WHERE COALESCE(i.is_canceled, false) = false
+		AND d.date_to >= d.date_from
+		AND d.consumption IS NOT NULL
+		AND d.kind IN ('ZIZWC', 'ZIABN3')
+		AND d.reading_type = 'STANDARD'
+		AND NOT EXISTS (
+			SELECT 1 FROM enapo_ppas_distribution_invoice s
+			WHERE s.preceding_id = i.id AND COALESCE(s.is_canceled, false) = false
+		)
+	ORDER BY ins.eic, d.place_id, d.device_serial_number, d.date_from, d.date_to, d.kind, d.unit,
+		i.facts_doc_date DESC, i.id DESC
+),
+commercial_device AS (
+	SELECT DISTINCT ON (ins.eic, d.place_id, d.device_serial_number, d.date_from, d.date_to, d.kind, d.unit)
+		ins.eic,
+		d.place_id,
+		d.invoice_id,
+		d.date_from,
+		d.date_to,
+		d.kind,
+		d.unit,
+		d.consumption,
+		d.normometers_nm3,
+		d.gas_consumption_kwh,
+		d.combustion_heat
+	FROM enapo_ppas_commercial_invoice_device d
+	INNER JOIN enapo_ppas_commercial_invoice i
+		ON i.id = d.invoice_id
+	INNER JOIN enapo_ppas_commercial_invoice_installations ins
+		ON ins.invoice_id = d.invoice_id
+		AND ins.customer_id = i.customer_id
+		AND ins.place_id = d.place_id
+	WHERE COALESCE(i.is_canceled, false) = false
+		AND d.date_to >= d.date_from
+		AND d.consumption IS NOT NULL
+		AND d.reading_type = 'STANDARD'
+		AND NOT EXISTS (
+			SELECT 1 FROM enapo_ppas_commercial_invoice s
+			WHERE s.preceding_id = i.id AND COALESCE(s.is_canceled, false) = false
+		)
+	ORDER BY ins.eic, d.place_id, d.device_serial_number, d.date_from, d.date_to, d.kind, d.unit,
+		i.facts_doc_date DESC, i.id DESC
+),
+
+invoice_device_month AS (
+	SELECT
+		'ppas_distribution_invoice' AS source,
+		d.eic AS place_id,
+		d.invoice_id,
+		gs.month::date AS period_start,
+		CASE WHEN d.unit = 'KWH' THEN NULL ELSE d.consumption END * o.share AS volume,
+		CASE WHEN d.unit = 'NM3' THEN 'Nm3' ELSE 'm3' END AS volume_unit,
+		d.normometers_nm3 * o.share AS nm3,
+		NULLIF(d.gas_consumption_kwh, 0) * o.share AS kwh,
+		(o.share < 1) AS is_estimated,
+		o.overlap_days AS days_covered
+	FROM distribution_device d
+	CROSS JOIN bounds b
+	CROSS JOIN LATERAL generate_series(
+		date_trunc('month', d.date_from::timestamp),
+		date_trunc('month', d.date_to::timestamp),
+		interval '1 month'
+	) gs(month)
+	CROSS JOIN LATERAL (
+		SELECT
+			ov.overlap_days,
+			ov.overlap_days::numeric / NULLIF(d.date_to - d.date_from + 1, 0) AS share
+		FROM (
+			SELECT LEAST(d.date_to, (gs.month + interval '1 month - 1 day')::date)
+				- GREATEST(d.date_from, gs.month::date) + 1 AS overlap_days
+		) ov
+	) o
+	WHERE gs.month >= b.month_from AND gs.month < b.month_to
+
+	UNION ALL
+
+	SELECT
+		'ppas_commercial_invoice',
+		d.eic,
+		d.invoice_id,
+		gs.month::date,
+		CASE WHEN d.unit = 'KWH' THEN NULL ELSE d.consumption END * o.share,
+		CASE WHEN d.unit = 'NM3' THEN 'Nm3' ELSE 'm3' END,
+		d.normometers_nm3 * o.share,
+		NULLIF(d.gas_consumption_kwh, 0) * o.share,
+		(o.share < 1),
+		o.overlap_days
+	FROM commercial_device d
+	CROSS JOIN bounds b
+	CROSS JOIN LATERAL generate_series(
+		date_trunc('month', d.date_from::timestamp),
+		date_trunc('month', d.date_to::timestamp),
+		interval '1 month'
+	) gs(month)
+	CROSS JOIN LATERAL (
+		SELECT
+			ov.overlap_days,
+			ov.overlap_days::numeric / NULLIF(d.date_to - d.date_from + 1, 0) AS share
+		FROM (
+			SELECT LEAST(d.date_to, (gs.month + interval '1 month - 1 day')::date)
+				- GREATEST(d.date_from, gs.month::date) + 1 AS overlap_days
+		) ov
+	) o
+	WHERE gs.month >= b.month_from AND gs.month < b.month_to
+),
+invoice_month AS (
+	SELECT
+		source,
+		place_id,
+		period_start,
+		sum(volume)           AS volume,
+		max(volume_unit)      AS volume_unit,
+		sum(nm3)              AS nm3,
+		sum(kwh)              AS kwh,
+		bool_or(is_estimated) AS is_estimated,
+		-- Clamp to the month's length: sum() would exceed it when meters are billed in parallel.
+		LEAST(
+			sum(days_covered),
+			(period_start + interval '1 month')::date - period_start
+		) AS days_covered,
+		array_agg(DISTINCT invoice_id::text ORDER BY invoice_id::text) AS invoice_ids
+	FROM invoice_device_month
+	GROUP BY source, place_id, period_start
+),
+invoice_year AS (
+	SELECT
+		source,
+		place_id,
+		date_trunc('year', period_start)::date AS period_start,
+		array_agg(DISTINCT invoice_id::text ORDER BY invoice_id::text) AS invoice_ids
+	FROM invoice_device_month
+	GROUP BY source, place_id, date_trunc('year', period_start)::date
+),
+
+porsenna_period AS (
+	SELECT *
+	FROM (
+		SELECT
+			d.identifier AS place_id,
+			c.commodity,
+			c."var" AS period_type,
+			f_enapo_safe_period(c."var", c."period") AS period_start,
+			c.value,
+			c.unit,
+			c."count" AS days_covered
+		FROM enapo_porsenna_consumption c
+		INNER JOIN enapo_porsenna_devices d
+			ON d.source = c.source AND d.id = c.device_id
+		WHERE d.identifier IS NOT NULL
+			AND (d."level" IS NULL OR d."level" = 'main')
+			AND c.commodity IS NOT NULL
+			AND c."var" IN ('yearly', 'monthly')
+	) parsed
+	WHERE parsed.period_start IS NOT NULL
+),
+
+monthly AS (
+	SELECT
+		p.gid,
+		p.place_id,
+		p.id_type,
+		p.commodity,
+		'predi_input'::varchar(50) AS source,
+		'monthly'::varchar(10) AS period_type,
+		e.period_start,
+		COALESCE(e.total_kwh, e.vt_kwh + e.nt_kwh, e.vt_kwh, e.nt_kwh) AS value,
+		'kWh'::varchar(10) AS unit,
+		COALESCE(e.total_kwh, e.vt_kwh + e.nt_kwh, e.vt_kwh, e.nt_kwh) AS value_kwh,
+		'EActi_VT_NT_DaySum'::varchar(50) AS internal_source_var,
+		e.days_covered,
+		false AS is_estimated,
+		'{}'::text[] AS invoice_ids
+	FROM point p
+	INNER JOIN electricity_metered e ON e.place_id = p.place_id
+	WHERE p.commodity = 'electricity'
+
+	UNION ALL
+
+	SELECT
+		p.gid,
+		p.place_id,
+		p.id_type,
+		p.commodity,
+		'ppas_ave_api',
+		'monthly',
+		g.period_start,
+		g.m3_sum,
+		'm3',
+		NULL::numeric,
+		'core',
+		g.days_covered,
+		false,
+		'{}'::text[]
+	FROM point p
+	INNER JOIN gas_metered g ON g.place_id = p.place_id
+	WHERE p.commodity = 'gas'
+
+	UNION ALL
+
+	SELECT
+		p.gid,
+		p.place_id,
+		p.id_type,
+		p.commodity,
+		i.source,
+		'monthly',
+		i.period_start,
+		COALESCE(i.volume, i.nm3::numeric),
+		CASE WHEN i.volume IS NOT NULL THEN i.volume_unit ELSE 'Nm3' END,
+		i.kwh,
+		NULL,
+		i.days_covered,
+		i.is_estimated,
+		i.invoice_ids
+	FROM point p
+	INNER JOIN invoice_month i ON i.place_id = p.place_id
+	WHERE p.commodity = 'gas'
+
+),
+
+yearly_rollup AS (
+	SELECT
+		gid,
+		place_id,
+		id_type,
+		commodity,
+		source,
+		'yearly'::varchar(10) AS period_type,
+		date_trunc('year', period_start)::date AS period_start,
+		sum(value) AS value,
+		unit,
+		-- count(*) = count(value_kwh) is an all-non-null check: only sum value_kwh when every month has one.
+		CASE WHEN count(*) = count(value_kwh) THEN sum(value_kwh) END AS value_kwh,
+		max(internal_source_var) AS internal_source_var,
+		sum(days_covered) AS days_covered,
+		bool_or(is_estimated) AS is_estimated
+	FROM monthly m
+	GROUP BY gid, place_id, id_type, commodity, source, date_trunc('year', period_start)::date, unit
+),
+yearly AS (
+	SELECT
+		r.gid,
+		r.place_id,
+		r.id_type,
+		r.commodity,
+		r.source,
+		r.period_type,
+		r.period_start,
+		r.value,
+		r.unit,
+		r.value_kwh,
+		r.internal_source_var,
+		r.days_covered,
+		r.is_estimated,
+		COALESCE(iy.invoice_ids, '{}'::text[]) AS invoice_ids
+	FROM yearly_rollup r
+	LEFT JOIN invoice_year iy
+		ON iy.source = r.source AND iy.place_id = r.place_id AND iy.period_start = r.period_start
+
+	UNION ALL
+
+	SELECT
+		p.gid,
+		p.place_id,
+		p.id_type,
+		p.commodity,
+		'porsenna',
+		'yearly',
+		pp.period_start,
+		pp.value,
+		pp.unit,
+		CASE WHEN lower(pp.unit) = 'kwh' THEN pp.value ELSE NULL END,
+		NULL,
+		pp.days_covered,
+		false,
+		'{}'::text[]
+	FROM point p
+	INNER JOIN porsenna_period pp
+		ON pp.place_id = p.place_id AND pp.commodity = p.commodity
+	WHERE pp.period_type = 'yearly'
+)
+
+SELECT
+	gid::varchar AS gid,
+	place_id::varchar(50) AS place_id,
+	max(id_type)::varchar(10) AS id_type,
+	commodity::varchar(20) AS commodity,
+	source::varchar(50) AS source,
+	period_type::varchar(10) AS period_type,
+	period_start,
+	sum(value)::numeric(30, 6) AS value,
+	unit::varchar(10) AS unit,
+	(CASE WHEN count(*) = count(value_kwh) THEN sum(value_kwh) END)::numeric(30, 6) AS value_kwh,
+	max(internal_source_var)::varchar(50) AS internal_source_var,
+	COALESCE(max(invoice_ids), '{}'::text[]) AS invoice_ids,
+	max(days_covered)::int AS coverage_count,
+	(
+		CASE period_type
+			WHEN 'yearly' THEN (make_date(extract(year FROM period_start)::int + 1, 1, 1) - period_start)
+			ELSE (period_start + interval '1 month')::date - period_start
+		END
+	)::int AS expected_count,
+	bool_or(is_estimated) AS is_estimated
+FROM (
+	SELECT * FROM monthly
+	UNION ALL
+	SELECT * FROM yearly
+) all_periods
+WHERE value IS NOT NULL
+GROUP BY gid, place_id, commodity, source, unit, period_type, period_start;
+
+
+COMMENT ON MATERIALIZED VIEW mv_enapo_om_consumption IS
+	'Monthly and yearly consumption per consumption point per source, for the last 48 months, behind the DeD building detail endpoint. One row per (gid, place_id, commodity, source, unit, period_type, period_start). Refreshed by EnapoConsumptionHistoryRefreshTask (integration engine).';
+
+COMMENT ON COLUMN mv_enapo_om_consumption.place_id IS
+	'EAN / EIC / OM code, as in enapo_gid_mapping.place_id - NOT enapo_measurements.place_id, which holds a PPAS-internal place id. Measurements are joined through enapo_measurements.id.';
+COMMENT ON COLUMN mv_enapo_om_consumption.value IS
+	'Consumption for the period in `unit`. Electricity is kWh (the upstream T1_Wh_total naming is wrong); metered gas is m3, the difference between the cumulative `core` reading on the first day of the next month and the first day of the current month; invoiced gas follows the invoice unit; Porsenna carries its own unit.';
+COMMENT ON COLUMN mv_enapo_om_consumption.value_kwh IS
+	'Derived comparable energy: for gas, normometers_nm3 * combustion_heat (verified exact). NULL when the conversion inputs are missing - `value` + `unit` stay authoritative. Always NULL for metered gas (no normometers_nm3 input).';
+COMMENT ON COLUMN mv_enapo_om_consumption.internal_source_var IS
+	'Which enapo_measurements.var produced the row; NULL for invoice and Porsenna rows. Provenance for debugging, not part of the public response.';
+COMMENT ON COLUMN mv_enapo_om_consumption.invoice_ids IS
+	'Billing documents the row was allocated from, sorted and deduplicated; empty for metered and Porsenna rows. A period can be allocated from several invoices (a yearly roll-up usually is), which is why it is an array.';
+COMMENT ON COLUMN mv_enapo_om_consumption.coverage_count IS
+	'Days of the period that carry data. Days for every commodity and both period types, so it is comparable with expected_count.';
+COMMENT ON COLUMN mv_enapo_om_consumption.expected_count IS 'Days in the period (28-31, or 365/366).';
+COMMENT ON COLUMN mv_enapo_om_consumption.is_estimated IS
+	'True when the value was allocated pro rata from a billing period spanning more than one month, rather than read for the period itself.';
+
+CREATE UNIQUE INDEX mv_enapo_om_consumption_uidx
+	ON mv_enapo_om_consumption (gid, place_id, commodity, source, unit, period_type, period_start);
+
+CREATE INDEX mv_enapo_om_consumption_gid_period_idx
+	ON mv_enapo_om_consumption (gid, period_type, period_start);