@golemio/energetics 2.0.0-dev.2954231424 → 2.0.0-dev.2962537365

package/db/example/09_enapo_consumption_history.sql

@@ -177,7 +177,14 @@ INSERT INTO enapo_ppas_distribution_invoice_device (device_serial_number, invoic
 	-- combustion_heat = 0 means "not supplied", not a real coefficient: value_kwh must be null here,
 	-- not 0, because 0 would be charted as a real reading. April, so it does not disturb June.
 	('GAS-CH-1', 'DI-CH-001', '9900001', '2026-04-01', '2026-04-30', 'G4', 'ZIZWC', 'STANDARD',
-		300.0, 'M3', 0.0, 0.0, 0.0, 300.0);
+		300.0, 'M3', 0.0, 0.0, 0.0, 300.0),
+	-- A month without consumption, as PPAS bills it (27ZG100Z00382385 in summer): no consumption at all,
+	-- zero Nm3 and zero kWh. It is 0 m3 and 0 kWh, not missing data.
+	('GAS-CH-1', 'DI-CH-001', '9900001', '2026-08-01', '2026-08-31', 'G4', 'ZIZWC', 'STANDARD',
+		NULL, 'M3', 0.0, 1.0043, 10.55, 0.0),
+	-- No consumption and no Nm3 or kWh either: nothing says the month was zero, so it stays missing.
+	('GAS-CH-1', 'DI-CH-001', '9900001', '2026-09-01', '2026-09-30', 'G4', 'ZIZWC', 'STANDARD',
+		NULL, 'M3', NULL, 1.0043, 10.55, NULL);
 
 
 -- =================================================================================================

package/db/migrations/postgresql/20261019090000-enapo-consumption-history-invoice-zero.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', '20261019090000-enapo-consumption-history-invoice-zero-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', '20261019090000-enapo-consumption-history-invoice-zero-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/20261019090000-enapo-consumption-history-invoice-zero-down.sql

@@ -0,0 +1,492 @@
+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_core_month AS (
+	-- Cumulative 'core' reading (m3) at the first measured hour of each first-of-month day, kept per
+	-- (id, place_id): an id can carry several meters, one per PPAS place id, whose diffs are summed.
+	-- Not per device_serial_number - the integration stamps every refetched hour with the serial AVE
+	-- lists at fetch time, so the serial is unreliable for history and would split one meter in two.
+	SELECT DISTINCT ON (em.id, em.place_id, date_trunc('month', em."timestamp" AT TIME ZONE 'Europe/Prague'))
+		em.id,
+		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
+	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.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 meter reading only grows, so a negative month total means a meter was exchanged or reset:
+		-- the month stays empty. Checked on the total, so a tiny drop on a small meter does not empty it.
+		(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.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
+),
+
+eb_month AS (
+	-- Energy Broker history, full calendar months only: a period that is longer or does not start on
+	-- the 1st needs the pro-rata methodology, which is a separate step. One EAN/EIC can appear under
+	-- two idodbmistoom with identical values (a re-registered OM), so one row per month is kept instead
+	-- of summing them into a double. The highest idodbmisto_rspotrebyfa stands in for the newest row: the
+	-- one-off import has no timestamp, and in production the duplicates carry identical values.
+	SELECT DISTINCT ON (eb.ean_eic, eb.komodita, eb.datum_od)
+		eb.ean_eic AS place_id,
+		CASE eb.komodita WHEN 1 THEN 'electricity' WHEN 2 THEN 'gas' END AS commodity,
+		eb.datum_od AS period_start,
+		eb.spotreba_mwh * 1000 AS value_kwh,
+		eb.datum_do - eb.datum_od + 1 AS days_covered
+	FROM enapo_eb_consumption eb
+	CROSS JOIN bounds b
+	WHERE eb.spotreba_mwh IS NOT NULL
+		AND eb.datum_od = date_trunc('month', eb.datum_od)::date
+		AND eb.datum_do = (date_trunc('month', eb.datum_od) + interval '1 month - 1 day')::date
+		AND eb.datum_od >= b.month_from
+		AND eb.datum_od < b.month_to
+	ORDER BY eb.ean_eic, eb.komodita, eb.datum_od, eb.idodbmisto_rspotrebyfa DESC
+),
+
+live_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',
+		-- No conversion inputs for metered gas, but no consumption is 0 kWh whatever the conversion.
+		CASE WHEN g.m3_sum = 0 THEN 0 END,
+		'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'
+),
+
+monthly AS (
+	SELECT * FROM live_monthly
+
+	UNION ALL
+
+	SELECT
+		p.gid,
+		p.place_id,
+		p.id_type,
+		p.commodity,
+		'energy_broker',
+		'monthly',
+		e.period_start,
+		e.value_kwh,
+		'kWh',
+		e.value_kwh,
+		NULL,
+		e.days_covered,
+		false,
+		'{}'::text[]
+	FROM point p
+	INNER JOIN eb_month e ON e.place_id = p.place_id AND e.commodity = p.commodity
+	-- A live source that read the whole month in kWh wins, so the overlap is not charted twice. A pro-rata
+	-- invoice or a partially covered month does not win: the EB figure is billed for the whole month. Nor
+	-- does a volume-only row (the PPAS gas meter): EB is the only kWh for that month, which the combined
+	-- kWh series needs - unless the meter read no consumption, which is 0 kWh and wins.
+	WHERE NOT EXISTS (
+		SELECT 1
+		FROM live_monthly l
+		WHERE l.place_id = e.place_id
+			AND l.commodity = e.commodity
+			AND l.period_start = e.period_start
+			AND l.value_kwh IS NOT NULL
+			AND NOT l.is_estimated
+			AND l.days_covered >= (e.period_start + interval '1 month')::date - e.period_start
+	)
+),
+
+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; Energy Broker (enapo_eb_consumption, full calendar months only, suppressed where a live source read the whole month) is kWh converted from MWh for both electricity and gas.';
+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. NULL for metered gas (no normometers_nm3 input), except 0 when no gas was consumed.';
+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);

package/db/migrations/postgresql/sqls/20261019090000-enapo-consumption-history-invoice-zero-up.sql

@@ -0,0 +1,495 @@
+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_core_month AS (
+	-- Cumulative 'core' reading (m3) at the first measured hour of each first-of-month day, kept per
+	-- (id, place_id): an id can carry several meters, one per PPAS place id, whose diffs are summed.
+	-- Not per device_serial_number - the integration stamps every refetched hour with the serial AVE
+	-- lists at fetch time, so the serial is unreliable for history and would split one meter in two.
+	SELECT DISTINCT ON (em.id, em.place_id, date_trunc('month', em."timestamp" AT TIME ZONE 'Europe/Prague'))
+		em.id,
+		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
+	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.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 meter reading only grows, so a negative month total means a meter was exchanged or reset:
+		-- the month stays empty. Checked on the total, so a tiny drop on a small meter does not empty it.
+		(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.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,
+		-- PPAS bills a month without consumption as an empty consumption with zero Nm3 and kWh.
+		COALESCE(d.consumption, 0) AS 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 OR (d.normometers_nm3 = 0 AND d.gas_consumption_kwh = 0))
+		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,
+		-- PPAS bills a month without consumption as an empty consumption with zero Nm3 and kWh.
+		COALESCE(d.consumption, 0) AS 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 OR (d.normometers_nm3 = 0 AND d.gas_consumption_kwh = 0))
+		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,
+		-- A zero kWh is a missing conversion input unless nothing was consumed: no consumption is 0 kWh.
+		CASE WHEN d.consumption = 0 THEN 0 ELSE NULLIF(d.gas_consumption_kwh, 0) END * 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,
+		CASE WHEN d.consumption = 0 THEN 0 ELSE NULLIF(d.gas_consumption_kwh, 0) END * 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
+),
+
+eb_month AS (
+	-- Energy Broker history, full calendar months only: a period that is longer or does not start on
+	-- the 1st needs the pro-rata methodology, which is a separate step. One EAN/EIC can appear under
+	-- two idodbmistoom with identical values (a re-registered OM), so one row per month is kept instead
+	-- of summing them into a double. The highest idodbmisto_rspotrebyfa stands in for the newest row: the
+	-- one-off import has no timestamp, and in production the duplicates carry identical values.
+	SELECT DISTINCT ON (eb.ean_eic, eb.komodita, eb.datum_od)
+		eb.ean_eic AS place_id,
+		CASE eb.komodita WHEN 1 THEN 'electricity' WHEN 2 THEN 'gas' END AS commodity,
+		eb.datum_od AS period_start,
+		eb.spotreba_mwh * 1000 AS value_kwh,
+		eb.datum_do - eb.datum_od + 1 AS days_covered
+	FROM enapo_eb_consumption eb
+	CROSS JOIN bounds b
+	WHERE eb.spotreba_mwh IS NOT NULL
+		AND eb.datum_od = date_trunc('month', eb.datum_od)::date
+		AND eb.datum_do = (date_trunc('month', eb.datum_od) + interval '1 month - 1 day')::date
+		AND eb.datum_od >= b.month_from
+		AND eb.datum_od < b.month_to
+	ORDER BY eb.ean_eic, eb.komodita, eb.datum_od, eb.idodbmisto_rspotrebyfa DESC
+),
+
+live_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',
+		-- No conversion inputs for metered gas, but no consumption is 0 kWh whatever the conversion.
+		CASE WHEN g.m3_sum = 0 THEN 0 END,
+		'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'
+),
+
+monthly AS (
+	SELECT * FROM live_monthly
+
+	UNION ALL
+
+	SELECT
+		p.gid,
+		p.place_id,
+		p.id_type,
+		p.commodity,
+		'energy_broker',
+		'monthly',
+		e.period_start,
+		e.value_kwh,
+		'kWh',
+		e.value_kwh,
+		NULL,
+		e.days_covered,
+		false,
+		'{}'::text[]
+	FROM point p
+	INNER JOIN eb_month e ON e.place_id = p.place_id AND e.commodity = p.commodity
+	-- A live source that read the whole month in kWh wins, so the overlap is not charted twice. A pro-rata
+	-- invoice or a partially covered month does not win: the EB figure is billed for the whole month. Nor
+	-- does a volume-only row (the PPAS gas meter): EB is the only kWh for that month, which the combined
+	-- kWh series needs - unless the meter read no consumption, which is 0 kWh and wins.
+	WHERE NOT EXISTS (
+		SELECT 1
+		FROM live_monthly l
+		WHERE l.place_id = e.place_id
+			AND l.commodity = e.commodity
+			AND l.period_start = e.period_start
+			AND l.value_kwh IS NOT NULL
+			AND NOT l.is_estimated
+			AND l.days_covered >= (e.period_start + interval '1 month')::date - e.period_start
+	)
+),
+
+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; Energy Broker (enapo_eb_consumption, full calendar months only, suppressed where a live source read the whole month) is kWh converted from MWh for both electricity and gas.';
+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. NULL for metered gas (no normometers_nm3 input). Always 0 when no gas was consumed, whatever the conversion inputs.';
+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);

package/dist/output-gateway/routers/v2/V2EnoBuildingsRouter.d.ts

@@ -1,3 +1,4 @@
+import { ISimpleConfig } from "@golemio/core/dist/helpers/configuration/ISimpleConfig";
 import { AbstractRouter } from "@golemio/core/dist/helpers/routing/AbstractRouter";
 export declare class V2EnoBuildingsRouter extends AbstractRouter {
     private controller;
@@ -6,6 +7,8 @@ export declare class V2EnoBuildingsRouter extends AbstractRouter {
     private staleWhileRevalidate;
     private searchMaxAge;
     private searchStaleWhileRevalidate;
-    constructor();
+    constructor(config: ISimpleConfig);
     protected initRoutes(): void;
+    /** The detail is cached for hours by default, so an invalid value falls back to it rather than to the core's minute. */
+    private static parseMaxAge;
 }

package/dist/output-gateway/routers/v2/V2EnoBuildingsRouter.js

@@ -8,6 +8,10 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var V2EnoBuildingsRouter_1;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.V2EnoBuildingsRouter = void 0;
 const ConsumptionHistory_1 = require("../../constants/ConsumptionHistory");
@@ -16,19 +20,21 @@ const Links_1 = require("../../constants/Links");
 const RouteVersion_1 = require("../../constants/RouteVersion");
 const Di_1 = require("../../ioc/Di");
 const ModuleContainerToken_1 = require("../../ioc/ModuleContainerToken");
+const CoreToken_1 = require("@golemio/core/dist/helpers/ioc/CoreToken");
 const AbstractRouter_1 = require("@golemio/core/dist/helpers/routing/AbstractRouter");
 const Validation_1 = require("@golemio/core/dist/output-gateway/Validation");
 const ioc_1 = require("@golemio/core/dist/output-gateway/ioc");
 const express_validator_1 = require("@golemio/core/dist/shared/express-validator");
 const tsyringe_1 = require("@golemio/core/dist/shared/tsyringe");
-let V2EnoBuildingsRouter = class V2EnoBuildingsRouter extends AbstractRouter_1.AbstractRouter {
-    constructor() {
+const DEFAULT_MAX_AGE = 6 * 60 * 60; // 6 hours
+let V2EnoBuildingsRouter = V2EnoBuildingsRouter_1 = class V2EnoBuildingsRouter extends AbstractRouter_1.AbstractRouter {
+    constructor(config) {
         super(RouteVersion_1.RouteVersion.v2, Links_1.DED_BUILDING_PATH);
-        this.maxAge = 6 * 60 * 60; // 6 hours
         this.staleWhileRevalidate = 60; // 1 minute
         // Suggestions must follow ingest closely, so the search is cached far more briefly than the detail.
         this.searchMaxAge = 60; // 1 minute
         this.searchStaleWhileRevalidate = 30; // 30 seconds
+        this.maxAge = V2EnoBuildingsRouter_1.parseMaxAge(config.getValue("env.ENERGETICS_DED_BUILDING_CACHE_MAX_AGE", String(DEFAULT_MAX_AGE)));
         this.controller = Di_1.OGEnergeticsContainer.resolve(ModuleContainerToken_1.ModuleContainerToken.EnoBuildingsController);
         this.cacheHeaderMiddleware = Di_1.OGEnergeticsContainer.resolve(ioc_1.ContainerToken.CacheHeaderMiddleware);
         this.initRoutes();
@@ -37,10 +43,16 @@ let V2EnoBuildingsRouter = class V2EnoBuildingsRouter extends AbstractRouter_1.A
         this.router.get("/", (0, express_validator_1.query)("q").exists().isString().not().isArray().trim().isLength({ min: 1, max: DedSearchWeights_1.DED_SEARCH_QUERY_MAX_LENGTH }), (0, express_validator_1.query)("limit").optional().isInt({ min: 1, max: DedSearchWeights_1.DED_SEARCH_LIMIT_MAX }).toInt(), Validation_1.checkErrors, this.cacheHeaderMiddleware.getMiddleware(this.searchMaxAge, this.searchStaleWhileRevalidate), this.controller.search);
         this.router.get("/:gid", (0, express_validator_1.param)("gid").exists().isString().not().isArray().trim(), (0, express_validator_1.query)("months").optional().isInt({ min: 1, max: ConsumptionHistory_1.CONSUMPTION_HISTORY_MONTHS_MAX }).toInt(), Validation_1.checkErrors, this.cacheHeaderMiddleware.getMiddleware(this.maxAge, this.staleWhileRevalidate), this.controller.getOne);
     }
+    /** The detail is cached for hours by default, so an invalid value falls back to it rather than to the core's minute. */
+    static parseMaxAge(value) {
+        const maxAge = Number(value);
+        return Number.isInteger(maxAge) && maxAge > 0 ? maxAge : DEFAULT_MAX_AGE;
+    }
 };
 exports.V2EnoBuildingsRouter = V2EnoBuildingsRouter;
-exports.V2EnoBuildingsRouter = V2EnoBuildingsRouter = __decorate([
+exports.V2EnoBuildingsRouter = V2EnoBuildingsRouter = V2EnoBuildingsRouter_1 = __decorate([
     (0, tsyringe_1.injectable)(),
-    __metadata("design:paramtypes", [])
+    __param(0, (0, tsyringe_1.inject)(CoreToken_1.CoreToken.SimpleConfig)),
+    __metadata("design:paramtypes", [Object])
 ], V2EnoBuildingsRouter);
 //# sourceMappingURL=V2EnoBuildingsRouter.js.map

package/dist/output-gateway/routers/v2/V2EnoBuildingsRouter.js.map

@@ -1 +1 @@
-{"version":3,"file":"V2EnoBuildingsRouter.js","sourceRoot":"","sources":["../../../../src/output-gateway/routers/v2/V2EnoBuildingsRouter.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2EAAkF;AAClF,uEAAmG;AACnG,iDAAwD;AACxD,+DAA0D;AAE1D,qCAAmD;AACnD,yEAAoE;AACpE,sFAAmF;AAEnF,6EAA2E;AAC3E,+DAAuE;AACvE,mFAA2E;AAC3E,iEAAgE;AAGzD,IAAM,oBAAoB,GAA1B,MAAM,oBAAqB,SAAQ,+BAAc;IASpD;QACI,KAAK,CAAC,2BAAY,CAAC,EAAE,EAAE,yBAAiB,CAAC,CAAC;QAPtC,WAAM,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,UAAU;QAChC,yBAAoB,GAAG,EAAE,CAAC,CAAC,WAAW;QAC9C,oGAAoG;QAC5F,iBAAY,GAAG,EAAE,CAAC,CAAC,WAAW;QAC9B,+BAA0B,GAAG,EAAE,CAAC,CAAC,aAAa;QAIlD,IAAI,CAAC,UAAU,GAAG,0BAAqB,CAAC,OAAO,CAAyB,2CAAoB,CAAC,sBAAsB,CAAC,CAAC;QACrH,IAAI,CAAC,qBAAqB,GAAG,0BAAqB,CAAC,OAAO,CAAwB,oBAAc,CAAC,qBAAqB,CAAC,CAAC;QACxH,IAAI,CAAC,UAAU,EAAE,CAAC;IACtB,CAAC;IAES,UAAU;QAChB,IAAI,CAAC,MAAM,CAAC,GAAG,CACX,GAAG,EACH,IAAA,yBAAK,EAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,8CAA2B,EAAE,CAAC,EAC5G,IAAA,yBAAK,EAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,uCAAoB,EAAE,CAAC,CAAC,KAAK,EAAE,EAC9E,wBAAW,EACX,IAAI,CAAC,qBAAqB,CAAC,aAAa,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,0BAA0B,CAAC,EAC5F,IAAI,CAAC,UAAU,CAAC,MAAM,CACzB,CAAC;QAEF,IAAI,CAAC,MAAM,CAAC,GAAG,CACX,OAAO,EACP,IAAA,yBAAK,EAAC,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EACvD,IAAA,yBAAK,EAAC,QAAQ,CAAC,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,mDAA8B,EAAE,CAAC,CAAC,KAAK,EAAE,EACzF,wBAAW,EACX,IAAI,CAAC,qBAAqB,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,oBAAoB,CAAC,EAChF,IAAI,CAAC,UAAU,CAAC,MAAM,CACzB,CAAC;IACN,CAAC;CACJ,CAAA;AAnCY,oDAAoB;+BAApB,oBAAoB;IADhC,IAAA,qBAAU,GAAE;;GACA,oBAAoB,CAmChC"}
+{"version":3,"file":"V2EnoBuildingsRouter.js","sourceRoot":"","sources":["../../../../src/output-gateway/routers/v2/V2EnoBuildingsRouter.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2EAAkF;AAClF,uEAAmG;AACnG,iDAAwD;AACxD,+DAA0D;AAE1D,qCAAmD;AACnD,yEAAoE;AAEpE,wEAAqE;AACrE,sFAAmF;AAEnF,6EAA2E;AAC3E,+DAAuE;AACvE,mFAA2E;AAC3E,iEAAwE;AAExE,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,UAAU;AAGxC,IAAM,oBAAoB,4BAA1B,MAAM,oBAAqB,SAAQ,+BAAc;IASpD,YAA4C,MAAqB;QAC7D,KAAK,CAAC,2BAAY,CAAC,EAAE,EAAE,yBAAiB,CAAC,CAAC;QANtC,yBAAoB,GAAG,EAAE,CAAC,CAAC,WAAW;QAC9C,oGAAoG;QAC5F,iBAAY,GAAG,EAAE,CAAC,CAAC,WAAW;QAC9B,+BAA0B,GAAG,EAAE,CAAC,CAAC,aAAa;QAIlD,IAAI,CAAC,MAAM,GAAG,sBAAoB,CAAC,WAAW,CAC1C,MAAM,CAAC,QAAQ,CAAS,2CAA2C,EAAE,MAAM,CAAC,eAAe,CAAC,CAAC,CAChG,CAAC;QACF,IAAI,CAAC,UAAU,GAAG,0BAAqB,CAAC,OAAO,CAAyB,2CAAoB,CAAC,sBAAsB,CAAC,CAAC;QACrH,IAAI,CAAC,qBAAqB,GAAG,0BAAqB,CAAC,OAAO,CAAwB,oBAAc,CAAC,qBAAqB,CAAC,CAAC;QACxH,IAAI,CAAC,UAAU,EAAE,CAAC;IACtB,CAAC;IAES,UAAU;QAChB,IAAI,CAAC,MAAM,CAAC,GAAG,CACX,GAAG,EACH,IAAA,yBAAK,EAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,8CAA2B,EAAE,CAAC,EAC5G,IAAA,yBAAK,EAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,uCAAoB,EAAE,CAAC,CAAC,KAAK,EAAE,EAC9E,wBAAW,EACX,IAAI,CAAC,qBAAqB,CAAC,aAAa,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,0BAA0B,CAAC,EAC5F,IAAI,CAAC,UAAU,CAAC,MAAM,CACzB,CAAC;QAEF,IAAI,CAAC,MAAM,CAAC,GAAG,CACX,OAAO,EACP,IAAA,yBAAK,EAAC,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EACvD,IAAA,yBAAK,EAAC,QAAQ,CAAC,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,mDAA8B,EAAE,CAAC,CAAC,KAAK,EAAE,EACzF,wBAAW,EACX,IAAI,CAAC,qBAAqB,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,oBAAoB,CAAC,EAChF,IAAI,CAAC,UAAU,CAAC,MAAM,CACzB,CAAC;IACN,CAAC;IAED,wHAAwH;IAChH,MAAM,CAAC,WAAW,CAAC,KAAa;QACpC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC7B,OAAO,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC;IAC7E,CAAC;CACJ,CAAA;AA5CY,oDAAoB;+BAApB,oBAAoB;IADhC,IAAA,qBAAU,GAAE;IAUI,WAAA,IAAA,iBAAM,EAAC,qBAAS,CAAC,YAAY,CAAC,CAAA;;GATlC,oBAAoB,CA4ChC"}

package/docs/implementation_documentation.md

@@ -718,7 +718,7 @@ Task přegeneruje materializovaný pohled `mv_enapo_om_consumption`, ze kterého
         -   prod `0 45 3 * * *`
         -   samotná definice cronu je vedena mimo tento repozitář (deployment konfigurace)
 -   spouštění na základě událostí
-    -   žádné, a to záměrně: [EnapoPpasTask](#task-enapoppastask) stahuje po pětidenních intervalech a spouštěl by desítky refreshů za jeden běh, přičemž endpoint stejně garantuje svěžest jen na 6 hodin (cache hlavičky)
+    -   žádné, a to záměrně: [EnapoPpasTask](#task-enapoppastask) stahuje po pětidenních intervalech a spouštěl by desítky refreshů za jeden běh, přičemž endpoint stejně garantuje svěžest jen na dobu cache (hlavička `s-maxage`, výchozích 6 hodin; per env ji nastavuje proměnná `ENERGETICS_DED_BUILDING_CACHE_MAX_AGE` v sekundách, na OG se předává přes `extraEnvVars` v infrastruktuře, neplatná hodnota zachová výchozí). Jde o sdílenou cache (CDN), takže ji z prohlížeče obejít nejde
 -   data modely
     -   [EnapoConsumptionHistoryIndexRepository](../src/integration-engine/enapo/repositories/EnapoConsumptionHistoryIndexRepository.ts) — `REFRESH MATERIALIZED VIEW CONCURRENTLY energetics.mv_enapo_om_consumption`, kontrakt [IEnapoConsumptionHistoryIndexRepository](../src/integration-engine/enapo/repositories/interfaces/IEnapoConsumptionHistoryIndexRepository.ts)
 -   funkce
@@ -808,6 +808,7 @@ Další ověřené vlastnosti dat, na které agregace spoléhá:
         -   `ZSCBM3` (M3, 49 EIC) — nese 92 % objemu `ZIZWC` z devítiny jeho EIC; vyloučeno jako bezpečnější strana otevřené otázky (chybějící řada se vrací jako `null`, zdvojené číslo by se tvářilo jako platné)
     -   sloupec `consumption` je denominovaný podle `unit` (M3 / NM3 / KWH), **není to vždy m³**
     -   `combustion_heat` a `volume_coefficient` s hodnotou 0 znamenají „nedodáno“, ne nulu — bez `NULLIF` by se z odvozených kWh stala nula, která se na grafu kreslí jako skutečný odečet
+    -   měsíc **bez spotřeby** PPAS fakturuje s prázdným `consumption` a nulovými `normometers_nm3` i `gas_consumption_kwh` (explicitní `consumption = 0` se v datech nevyskytuje; ověřeno 2026-10-19, ~5 600 takových řádků). `mv_enapo_om_consumption` takový řádek bere jako 0 m³ a 0 kWh — nulová spotřeba je 0 kWh bez ohledu na přepočet, takže tu `NULLIF` neplatí. Řádek bez `consumption` i bez Nm³/kWh (všechno `NULL`) nic neříká a zůstává chybějícím údajem
     -   existují **duplicitní faktury bez vazby přes `preceding_id`** nesoucí bajtově shodné řádky pro totéž EIC a období; deduplikace proto musí jít podle obsahu řádku `(eic, place_id, device_serial_number, date_from, date_to, kind, reading_type, unit)`, nikoli podle návaznosti faktur
     -   `mv_enapo_om_consumption` zatím bere jen `reading_type = 'STANDARD'`. Protože CORRECTION je storno (viz výše, negativní consumptionKwh), znamená to, že se storna neodečítají a spotřeba je **nadhodnocená o ~0,68 %**. Vědomé zjednodušení první verze: znaménko nese pouze `gas_consumption_kwh`, `consumption` zůstává pozitivní, takže naivní součet by v jednom sloupci odečítal a ve druhém přičítal
 -   formát dat

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@golemio/energetics",
-    "version": "2.0.0-dev.2954231424",
+    "version": "2.0.0-dev.2962537365",
     "description": "Golemio Energetics Module",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",