@things-factory/headless-twin 10.0.15 → 10.0.18

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

@@ -1,8 +1,9 @@
-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;
-    /** ISO 시각. 파싱 불가하면 그 줄은 버린다(조용히 0 으로 세지 않는다). */
+    /** ISO 시각. 파싱 불가하면 그 줄은 버린다(알리지 않고 0 으로 세지 않는다). */
     eventTime?: string;
     payload?: any;
 }
@@ -15,7 +16,7 @@ export interface DurationStats {
     /** 짝이 맞아 계산된 건수. */
     count: number;
     /**
-     * 하위 꼬리 — **분포를 양쪽에서 접지하기 위해** 낸다.
+     * 하위 꼬리 — **분포를 양쪽에서 계산하지하기 위해** 낸다.
      * p50·p90 만 있으면 아래쪽 퍼짐을 위쪽에서 거울처럼 베껴 쓸 수밖에 없다(발명). 관측이 말하게 한다.
      */
     p10Ms: number;
@@ -49,7 +50,7 @@ export interface KpiGroup {
      * **품질 판정이 있었던 건수만** 센다 (2026-08-19).
      *
      * 판정이 없는 작업(이동·체류·중간 스테이션)은 어느 쪽에도 세지 않는다 — 모름을 양품으로 세면 양품률이
-     * 조용히 100% 로 올라간다. 그래서 `good + scrap` 은 `tasks` 보다 작을 수 있고, 그것이 정상이다.
+     * 알리지 않고 100% 로 올라간다. 그래서 `good + scrap` 은 `tasks` 보다 작을 수 있고, 그것이 정상이다.
      *
      * 판정이 하나도 없으면 **필드를 만들지 않는다**(0/0 을 「양품률 0%」로 읽히게 두지 않는다).
      */
@@ -98,9 +99,167 @@ export interface KpiResult {
          */
         peakGrossKW?: number;
         shavedKW?: number;
+        /**
+         * 이 창의 **발전량** — 커널이 마감한 기간 사실(`energy.generation.period`)에서 온다.
+         *
+         * 부하(`kWh`)와 더하지 않는다: 발전은 설비가 만든 양이고 부하는 계량 지점을 지난 양이다. 두 수를
+         * 더하면 어느 쪽도 아닌 숫자가 된다.
+         *
+         * 성과지표(ISO 50001 EnPI)와 태양광 성능비가 이 값을 분자로 쓴다. 발전 사실이 없으면 `undefined`
+         * 다(0 이 아니다 — 「발전이 없다」와 「발전 설비가 없다」는 다르다).
+         */
+        generated?: {
+            /** 창에 온전히 든 기간들의 합(kWh). */
+            kWh: number;
+            /** 센 기간 수. */
+            counted: number;
+            /**
+             * 그중 **관측이 기간을 다 덮지 못한** 기간 수.
+             *
+             * 커널이 기간마다 관측 구간을 함께 낸다. 마지막 표본이 기간 끝보다 이르면 그만큼 재지 않은
+             * 것이고, 그 수를 감추면 화면이 덜 잰 합을 온전한 합으로 말한다.
+             */
+            partial: number;
+            /** 설비별 몫 — 이것은 **측정**이다(배분이 아니다). 각 설비의 적산에서 왔다. */
+            byEquipment: {
+                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` 가 어느 회계에서 왔나.
+         *
+         *   'demand-window'   우리가 표본에서 마감한 구간 (계량이 오는 현장)
+         *   'usage-period'    밖에서 마감되어 온 구간 (계량 표본이 없는 현장)
+         *
+         * 둘을 더하지 않는다 — 같은 전기를 두 번 센다. 둘 다 있으면 계량 쪽을 쓰고 그 사실을 낸다.
+         */
+        kWhBasis?: 'demand-window' | 'usage-period';
+        /**
+         * 기본요금을 매긴 **요금적용전력과 그 근거**.
+         *
+         * 이 값은 매달 다시 정해진다. 선언에 박아 두면 사람이 갱신해야 하고, 안 하면 낡은 값으로
+         * 기본요금이 조용히 틀린다. 그래서 **청구서가 먼저다** — 원본이 매일 실어 보낸다.
+         *
+         *   'bill'             이 창을 덮는 청구서가 말한 값
+         *   'carried-forward'  가장 최근 청구서의 값을 이어 쓴다(요금 제도가 실제로 그렇게 군다)
+         *   'declaration'      청구가 오지 않는 현장 — 모델의 선언
+         *
+         * `declaredKW` 와 다르면 **선언이 낡았다**(`stale`). 그 사실을 감추면 아무도 다시 읽지 않는다.
+         */
+        billingDemand?: {
+            kW: number;
+            from: 'tariff-basis' | 'bill' | 'carried-forward' | 'declaration';
+            declaredKW?: number;
+            stale?: boolean;
+            /**
+             * 이 창에서 관측한 최고 수요가 그 기준을 넘었다 — **다음 주기의 기본요금이 오른다.**
+             *
+             * 계약 초과와 다른 값이다. 계약 초과는 지금 줄이면 되고, 이것은 이미 정해진 결과다.
+             *
+             * `observedTo` 는 이 최고값이 언제까지의 것인지다. 최고 수요는 구간이 마감되어야 오므로
+             * 넘은 것을 뒤늦게 안다 — 그 한계를 화면이 말할 수 있어야 한다.
+             */
+            exceeded?: {
+                peakKW: number;
+                overKW: number;
+                observedTo: string;
+            };
+        };
+        /**
+         * 밖에서 마감되어 온 사용 구간 — 계량 표본이 없는 현장의 유일한 근거다.
+         *
+         * `basis` 별 건수를 함께 낸다: 같은 kWh 라도 계량기가 잰 것과 공급자 화면에서 긁어온 것은 무게가
+         * 다르고, 실제로 긁어온 값이 망가져 있는 것을 본 적이 있다.
+         */
+        usage?: {
+            kWh: number;
+            counted: number;
+            /** 구간마다 제 단가로 매긴 사용량 요금 — 모든 구간이 단가를 실었을 때만. */
+            charge?: number;
+            currency?: string;
+            /** 단가가 없어 요금을 매기지 못한 구간 수 — 조용히 빼지 않는다. */
+            unpriced: number;
+            byBasis: {
+                basis: string;
+                counted: number;
+            }[];
+        };
+        /**
+         * 이 창에 온전히 든 **청구서** — 공급자가 확정한 금액.
+         *
+         * 우리 계산을 덮지 않는다. 창이 청구 주기와 정확히 같을 때만 견줄 수 있으므로 그 사실을
+         * `matchesWindow` 로 함께 낸다 — 다른 창의 두 수를 빼면 그 차이는 아무것도 뜻하지 않는다.
+         */
+        bill?: {
+            from: string;
+            to: string;
+            total?: number;
+            energyCharge?: number;
+            demandCharge?: number;
+            currency?: string;
+            billingDemandKW?: number;
+            matchesWindow: boolean;
+            /**
+             * 창이 같을 때, **우리 계산에서 청구액을 뺀 값** — 0 이 아니면 우리 계산이 틀렸다는 뜻이다.
+             *
+             * 항목별로도 낸다(2026-08-29). 총액만 견주면 원본이 총액을 주지 않는 청구서에서는 비교가
+             * 영영 나오지 않는다 — 실제로 첫 청구서에 기본요금만 있었다. 양쪽에 있는 항목만 견준다.
+             */
+            diff?: {
+                total?: number;
+                demandCharge?: number;
+                energyCharge?: number;
+            };
+        };
         /** 파생의 근거 — 구간 평균부하 × 길이(`mean-kw`). */
         basis: string;
-        /** 센 구간 수 · 못 센 구간 수(계측이 끊긴 구간) — 조용히 자르지 않는다. */
+        /** 센 구간 수 · 못 센 구간 수(계측이 끊긴 구간) — 알리지 않고 자르지 않는다. */
         counted: number;
         skipped: number;
         /** 완료 오더당 전력량 — 답할 수 없으면 `null` 과 이유. */
@@ -124,7 +283,7 @@ export interface KpiResult {
          * 붙지 않는 부하도 그 비율에 섞인다 — 화면이 그 문장을 함께 말해야 한다.
          */
         byFeeder?: {
-            /** 자리(분기·수전) id. 자리를 모르는 자원은 `unknown` 으로 모인다(조용히 버리지 않는다). */
+            /** 자리(분기·수전) id. 자리를 모르는 자원은 `unknown` 으로 모인다(알리지 않고 버리지 않는다). */
             key: string;
             kWh: number;
             /**
@@ -153,7 +312,7 @@ export interface KpiResult {
             peakKW?: number;
         }[];
         /**
-         * 나누지 못한 양과 그 이유 — **조용히 0 으로 만들지 않는다.**
+         * 나누지 못한 양과 그 이유 — **알리지 않고 0 으로 만들지 않는다.**
          * `no-weights` = 그 창에 돌아간 자원이 없다(가동시간이 전부 0). 그러면 총량은 그대로 남는다.
          */
         unattributedKWh?: number;
@@ -193,7 +352,7 @@ export interface KpiResult {
     }[];
     /**
      * **셈에서 빠진 것** — 완료는 창 안이지만 시작 이벤트를 못 찾은 건수.
-     * 조회 구간이 짧아 시작이 잘렸거나 저널이 유실된 경우다. 이 값을 숨기면 평균이 조용히 거짓이 된다.
+     * 조회 구간이 짧아 시작이 잘렸거나 저널이 유실된 경우다. 이 값을 숨기면 평균이 알리지 않고 거짓이 된다.
      */
     unpaired: {
         leadTime: number;
@@ -248,12 +407,51 @@ export interface KpiResult {
         truncatedTasks?: number;
     };
 }
-/** 폴드 옵션 — 관점 축과, 그 축을 만들기 위해 이벤트 밖에서 와야 하는 지도. */
 export interface KpiFoldOptions {
     groupBy?: KpiGroupBy;
+    /**
+     * 이 트윈이 이어받고 있는 **마지막 청구서** — 요금적용전력의 우선 근거(§`billingDemandOf`).
+     *
+     * 창 밖의 청구서는 저널 조회에 걸리지 않는다. 그런데 그 값은 이 창에도 적용되므로 호출부가
+     * 커널 상태에서 읽어 넘긴다.
+     */
+    lastBill?: {
+        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' 으로 모인다(조용히 다른 축으로 바꾸지 않는다).
+     * 호출부가 넘긴다. 없으면 구역 축은 'unknown' 으로 모인다(알리지 않고 다른 축으로 바꾸지 않는다).
      */
     locationArea?: Record<string, string>;
     /**
@@ -283,7 +481,7 @@ export interface KpiFoldOptions {
     tariff?: TariffDeclaration;
     /**
      * 교대 선언 — **이벤트에는 교대가 없다**(시각만 있다). 현장 마스터가 아는 값이라 호출부가 넘긴다.
-     * 없으면 교대 축은 'unknown' 으로 모인다(다른 축으로 조용히 바꾸지 않는다).
+     * 없으면 교대 축은 'unknown' 으로 모인다(다른 축으로 알리지 않고 바꾸지 않는다).
      */
     shifts?: WorkCalendarEntry[];
     /**
@@ -300,11 +498,11 @@ export interface KpiFoldOptions {
     groupLimit?: number;
 }
 /**
- * 이벤트를 접어 시간창 KPI 를 만든다.
+ * 이벤트를 계산해 시간창 KPI 를 만든다.
  *
  * **호출부 규약**: `events` 는 창보다 **넉넉히 앞까지** 담아 넘긴다(예: 창 시작 − 리드타임 상한).
  * 완료된 작업의 시작 이벤트가 창 밖에 있을 수 있기 때문이다. 못 찾은 것은 `unpaired` 로 알린다 —
- * 평균에서 조용히 빠지면 지표가 거짓이 된다.
+ * 평균에서 오류 없이 빠지면 지표가 거짓이 된다.
  *
  * 시간축은 `eventTime`(ISO) 차분이다. sim 클록이 실제 시각과 오프셋이 있어도 **차분은 정확**하다
  * (고정 오프셋은 상쇄된다). 파싱 불가한 줄은 버린다.
@@ -363,7 +561,7 @@ export interface KpiBucket {
     workP50Ms: number;
 }
 /**
- * 창을 N 등분해 구간별로 접는다 — **같은 이벤트를 창만 바꿔** 다시 접는다(조회 추가 없음).
+ * 창을 N 등분해 구간별로 처리한다 — **같은 이벤트를 창만 바꿔** 다시 계산한다(조회 추가 없음).
  *
  * 마지막 구간은 나머지를 흡수한다(부동소수 나눗셈으로 끝이 밀리면 마지막 완료가 빠진다).
  * `count <= 1` 이면 쪼갤 것이 없으므로 빈 배열 — 호출부가 "추세 없음" 으로 다룬다.