@things-factory/headless-twin 10.0.17 → 10.0.18

package/dist-server/engine/kpi-fold.d.ts

@@ -1,4 +1,5 @@
-import { type ElectricityCost, type TariffDeclaration, type WorkCalendarEntry } from '@operato/twin-kernel';
+import { type ElectricityCost, type TariffDeclaration } from '@operato/twin-kernel';
+import { type WorkCalendarEntry } from '@operato/ops-contract';
 /** 저널 한 줄 — 필요한 것만(엔티티·typeorm 비의존). */
 export interface KpiEvent {
     eventType?: string;
@@ -124,6 +125,51 @@ export interface KpiResult {
                 id: string;
                 kWh: number;
             }[];
+            /**
+             * **이 창에 다 들어오지 않아 더하지 못한 기간** — 조용히 버리지 않는다.
+             *
+             * 더하는 것은 창에 온전히 든 기간뿐이다(걸친 기간을 더하면 다른 날 값이 이 창의 값인 척한다).
+             * 그런데 하루 단위 기간은 「지금부터 24시간 전」 창에 온전히 드는 일이 거의 없다 — 창이 한낮에서
+             * 시작하기 때문이다. 그래서 어제 발전량이 저널에 멀쩡히 있는데 화면이 비었고, 사용자는 그것을
+             * 「발전량이 없다」로 읽었다(2026-08-30 실측).
+             *
+             * 이 값이 있으면 화면은 **「이 구간에 다 들어오지 않은 기간이 있다」**를 말해야 한다.
+             */
+            notCounted?: {
+                periods: number;
+                kWh: number;
+                earliestStart: string;
+                latestEnd: string;
+            };
+            /**
+             * 이용률 — 만든 양 ÷ (정격 × 그 기간의 시간).
+             *
+             * **어느 정격으로 나눴는지를 함께 낸다.** 변환기를 낀 발전은 직류 정격이 교류보다 크고,
+             * 직류로 나눠 보여 주는 시스템이 실제로 있다. 밝히지 않으면 두 화면의 수가 두 배 달라도
+             * 왜 다른지 말할 수 없다.
+             *
+             * 창 전체가 아니라 **센 기간들의 길이**로 나눈다 — 하루치 하나만 센 24시간 창에서 창 길이로
+             * 나누면 그 하루가 창 전체에 걸쳐 있었던 것처럼 작아진다.
+             */
+            capacityFactor?: {
+                value: number;
+                ratedKW: number;
+                basis: 'ac' | 'dc';
+                from: 'equipment' | 'location';
+                hours: number;
+            };
+            /**
+             * 낸 것의 값 — 기간마다 그때의 단가로 매긴다.
+             *
+             * **모든 기간에 단가가 있을 때만** 금액을 만든다. 일부만 매기고 더하면 그 합이 창 전체의 값인
+             * 척한다 — 못 매긴 기간 수를 함께 낸다.
+             */
+            revenue?: {
+                amount: number;
+                currency: string;
+                priced: number;
+                unpriced: number;
+            };
         };
         /**
          * `kWh` 가 어느 회계에서 왔나.
@@ -148,9 +194,22 @@ export interface KpiResult {
          */
         billingDemand?: {
             kW: number;
-            from: 'bill' | 'carried-forward' | 'declaration';
+            from: 'tariff-basis' | 'bill' | 'carried-forward' | 'declaration';
             declaredKW?: number;
             stale?: boolean;
+            /**
+             * 이 창에서 관측한 최고 수요가 그 기준을 넘었다 — **다음 주기의 기본요금이 오른다.**
+             *
+             * 계약 초과와 다른 값이다. 계약 초과는 지금 줄이면 되고, 이것은 이미 정해진 결과다.
+             *
+             * `observedTo` 는 이 최고값이 언제까지의 것인지다. 최고 수요는 구간이 마감되어야 오므로
+             * 넘은 것을 뒤늦게 안다 — 그 한계를 화면이 말할 수 있어야 한다.
+             */
+            exceeded?: {
+                peakKW: number;
+                overKW: number;
+                observedTo: string;
+            };
         };
         /**
          * 밖에서 마감되어 온 사용 구간 — 계량 표본이 없는 현장의 유일한 근거다.
@@ -348,7 +407,6 @@ export interface KpiResult {
         truncatedTasks?: number;
     };
 }
-/** 폴드 옵션 — 관점 축과, 그 축을 만들기 위해 이벤트 밖에서 와야 하는 지도. */
 export interface KpiFoldOptions {
     groupBy?: KpiGroupBy;
     /**
@@ -361,6 +419,36 @@ export interface KpiFoldOptions {
         to: string;
         billingDemandKW?: number;
     };
+    /**
+     * 이 트윈이 이어받고 있는 **요금 기준** — 이 주기에 적용되는 값(§`ENERGY_EVENT.tariffBasis`).
+     *
+     * 청구서보다 먼저다. 청구서는 끝난 기간의 정산이라 이번 주기의 기준을 말하지 않는다.
+     */
+    tariffBasis?: {
+        from: string;
+        billingDemandKW?: number;
+    };
+    /**
+     * 이 트윈의 **발전 정격**과 그 근거 — 이용률의 분모(§ 커널 `generationRated`).
+     *
+     * 모델의 선언에서 오므로 호출부가 읽어 넘긴다. 폴드는 저널만 본다.
+     */
+    generationRated?: {
+        kW: number;
+        basis: 'ac' | 'dc';
+        from: 'equipment' | 'location';
+    };
+    /**
+     * 이 트윈이 이어받고 있는 **발전 단가** — 창 밖의 단가도 이 창에 적용될 수 있다.
+     *
+     * 창 안의 단가 사실이 먼저다. 이것은 그 창에 단가가 없을 때 쓴다.
+     */
+    generationPrice?: {
+        from: string;
+        to: string;
+        unitPrice: number;
+        currency: string;
+    };
     /**
      * 노드 → 구역 지도. **이벤트에는 구역이 없다**(노드까지만 있다) — 스냅샷·마스터가 아는 값이라
      * 호출부가 넘긴다. 없으면 구역 축은 'unknown' 으로 모인다(알리지 않고 다른 축으로 바꾸지 않는다).

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

@@ -32,6 +32,7 @@ exports.foldKpiBuckets = foldKpiBuckets;
  * 이 파일은 이제 "계산한 기록 → 창 지표" 만 한다.
  */
 const twin_kernel_1 = require("@operato/twin-kernel");
+const ops_contract_1 = require("@operato/ops-contract");
 /**
  * 창의 전력량을 **배전 계통의 자리별로 나눈다** — 근거를 함께.
  *
@@ -144,10 +145,37 @@ function feederShares(kWh, utilization, resourceFeeder) {
  * 기간의 끝이 자정인데 마지막 표본이 저녁이었으면 그 사이는 재지 않은 것이다. 그 수를 함께 내야 화면이
  * 「이 합은 이만큼 덜 잰 것」이라고 말할 수 있다. 얼마나 어긋나면 문제인지는 현장이 정한다.
  */
-function generatedOfPeriods(periods, range) {
+function generatedOfPeriods(periods, range, 
+/** 이용률의 분모 — 없으면 이용률을 내지 않는다(0 이나 짐작을 만들지 않는다). */
+rated, 
+/** 기간마다 적용할 단가 — 기간을 덮는 것을 쓴다. 없으면 금액을 만들지 않는다. */
+prices) {
     const inside = periods.filter(g => g.startMs >= range.startMs && g.endMs <= range.endMs);
-    if (!inside.length)
-        return {};
+    /*
+     * ── **걸친 기간을 조용히 버리지 않는다** (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) {
@@ -157,14 +185,46 @@ function generatedOfPeriods(periods, range) {
         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: inside.reduce((a, g) => a + g.kWh, 0),
+            kWh,
             counted: inside.length,
             partial,
             byEquipment: [...byEquipment.entries()]
                 .map(([id, kWh]) => ({ id, kWh }))
-                .sort((a, b) => b.kWh - a.kWh)
+                .sort((a, b) => b.kWh - a.kWh),
+            ...(capacityFactor ? { capacityFactor } : {}),
+            ...(revenue ? { revenue } : {}),
+            /* 이 창에 다 들어오지 않아 더하지 못한 기간 — 있으면 화면이 그것을 말한다. */
+            ...(notCounted ? { notCounted } : {})
         }
     };
 }
@@ -211,26 +271,40 @@ function usageOfPeriods(periods, range) {
  * 순서에 뜻이 있다. 청구서는 그 기간에 실제로 매겨진 값이고, 선언은 사람이 옮겨 적은 값이다.
  * 그 값이 매달 바뀌므로 옮겨 적은 것은 곧 낡는다.
  */
-function billingDemandOf(billsInWindow, lastBill, declaredKW) {
+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 picked = fromBill !== undefined
-        ? { kW: fromBill, from: 'bill' }
-        : carried !== undefined
-            ? { kW: carried, from: 'carried-forward' }
-            : declared !== undefined
-                ? { kW: declared, from: 'declaration' }
-                : 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 } : {})
+        ...(stale ? { stale: true } : {}),
+        ...(exceeded ? { exceeded } : {})
     };
 }
 /**
@@ -339,6 +413,28 @@ function measuredFeeders(windows, range, totalKWh, meterFeeder) {
         ...(remainder < 0 ? { submeterExcessKWh: -remainder } : {})
     };
 }
+/** 폴드 옵션 — 관점 축과, 그 축을 만들기 위해 이벤트 밖에서 와야 하는 지도. */
+/*
+ * ── 같은 사실이 두 벌 있어도 한 번만 센다 (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;
@@ -370,7 +466,7 @@ function facetKey(rec, options) {
                 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';
     }
@@ -507,7 +603,7 @@ 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) {
                 /*
                  * **오더당 한 번만 센다.** 폴링하는 원본은 같은 오더의 종결을 여러 주기에 걸쳐 다시 보낼 수
@@ -540,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`)도 함께 넘긴다 — 요금이 걸리는 수는 평균이 아니라 최대다.
@@ -569,8 +665,7 @@ function foldKpi(events, window, options = {}) {
      *
      * 관측 구간(`observedFrom`·`observedTo`)을 함께 읽는다 — 값의 근거가 얼마나 덮였는지가 그 둘에 있다.
      */
-    const generationPeriods = events
-        .filter(e => e.eventType === twin_kernel_1.ENERGY_EVENT.generationPeriod)
+    const generationPeriods = onceById(events.filter(e => e.eventType === ops_contract_1.ENERGY_EVENT.generationPeriod))
         .map(e => {
         const d = e.payload?.data ?? e.payload ?? {};
         return {
@@ -586,8 +681,7 @@ function foldKpi(events, window, options = {}) {
     /*
      * 밖에서 마감되어 온 사용 구간 — 구간 마감과 같은 규칙으로 **창에 온전히 든 것만** 센다.
      */
-    const usagePeriods = events
-        .filter(e => e.eventType === twin_kernel_1.ENERGY_EVENT.usagePeriod)
+    const usagePeriods = onceById(events.filter(e => e.eventType === ops_contract_1.ENERGY_EVENT.usagePeriod))
         .map(e => {
         const d = e.payload?.data ?? e.payload ?? {};
         return {
@@ -596,14 +690,14 @@ function foldKpi(events, window, options = {}) {
             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 = events
-        .filter(e => e.eventType === twin_kernel_1.ENERGY_EVENT.bill)
+    const bills = onceById(events.filter(e => e.eventType === ops_contract_1.ENERGY_EVENT.bill))
         .map(e => {
         const d = e.payload?.data ?? e.payload ?? {};
         return {
@@ -619,6 +713,18 @@ function foldKpi(events, window, options = {}) {
         };
     })
         .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 = [];
@@ -686,7 +792,12 @@ function foldKpi(events, window, options = {}) {
                  * 다른 단가가 사라지고, 「피크를 깎아 얼마를 아끼나」가 그 차이 위에 선다.
                  */
                 /* 요금적용전력은 청구서가 먼저다 — 선언은 청구가 오지 않는 현장의 몫이다. */
-                const billingDemand = billingDemandOf(bills.filter(b => Number.isFinite(b.billingDemandKW)).map(b => ({ endMs: b.endMs, billingDemandKW: b.billingDemandKW })), options.lastBill, options.tariff?.billingDemandKW);
+                /* 이 창의 최고 수요 — 사용 구간이 실어 온 값 중 가장 큰 것(원본 계량기가 잰 값이다). */
+                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,
@@ -717,7 +828,20 @@ function foldKpi(events, window, options = {}) {
                             feederShares(e.kWh, utilization, options.resourceFeeder)),
                         /* 금액은 같은 창의 전력량·최대수요에서 나온다 — 창이 하나뿐이라 어긋날 수 없다. */
                         ...(cost ? { cost } : {}),
-                        ...generatedOfPeriods(generationPeriods, { startMs: window.fromMs, endMs: window.toMs }),
+                        ...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);