@things-factory/headless-twin 10.0.15 → 10.0.18

package/dist-server/engine/kpi-fold.js

@@ -1,6 +1,6 @@
 "use strict";
 /*
- * 업무 KPI 폴드 — **이벤트 저널을 접어** 시간창 지표를 만든다(순수).
+ * 업무 KPI 폴드 — **이벤트 저널을 계산해** 시간창 지표를 만든다(순수).
  *
  * ── 왜 필요한가 ─────────────────────────────────────────────────────────────
  * 지금 트윈이 답할 수 있는 것은 "이 순간의 값"(점유 92%)과 "인프라 부하"(초당 이벤트 수)뿐이다.
@@ -9,8 +9,8 @@
  *
  * ── 원료는 이미 있다 ────────────────────────────────────────────────────────
  * 저널(`TwinEvent`)에 `task.status`·`order.status`·`equipment.status` 전이가 `eventTime`(ISO)과 함께
- * append-only 로 쌓인다. 그래서 새 계측을 심을 필요가 없다 — **접기만 하면 된다.**
- * 같은 모양의 선례가 이 폴더에 있다(`oee-accumulator.ts` — equipment 전이를 접어 OEE 카운터 생산).
+ * append-only 로 쌓인다. 그래서 새 계측을 심을 필요가 없다 — **계산만 하면 된다.**
+ * 같은 모양의 선례가 이 폴더에 있다(`oee-accumulator.ts` — equipment 전이를 계산해 OEE 카운터 생산).
  *
  * ── 이 파일이 하지 않는 것 ──────────────────────────────────────────────────
  * · 목표와 비교하지 않는다. "95% 목표 대비" 는 목표를 저장하는 별개 층(경영 KPI)의 몫이고,
@@ -29,9 +29,10 @@ exports.foldKpiBuckets = foldKpiBuckets;
  * 짝맞춤은 **커널이 소유한다**(`foldTaskRecords`). 완료는 작업당 하나·나중 것이 사실, 착수는 처음 것,
  * 종류·오더는 어느 전이에서든 — 그 규칙은 커널 상태 기계에서 나오는 지식이다. 여기서 다시 적었더니
  * 공정 타임라인과 **다른 답**을 냈다(재전송된 완료를 두 건으로 세어 처리량·점유가 부풀려졌다).
- * 이 파일은 이제 "접힌 기록 → 창 지표" 만 한다.
+ * 이 파일은 이제 "계산한 기록 → 창 지표" 만 한다.
  */
 const twin_kernel_1 = require("@operato/twin-kernel");
+const ops_contract_1 = require("@operato/ops-contract");
 /**
  * 창의 전력량을 **배전 계통의 자리별로 나눈다** — 근거를 함께.
  *
@@ -128,6 +129,221 @@ function feederShares(kWh, utilization, resourceFeeder) {
  * 분기 계량 합이 뿌리보다 크면(회계가 다른 두 계량기) **그 사실을 낸다** — 값을 깎아 맞추면 계량을
  * 우리가 고쳐 쓰는 것이다.
  */
+/**
+ * 창의 **발전량** — 커널이 마감한 기간 사실을 합한다.
+ *
+ * ── 왜 합이 전부인가 ───────────────────────────────────────────────────────
+ * 기간 발전량은 커널이 이미 확정한 사실이다(적산의 종류마다 다른 규칙으로 얻는다). 여기서 다시
+ * 계산하면 규칙이 두 벌이 되고, 그때부터 두 화면이 다른 발전량을 말한다. 이 함수가 하는 일은
+ * **창에 든 것을 고르고, 설비별로 묶고, 근거가 얼마나 덮였는지 세는 것**이다.
+ *
+ * ── 걸친 기간은 세지 않는다 ─────────────────────────────────────────────────
+ * 구간 마감과 같은 규칙이다. 하루의 절반이 창에 들었다고 절반을 세면 그것은 관측이 아니라 우리가 나눈
+ * 값이고, 합이 창을 넘는다.
+ *
+ * ── 덜 덮인 기간을 센다 ─────────────────────────────────────────────────────
+ * 기간의 끝이 자정인데 마지막 표본이 저녁이었으면 그 사이는 재지 않은 것이다. 그 수를 함께 내야 화면이
+ * 「이 합은 이만큼 덜 잰 것」이라고 말할 수 있다. 얼마나 어긋나면 문제인지는 현장이 정한다.
+ */
+function generatedOfPeriods(periods, range, 
+/** 이용률의 분모 — 없으면 이용률을 내지 않는다(0 이나 짐작을 만들지 않는다). */
+rated, 
+/** 기간마다 적용할 단가 — 기간을 덮는 것을 쓴다. 없으면 금액을 만들지 않는다. */
+prices) {
+    const inside = periods.filter(g => g.startMs >= range.startMs && g.endMs <= range.endMs);
+    /*
+     * ── **걸친 기간을 조용히 버리지 않는다** (2026-08-30) ──────────────────────
+     *
+     * 더하는 것은 창에 **온전히 들어온 기간**뿐이다. 그것이 맞는 셈이다 — 걸친 기간을 더하면 다른 날의
+     * 값이 이 창의 값인 척한다.
+     *
+     * 그런데 버린 것을 말하지 않았다. 하루 단위 기간은 「지금부터 24시간 전」 창에 온전히 들어오는 일이
+     * 거의 없다(창이 한낮에서 시작하므로). 그래서 어제 발전량이 저널에 멀쩡히 있는데 화면이 비었고,
+     * 사용자는 그것을 **「발전량이 없다」**로 읽었다. 실측으로 그 일이 났다.
+     *
+     * 이제 걸친 것을 세어 함께 낸다. 화면이 「이 창에 다 들어오지 않은 기간이 있다」를 말할 수 있다.
+     */
+    const straddling = periods.filter(g => !(g.startMs >= range.startMs && g.endMs <= range.endMs) && g.endMs > range.startMs && g.startMs < range.endMs);
+    const notCounted = straddling.length
+        ? {
+            periods: straddling.length,
+            kWh: straddling.reduce((a, g) => a + g.kWh, 0),
+            earliestStart: new Date(Math.min(...straddling.map(g => g.startMs))).toISOString(),
+            latestEnd: new Date(Math.max(...straddling.map(g => g.endMs))).toISOString()
+        }
+        : undefined;
+    if (!inside.length) {
+        /* 온전히 들어온 것이 없다 — 그래도 걸친 것이 있으면 그 사실을 낸다(빈 값과 「없음」은 다르다). */
+        return notCounted ? { generated: { kWh: 0, counted: 0, partial: 0, byEquipment: [], notCounted } } : {};
+    }
+    const byEquipment = new Map();
+    let partial = 0;
+    for (const g of inside) {
+        byEquipment.set(g.equipmentId, (byEquipment.get(g.equipmentId) ?? 0) + g.kWh);
+        const coveredFrom = Number.isFinite(g.observedFromMs) ? g.observedFromMs <= g.startMs : false;
+        const coveredTo = Number.isFinite(g.observedToMs) ? g.observedToMs >= g.endMs : false;
+        if (!coveredFrom || !coveredTo)
+            partial++;
+    }
+    const kWh = inside.reduce((a, g) => a + g.kWh, 0);
+    /*
+     * 이용률의 분모는 **센 기간들의 길이**다. 창 길이로 나누면, 하루치 하나만 센 24시간 창에서 그 하루가
+     * 창 전체에 걸쳐 있었던 것처럼 작아진다.
+     */
+    const hours = inside.reduce((a, g) => a + (g.endMs - g.startMs) / 3_600_000, 0);
+    const capacityFactor = rated && rated.kW > 0 && hours > 0
+        ? { value: kWh / (rated.kW * hours), ratedKW: rated.kW, basis: rated.basis, from: rated.from, hours }
+        : undefined;
+    /*
+     * 낸 것의 값 — 기간마다 **그 기간을 덮는 단가**로 매긴다. 걸친 단가는 쓰지 않는다: 하루 단가로
+     * 이틀치를 매기면 그 절반은 다른 날의 값이 된다.
+     *
+     * 모든 기간에 단가가 있을 때만 금액을 만든다. 일부만 매기고 더하면 그 합이 창 전체의 값인 척한다.
+     */
+    let amount = 0;
+    let priced = 0;
+    let currency;
+    for (const g of inside) {
+        const p = (prices ?? []).find(x => x.startMs <= g.startMs && x.endMs >= g.endMs);
+        if (!p)
+            continue;
+        amount += g.kWh * p.unitPrice;
+        priced++;
+        currency = currency ?? p.currency;
+    }
+    const unpriced = inside.length - priced;
+    const revenue = priced > 0 && unpriced === 0 && currency ? { amount, currency, priced, unpriced } : undefined;
+    return {
+        generated: {
+            kWh,
+            counted: inside.length,
+            partial,
+            byEquipment: [...byEquipment.entries()]
+                .map(([id, kWh]) => ({ id, kWh }))
+                .sort((a, b) => b.kWh - a.kWh),
+            ...(capacityFactor ? { capacityFactor } : {}),
+            ...(revenue ? { revenue } : {}),
+            /* 이 창에 다 들어오지 않아 더하지 못한 기간 — 있으면 화면이 그것을 말한다. */
+            ...(notCounted ? { notCounted } : {})
+        }
+    };
+}
+/**
+ * 밖에서 마감되어 온 사용 구간을 합한다 — **구간 마감과 더하지 않는다.**
+ *
+ * 두 회계가 같은 전기를 말한다. 더하면 두 번 세고, 둘 다 있는 현장에서는 계량 쪽이 강한 근거이므로
+ * 그쪽을 쓴다. 여기서는 이쪽 몫만 계산하고, 무엇을 쓸지는 부르는 쪽이 정한다.
+ *
+ * 단가는 **모든 구간이 실었을 때만** 요금을 만든다. 일부만 실었는데 있는 것만 더하면 그 합이 창의
+ * 요금인 척한다 — 못 매긴 구간 수를 함께 낸다.
+ */
+function usageOfPeriods(periods, range) {
+    const inside = periods.filter(u => u.startMs >= range.startMs && u.endMs <= range.endMs);
+    if (!inside.length)
+        return undefined;
+    const byBasis = new Map();
+    let kWh = 0;
+    let charge = 0;
+    let unpriced = 0;
+    let currency;
+    for (const u of inside) {
+        kWh += u.kWh;
+        byBasis.set(u.basis, (byBasis.get(u.basis) ?? 0) + 1);
+        if (Number.isFinite(u.unitPrice)) {
+            charge += u.kWh * u.unitPrice;
+            if (!currency)
+                currency = u.currency;
+        }
+        else
+            unpriced++;
+    }
+    return {
+        kWh,
+        counted: inside.length,
+        ...(unpriced === 0 && currency ? { charge, currency } : {}),
+        unpriced,
+        byBasis: [...byBasis.entries()].map(([basis, counted]) => ({ basis, counted })).sort((a, b) => b.counted - a.counted)
+    };
+}
+/**
+ * **요금적용전력을 고른다 — 청구서가 먼저다.**
+ *
+ * 순서에 뜻이 있다. 청구서는 그 기간에 실제로 매겨진 값이고, 선언은 사람이 옮겨 적은 값이다.
+ * 그 값이 매달 바뀌므로 옮겨 적은 것은 곧 낡는다.
+ */
+function billingDemandOf(billsInWindow, tariffBasis, lastBill, declaredKW, 
+/** 이 창에서 관측한 최고 수요와 그 값이 언제까지의 것인지 — 사용 구간의 `maxKW` 에서 온다. */
+observedPeak) {
+    const declared = Number.isFinite(Number(declaredKW)) ? Number(declaredKW) : undefined;
+    const withValue = billsInWindow.filter(b => Number.isFinite(b.billingDemandKW));
+    const fromBill = withValue.length ? withValue.reduce((a, x) => (x.endMs > a.endMs ? x : a)).billingDemandKW : undefined;
+    const carried = Number.isFinite(Number(lastBill?.billingDemandKW)) ? Number(lastBill?.billingDemandKW) : undefined;
+    /* 이 주기에 적용되는 기준이 가장 먼저다 — 청구서는 끝난 기간의 것이다. */
+    const fromBasis = Number.isFinite(Number(tariffBasis?.billingDemandKW)) ? Number(tariffBasis?.billingDemandKW) : undefined;
+    const picked = fromBasis !== undefined
+        ? { kW: fromBasis, from: 'tariff-basis' }
+        : fromBill !== undefined
+            ? { kW: fromBill, from: 'bill' }
+            : carried !== undefined
+                ? { kW: carried, from: 'carried-forward' }
+                : declared !== undefined
+                    ? { kW: declared, from: 'declaration' }
+                    : undefined;
+    if (!picked)
+        return undefined;
+    /* 선언이 있는데 청구서와 다르면 그 사실을 낸다 — 낡은 선언은 스스로 말해야 한다. */
+    const stale = picked.from !== 'declaration' && declared !== undefined && declared !== picked.kW;
+    const exceeded = observedPeak && observedPeak.kW > picked.kW
+        ? {
+            peakKW: observedPeak.kW,
+            overKW: observedPeak.kW - picked.kW,
+            observedTo: new Date(observedPeak.toMs).toISOString()
+        }
+        : undefined;
+    return {
+        ...picked,
+        ...(declared !== undefined ? { declaredKW: declared } : {}),
+        ...(stale ? { stale: true } : {}),
+        ...(exceeded ? { exceeded } : {})
+    };
+}
+/**
+ * 창에 온전히 든 청구서 하나 — 가장 늦게 끝난 것.
+ *
+ * **창이 청구 주기와 같을 때만 견준다.** 한 달 청구서를 하루 창의 값과 빼면 그 차이는 아무것도 뜻하지
+ * 않는다. 그래서 같은지를 값과 함께 낸다.
+ */
+function billOfWindow(bills, range, ours) {
+    const inside = bills.filter(b => b.startMs >= range.startMs && b.endMs <= range.endMs);
+    if (!inside.length)
+        return undefined;
+    const b = inside.reduce((a, x) => (x.endMs > a.endMs ? x : a));
+    const matchesWindow = b.startMs === range.startMs && b.endMs === range.endMs;
+    /* 양쪽에 있는 항목만 견준다 — 한쪽이 없는 것을 0 으로 두면 그 차이가 통째로 어긋남처럼 보인다. */
+    const gap = (mine, billed) => Number.isFinite(Number(mine)) && Number.isFinite(billed) ? Number(mine) - billed : undefined;
+    const diff = matchesWindow
+        ? {
+            ...(gap(ours?.total, b.total) !== undefined ? { total: gap(ours?.total, b.total) } : {}),
+            ...(gap(ours?.demandCharge, b.demandCharge) !== undefined
+                ? { demandCharge: gap(ours?.demandCharge, b.demandCharge) }
+                : {}),
+            ...(gap(ours?.energyCharge, b.energyCharge) !== undefined
+                ? { energyCharge: gap(ours?.energyCharge, b.energyCharge) }
+                : {})
+        }
+        : {};
+    return {
+        from: b.from,
+        to: b.to,
+        ...(Number.isFinite(b.total) ? { total: b.total } : {}),
+        ...(Number.isFinite(b.energyCharge) ? { energyCharge: b.energyCharge } : {}),
+        ...(Number.isFinite(b.demandCharge) ? { demandCharge: b.demandCharge } : {}),
+        ...(b.currency ? { currency: b.currency } : {}),
+        ...(Number.isFinite(b.billingDemandKW) ? { billingDemandKW: b.billingDemandKW } : {}),
+        matchesWindow,
+        ...(Object.keys(diff).length ? { diff } : {})
+    };
+}
 function measuredFeeders(windows, range, totalKWh, meterFeeder) {
     if (!meterFeeder || !Object.keys(meterFeeder).length)
         return undefined;
@@ -197,7 +413,29 @@ function measuredFeeders(windows, range, totalKWh, meterFeeder) {
         ...(remainder < 0 ? { submeterExcessKWh: -remainder } : {})
     };
 }
-/** 이 기록이 요청한 축에서 어느 값에 속하는가. 값이 없으면 'unknown'(조용히 버리지 않는다). */
+/** 폴드 옵션 — 관점 축과, 그 축을 만들기 위해 이벤트 밖에서 와야 하는 지도. */
+/*
+ * ── 같은 사실이 두 벌 있어도 한 번만 센다 (2026-08-30) ──────────────────────
+ *
+ * 마감된 구간 사실은 정체성이 내용에 있다(커널 0.7.81). 그런데 저널에 이미 여러 벌 적힌 것이 있다 —
+ * 쓰는 자리에서 막기 전에 들어간 것들이다(실측: 어느 날의 발전 단가가 세 벌).
+ *
+ * 지난 기록을 지우지 않는다 — 저널은 일어난 일의 기록이다. 대신 **읽을 때 한 번만 센다.**
+ * 그러지 않으면 그 구간의 수익·사용량이 그 횟수만큼 세어진다.
+ */
+function onceById(rows) {
+    const seen = new Set();
+    return rows.filter(r => {
+        const id = r?.payload?.eventId;
+        if (typeof id !== 'string' || !id)
+            return true;
+        if (seen.has(id))
+            return false;
+        seen.add(id);
+        return true;
+    });
+}
+/** 이 기록이 요청한 축에서 어느 값에 속하는가. 값이 없으면 'unknown'(알리지 않고 버리지 않는다). */
 function facetKey(rec, options) {
     const f = rec.facets;
     switch (options.groupBy) {
@@ -227,8 +465,8 @@ function facetKey(rec, options) {
             if (!options.shifts?.length)
                 return 'unknown';
             /* 시각까지 넘긴다 — **휴일에 일어난 일은 어느 교대에도 속하지 않는다.** 되풀이만 보면 그날 서지도
-               않은 교대에 집계돼, 교대별 성과가 조용히 거짓이 된다. */
-            return (0, twin_kernel_1.activeShiftAt)(options.shifts, rec.at, options.utcOffsetMinutes) ?? 'unknown';
+               않은 교대에 집계돼, 교대별 성과가 알리지 않고 거짓이 된다. */
+            return (0, ops_contract_1.activeShiftAt)(options.shifts, rec.at, options.utcOffsetMinutes) ?? 'unknown';
         default:
             return 'unknown';
     }
@@ -256,7 +494,7 @@ function qualityOf(rows) {
  * 기록을 축으로 묶어 축별 통계를 낸다 — **전체와 같은 규칙**으로(같은 stats 함수, 같은 창).
  *
  * 축의 값이 아주 많을 수 있다(오더 축은 수천 개). 그래서 건수 큰 것부터 상한까지만 돌려주고
- * **잘라낸 수를 함께 알린다** — 조용한 절단은 "이게 전부" 라는 거짓을 만든다.
+ * **잘라낸 수를 함께 알린다** — 들어온 것이 없는 절단은 "이게 전부" 라는 거짓을 만든다.
  */
 function groupRecords(records, options) {
     const by = options.groupBy;
@@ -320,11 +558,11 @@ function stats(values) {
     };
 }
 /**
- * 이벤트를 접어 시간창 KPI 를 만든다.
+ * 이벤트를 계산해 시간창 KPI 를 만든다.
  *
  * **호출부 규약**: `events` 는 창보다 **넉넉히 앞까지** 담아 넘긴다(예: 창 시작 − 리드타임 상한).
  * 완료된 작업의 시작 이벤트가 창 밖에 있을 수 있기 때문이다. 못 찾은 것은 `unpaired` 로 알린다 —
- * 평균에서 조용히 빠지면 지표가 거짓이 된다.
+ * 평균에서 오류 없이 빠지면 지표가 거짓이 된다.
  *
  * 시간축은 `eventTime`(ISO) 차분이다. sim 클록이 실제 시각과 오프셋이 있어도 **차분은 정확**하다
  * (고정 오프셋은 상쇄된다). 파싱 불가한 줄은 버린다.
@@ -352,7 +590,7 @@ function foldKpi(events, window, options = {}) {
              * **끝났나는 커널이 답한다** (2026-08-23) — `isOrderTerminal`.
              *
              * 예전에는 여기서 **동의어 목록**으로 추론했다(`completed`·`fulfilled`·`done`·`finished`).
-             * 그 방식이 낸 대가가 둘이었고 둘 다 조용했다.
+             * 그 방식이 낸 대가가 둘이었고 둘 다 들어온 것이 없었다.
              *
              *  ① 원본의 낱말이 목록에 없으면 완료가 0 이 된다. 실제로 그랬다 — 첫 실 시스템의 `FINISHED`
              *     가 빠져 있었고, 그때 목록에 낱말을 더한 것은 진짜 빈 자리(그 커넥터가 자기 상태 표를
@@ -365,11 +603,11 @@ function foldKpi(events, window, options = {}) {
              * 판정의 1차 근거는 **양**이고 낱말은 양으로 말할 수 없는 종결(취소·중도 종료)에만 쓴다.
              */
             const status = String(d.status ?? '').toLowerCase();
-            const done = (0, twin_kernel_1.isOrderTerminal)({ status: d.status, requested: d.requested, fulfilled: d.fulfilled });
+            const done = (0, ops_contract_1.isOrderTerminal)({ status: d.status, requested: d.requested, fulfilled: d.fulfilled });
             if (at >= window.fromMs && at <= window.toMs) {
                 /*
                  * **오더당 한 번만 센다.** 폴링하는 원본은 같은 오더의 종결을 여러 주기에 걸쳐 다시 보낼 수
-                 * 있고(그것은 결함이 아니라 폴링의 성질이다), 사건마다 세면 처리량이 조용히 부풀려진다.
+                 * 있고(그것은 결함이 아니라 폴링의 성질이다), 사건마다 세면 처리량이 알리지 않고 부풀려진다.
                  * 작업 쪽은 커널의 짝맞춤이 이미 그 규율을 갖고 있다(「완료는 작업당 하나」) — 오더만 없었다.
                  */
                 if (done) {
@@ -379,7 +617,7 @@ function foldKpi(events, window, options = {}) {
                         completedOrders++;
                     }
                     else if (!id)
-                        completedOrders++; // 정체를 모르면 셈에서 빼지 않는다(조용히 줄이지 않는다)
+                        completedOrders++; // 정체를 모르면 셈에서 빼지 않는다(알리지 않고 줄이지 않는다)
                 }
                 /*
                  * **완료로 세지 않은 낱말의 인구조사.** 「못 읽었다」가 아니다 — `picking` 처럼 완료가 아닌
@@ -398,7 +636,7 @@ function foldKpi(events, window, options = {}) {
      * 사건이 하나도 없으면 이 트윈에는 에너지가 없는 것이므로 블록 자체를 내지 않는다.
      */
     const demandWindows = events
-        .filter(e => e.eventType === twin_kernel_1.ENERGY_EVENT.demandWindow)
+        .filter(e => e.eventType === ops_contract_1.ENERGY_EVENT.demandWindow)
         .map(e => {
         const d = e.payload?.data ?? e.payload ?? {};
         /* 최대(`maxKW`)도 함께 넘긴다 — 요금이 걸리는 수는 평균이 아니라 최대다.
@@ -421,6 +659,72 @@ function foldKpi(events, window, options = {}) {
         };
     })
         .filter(w => Number.isFinite(w.startMs) && Number.isFinite(w.endMs));
+    /*
+     * 발전 기간 사실 — 커널이 기간을 마감할 때 낸 것이다. 구간 마감과 같은 규칙으로 **창에 온전히 든
+     * 것만** 센다(걸친 기간을 반만 세면 합이 창을 넘는다).
+     *
+     * 관측 구간(`observedFrom`·`observedTo`)을 함께 읽는다 — 값의 근거가 얼마나 덮였는지가 그 둘에 있다.
+     */
+    const generationPeriods = onceById(events.filter(e => e.eventType === ops_contract_1.ENERGY_EVENT.generationPeriod))
+        .map(e => {
+        const d = e.payload?.data ?? e.payload ?? {};
+        return {
+            equipmentId: String(d.equipmentId ?? ''),
+            kWh: Number(d.kWh),
+            startMs: Date.parse(String(d.periodStart ?? '')),
+            endMs: Date.parse(String(d.periodEnd ?? '')),
+            observedFromMs: Date.parse(String(d.observedFrom ?? '')),
+            observedToMs: Date.parse(String(d.observedTo ?? ''))
+        };
+    })
+        .filter(g => g.equipmentId && Number.isFinite(g.kWh) && Number.isFinite(g.startMs) && Number.isFinite(g.endMs));
+    /*
+     * 밖에서 마감되어 온 사용 구간 — 구간 마감과 같은 규칙으로 **창에 온전히 든 것만** 센다.
+     */
+    const usagePeriods = onceById(events.filter(e => e.eventType === ops_contract_1.ENERGY_EVENT.usagePeriod))
+        .map(e => {
+        const d = e.payload?.data ?? e.payload ?? {};
+        return {
+            meterId: String(d.meterId ?? ''),
+            kWh: Number(d.kWh),
+            startMs: Date.parse(String(d.from ?? '')),
+            endMs: Date.parse(String(d.to ?? '')),
+            unitPrice: Number(d.unitPrice),
+            maxKW: Number(d.maxKW),
+            currency: d.currency ? String(d.currency) : undefined,
+            basis: d.basis ? String(d.basis) : 'unstated'
+        };
+    })
+        .filter(u => u.meterId && Number.isFinite(u.kWh) && Number.isFinite(u.startMs) && Number.isFinite(u.endMs));
+    /* 청구서 — 창에 온전히 든 것 중 가장 늦게 끝난 것 하나. */
+    const bills = onceById(events.filter(e => e.eventType === ops_contract_1.ENERGY_EVENT.bill))
+        .map(e => {
+        const d = e.payload?.data ?? e.payload ?? {};
+        return {
+            from: String(d.from ?? ''),
+            to: String(d.to ?? ''),
+            startMs: Date.parse(String(d.from ?? '')),
+            endMs: Date.parse(String(d.to ?? '')),
+            total: Number(d.total),
+            energyCharge: Number(d.energyCharge),
+            demandCharge: Number(d.demandCharge),
+            currency: d.currency ? String(d.currency) : undefined,
+            billingDemandKW: Number(d.billingDemandKW)
+        };
+    })
+        .filter(b => Number.isFinite(b.startMs) && Number.isFinite(b.endMs));
+    /* 발전 단가 — 기간마다 그때의 값이다(날마다 바뀐다). */
+    const generationPrices = onceById(events.filter(e => e.eventType === ops_contract_1.ENERGY_EVENT.generationPrice))
+        .map(e => {
+        const d = e.payload?.data ?? e.payload ?? {};
+        return {
+            startMs: Date.parse(String(d.from ?? '')),
+            endMs: Date.parse(String(d.to ?? '')),
+            unitPrice: Number(d.unitPrice),
+            currency: String(d.currency ?? '')
+        };
+    })
+        .filter(p => Number.isFinite(p.startMs) && Number.isFinite(p.endMs) && Number.isFinite(p.unitPrice) && p.currency);
     const leads = [];
     const works = [];
     const waits = [];
@@ -466,18 +770,48 @@ function foldKpi(events, window, options = {}) {
     return {
         window: { fromMs: window.fromMs, toMs: window.toMs },
         throughput: { tasks: tasksInWindow, orders: completedOrders },
-        ...(demandWindows.length
+        /* 발전만 있는 현장(계량 없는 발전소)도 답이 나와야 한다 — 둘 중 하나만 있어도 블록을 낸다. */
+        ...(demandWindows.length || generationPeriods.length || usagePeriods.length || bills.length
             ? (() => {
                 const e = (0, twin_kernel_1.energyOfWindows)(demandWindows, { startMs: window.fromMs, endMs: window.toMs });
+                const usage = usageOfPeriods(usagePeriods, { startMs: window.fromMs, endMs: window.toMs });
+                /*
+                 * 어느 회계를 쓸지 정한다 — **더하지 않는다.** 계량 표본에서 우리가 마감한 값이 있으면 그것을
+                 * 쓰고(강한 근거), 없으면 밖에서 마감되어 온 값을 쓴다. 무엇을 썼는지 함께 낸다.
+                 */
+                const usedKWh = e.kWh !== undefined ? e.kWh : usage?.kWh;
+                const kWhBasis = e.kWh !== undefined ? 'demand-window' : usage ? 'usage-period' : undefined;
                 /* 분모는 **완료 오더**다(대당 전력). 창에 완료가 없으면 커널 규칙이 「정의되지 않음」으로 답한다. */
                 const i = (0, twin_kernel_1.energyIntensity)({
-                    kWh: e.kWh,
+                    kWh: usedKWh,
                     energyWindow: e.window,
                     denominator: { kind: 'output', value: completedOrders, window: e.window }
                 });
+                /*
+                 * 요금은 **구간마다 제 단가로** 매긴 값이 있으면 그것을 쓴다. 단일 단가로 접으면 시간대마다
+                 * 다른 단가가 사라지고, 「피크를 깎아 얼마를 아끼나」가 그 차이 위에 선다.
+                 */
+                /* 요금적용전력은 청구서가 먼저다 — 선언은 청구가 오지 않는 현장의 몫이다. */
+                /* 이 창의 최고 수요 — 사용 구간이 실어 온 값 중 가장 큰 것(원본 계량기가 잰 값이다). */
+                const peaks = usagePeriods
+                    .filter(u => u.startMs >= window.fromMs && u.endMs <= window.toMs && Number.isFinite(u.maxKW))
+                    .map(u => ({ kW: u.maxKW, toMs: u.endMs }));
+                const observedPeak = peaks.length ? peaks.reduce((a, x) => (x.kW > a.kW ? x : a)) : undefined;
+                const billingDemand = billingDemandOf(bills.filter(b => Number.isFinite(b.billingDemandKW)).map(b => ({ endMs: b.endMs, billingDemandKW: b.billingDemandKW })), options.tariffBasis, options.lastBill, options.tariff?.billingDemandKW, observedPeak);
+                const cost = options.tariff
+                    ? (0, twin_kernel_1.electricityCost)({
+                        kWh: usedKWh,
+                        peakKW: e.peakKW,
+                        tariff: { ...options.tariff, ...(billingDemand ? { billingDemandKW: billingDemand.kW } : {}) },
+                        ...(usage?.charge !== undefined ? { energyChargeFromPeriods: usage.charge } : {})
+                    })
+                    : undefined;
                 return {
                     energy: {
-                        ...(e.kWh !== undefined ? { kWh: e.kWh } : {}),
+                        ...(usedKWh !== undefined ? { kWh: usedKWh } : {}),
+                        ...(kWhBasis ? { kWhBasis } : {}),
+                        ...(billingDemand ? { billingDemand } : {}),
+                        ...(usage ? { usage } : {}),
                         /* 이 창의 최대수요 — 계약 대비 판정이 보는 수다(전력량과 같은 구간 집합에서 왔다). */
                         ...(e.peakKW !== undefined ? { peakKW: e.peakKW, peakStartMs: e.peakStartMs } : {}),
                         /* 깎인 양은 **같은 구간의 두 수**의 차이다 — 여기서 한 번만 계산해 두 곳이 갈라지지 않게. */
@@ -493,7 +827,26 @@ function foldKpi(events, window, options = {}) {
                         ...(measuredFeeders(demandWindows, { startMs: window.fromMs, endMs: window.toMs }, e.kWh, options.meterFeeder) ??
                             feederShares(e.kWh, utilization, options.resourceFeeder)),
                         /* 금액은 같은 창의 전력량·최대수요에서 나온다 — 창이 하나뿐이라 어긋날 수 없다. */
-                        ...(options.tariff ? { cost: (0, twin_kernel_1.electricityCost)({ kWh: e.kWh, peakKW: e.peakKW, tariff: options.tariff }) } : {})
+                        ...(cost ? { cost } : {}),
+                        ...generatedOfPeriods(generationPeriods, { startMs: window.fromMs, endMs: window.toMs }, options.generationRated, 
+                        /* 창 안의 단가 사실이 먼저이고, 없으면 이어받은 마지막 단가를 쓴다. */
+                        generationPrices.length
+                            ? generationPrices
+                            : options.generationPrice
+                                ? [
+                                    {
+                                        startMs: Date.parse(options.generationPrice.from),
+                                        endMs: Date.parse(options.generationPrice.to),
+                                        unitPrice: options.generationPrice.unitPrice,
+                                        currency: options.generationPrice.currency
+                                    }
+                                ]
+                                : []),
+                        /* 청구서는 사실이다 — 우리 계산을 덮지 않고 나란히 둔다(§`billOfWindow`). */
+                        ...(() => {
+                            const b = billOfWindow(bills, { startMs: window.fromMs, endMs: window.toMs }, cost);
+                            return b ? { bill: b } : {};
+                        })()
                     }
                 };
             })()
@@ -529,7 +882,7 @@ function crossGroups(now, prev) {
 }
 /* ── 시간 비교 ──────────────────────────────────────────────────────────────
  * 숫자 하나로는 좋아졌는지 나빠졌는지 알 수 없다("29초" 가 개선인지 악화인지). 같은 길이의 창을 옮겨
- * 한 번 더 접으면 되므로(폴드는 순수) 값싸다. 창 옮기기와 차이 계산은 계산 규칙이라 여기 있다 —
+ * 한 번 더 계산하면 되므로(폴드는 순수) 값싸다. 창 옮기기와 차이 계산은 계산 규칙이라 여기 있다 —
  * 조회 층에 두면 테스트가 DB 를 끌고 와야 한다.
  */
 /**
@@ -553,7 +906,7 @@ function deltaP50(now, prev) {
     return now.count > 0 && prev.count > 0 ? now.p50Ms - prev.p50Ms : undefined;
 }
 /**
- * 창을 N 등분해 구간별로 접는다 — **같은 이벤트를 창만 바꿔** 다시 접는다(조회 추가 없음).
+ * 창을 N 등분해 구간별로 처리한다 — **같은 이벤트를 창만 바꿔** 다시 계산한다(조회 추가 없음).
  *
  * 마지막 구간은 나머지를 흡수한다(부동소수 나눗셈으로 끝이 밀리면 마지막 완료가 빠진다).
  * `count <= 1` 이면 쪼갤 것이 없으므로 빈 배열 — 호출부가 "추세 없음" 으로 다룬다.