@things-factory/headless-twin 10.0.15 → 10.0.18

package/server/engine/kpi-fold.ts

@@ -1,5 +1,5 @@
 /*
- * 업무 KPI 폴드 — **이벤트 저널을 접어** 시간창 지표를 만든다(순수).
+ * 업무 KPI 폴드 — **이벤트 저널을 계산해** 시간창 지표를 만든다(순수).
  *
  * ── 왜 필요한가 ─────────────────────────────────────────────────────────────
  * 지금 트윈이 답할 수 있는 것은 "이 순간의 값"(점유 92%)과 "인프라 부하"(초당 이벤트 수)뿐이다.
@@ -8,8 +8,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)의 몫이고,
@@ -23,27 +23,16 @@
  * 짝맞춤은 **커널이 소유한다**(`foldTaskRecords`). 완료는 작업당 하나·나중 것이 사실, 착수는 처음 것,
  * 종류·오더는 어느 전이에서든 — 그 규칙은 커널 상태 기계에서 나오는 지식이다. 여기서 다시 적었더니
  * 공정 타임라인과 **다른 답**을 냈다(재전송된 완료를 두 건으로 세어 처리량·점유가 부풀려졌다).
- * 이 파일은 이제 "접힌 기록 → 창 지표" 만 한다.
+ * 이 파일은 이제 "계산한 기록 → 창 지표" 만 한다.
  */
-import {
-  ENERGY_EVENT,
-  attributeEnergy,
-  electricityCost,
-  energyIntensity,
-  energyOfWindows,
-  foldTaskRecords,
-  isOrderTerminal,
-  activeShiftAt,
-  type ElectricityCost,
-  type TariffDeclaration,
-  type TaskFacets,
-  type WorkCalendarEntry
-} from '@operato/twin-kernel'
+import { attributeEnergy, electricityCost, energyIntensity, energyOfWindows, foldTaskRecords, type ElectricityCost, type TariffDeclaration, type TaskFacets } from '@operato/twin-kernel'
+import { type WorkCalendarEntry } from '@operato/ops-contract'
+import { ENERGY_EVENT, isOrderTerminal, activeShiftAt } from '@operato/ops-contract'
 
 /** 저널 한 줄 — 필요한 것만(엔티티·typeorm 비의존). */
 export interface KpiEvent {
   eventType?: string
-  /** ISO 시각. 파싱 불가하면 그 줄은 버린다(조용히 0 으로 세지 않는다). */
+  /** ISO 시각. 파싱 불가하면 그 줄은 버린다(알리지 않고 0 으로 세지 않는다). */
   eventTime?: string
   payload?: any
 }
@@ -58,7 +47,7 @@ export interface DurationStats {
   /** 짝이 맞아 계산된 건수. */
   count: number
   /**
-   * 하위 꼬리 — **분포를 양쪽에서 접지하기 위해** 낸다.
+   * 하위 꼬리 — **분포를 양쪽에서 계산하지하기 위해** 낸다.
    * p50·p90 만 있으면 아래쪽 퍼짐을 위쪽에서 거울처럼 베껴 쓸 수밖에 없다(발명). 관측이 말하게 한다.
    */
   p10Ms: number
@@ -94,7 +83,7 @@ export interface KpiGroup {
    * **품질 판정이 있었던 건수만** 센다 (2026-08-19).
    *
    * 판정이 없는 작업(이동·체류·중간 스테이션)은 어느 쪽에도 세지 않는다 — 모름을 양품으로 세면 양품률이
-   * 조용히 100% 로 올라간다. 그래서 `good + scrap` 은 `tasks` 보다 작을 수 있고, 그것이 정상이다.
+   * 알리지 않고 100% 로 올라간다. 그래서 `good + scrap` 은 `tasks` 보다 작을 수 있고, 그것이 정상이다.
    *
    * 판정이 하나도 없으면 **필드를 만들지 않는다**(0/0 을 「양품률 0%」로 읽히게 두지 않는다).
    */
@@ -135,9 +124,137 @@ 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` 과 이유. */
@@ -157,7 +274,7 @@ export interface KpiResult {
      * 붙지 않는 부하도 그 비율에 섞인다 — 화면이 그 문장을 함께 말해야 한다.
      */
     byFeeder?: {
-      /** 자리(분기·수전) id. 자리를 모르는 자원은 `unknown` 으로 모인다(조용히 버리지 않는다). */
+      /** 자리(분기·수전) id. 자리를 모르는 자원은 `unknown` 으로 모인다(알리지 않고 버리지 않는다). */
       key: string
       kWh: number
       /**
@@ -186,7 +303,7 @@ export interface KpiResult {
       peakKW?: number
     }[]
     /**
-     * 나누지 못한 양과 그 이유 — **조용히 0 으로 만들지 않는다.**
+     * 나누지 못한 양과 그 이유 — **알리지 않고 0 으로 만들지 않는다.**
      * `no-weights` = 그 창에 돌아간 자원이 없다(가동시간이 전부 0). 그러면 총량은 그대로 남는다.
      */
     unattributedKWh?: number
@@ -222,7 +339,7 @@ export interface KpiResult {
   utilization: { resourceId: string; busyMs: number; ratio: number }[]
   /**
    * **셈에서 빠진 것** — 완료는 창 안이지만 시작 이벤트를 못 찾은 건수.
-   * 조회 구간이 짧아 시작이 잘렸거나 저널이 유실된 경우다. 이 값을 숨기면 평균이 조용히 거짓이 된다.
+   * 조회 구간이 짧아 시작이 잘렸거나 저널이 유실된 경우다. 이 값을 숨기면 평균이 알리지 않고 거짓이 된다.
    */
   unpaired: { leadTime: number; workTime: number }
   /**
@@ -372,6 +489,266 @@ function feederShares(
  * 분기 계량 합이 뿌리보다 크면(회계가 다른 두 계량기) **그 사실을 낸다** — 값을 깎아 맞추면 계량을
  * 우리가 고쳐 쓰는 것이다.
  */
+/**
+ * 창의 **발전량** — 커널이 마감한 기간 사실을 합한다.
+ *
+ * ── 왜 합이 전부인가 ───────────────────────────────────────────────────────
+ * 기간 발전량은 커널이 이미 확정한 사실이다(적산의 종류마다 다른 규칙으로 얻는다). 여기서 다시
+ * 계산하면 규칙이 두 벌이 되고, 그때부터 두 화면이 다른 발전량을 말한다. 이 함수가 하는 일은
+ * **창에 든 것을 고르고, 설비별로 묶고, 근거가 얼마나 덮였는지 세는 것**이다.
+ *
+ * ── 걸친 기간은 세지 않는다 ─────────────────────────────────────────────────
+ * 구간 마감과 같은 규칙이다. 하루의 절반이 창에 들었다고 절반을 세면 그것은 관측이 아니라 우리가 나눈
+ * 값이고, 합이 창을 넘는다.
+ *
+ * ── 덜 덮인 기간을 센다 ─────────────────────────────────────────────────────
+ * 기간의 끝이 자정인데 마지막 표본이 저녁이었으면 그 사이는 재지 않은 것이다. 그 수를 함께 내야 화면이
+ * 「이 합은 이만큼 덜 잰 것」이라고 말할 수 있다. 얼마나 어긋나면 문제인지는 현장이 정한다.
+ */
+function generatedOfPeriods(
+  periods: readonly {
+    equipmentId: string
+    kWh: number
+    startMs: number
+    endMs: number
+    observedFromMs: number
+    observedToMs: number
+  }[],
+  range: { startMs: number; endMs: number },
+  /** 이용률의 분모 — 없으면 이용률을 내지 않는다(0 이나 짐작을 만들지 않는다). */
+  rated?: { kW: number; basis: 'ac' | 'dc'; from: 'equipment' | 'location' },
+  /** 기간마다 적용할 단가 — 기간을 덮는 것을 쓴다. 없으면 금액을 만들지 않는다. */
+  prices?: readonly { startMs: number; endMs: number; unitPrice: number; currency: string }[]
+): Partial<NonNullable<KpiResult['energy']>> {
+  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<string, number>()
+  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: string | undefined
+  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: readonly { meterId: string; kWh: number; startMs: number; endMs: number; unitPrice: number; currency?: string; basis: string }[],
+  range: { startMs: number; endMs: number }
+): NonNullable<KpiResult['energy']>['usage'] | undefined {
+  const inside = periods.filter(u => u.startMs >= range.startMs && u.endMs <= range.endMs)
+  if (!inside.length) return undefined
+
+  const byBasis = new Map<string, number>()
+  let kWh = 0
+  let charge = 0
+  let unpriced = 0
+  let currency: string | undefined
+  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: readonly { endMs: number; billingDemandKW: number }[],
+  tariffBasis: { billingDemandKW?: number } | undefined,
+  lastBill: { billingDemandKW?: number } | undefined,
+  declaredKW: number | undefined,
+  /** 이 창에서 관측한 최고 수요와 그 값이 언제까지의 것인지 — 사용 구간의 `maxKW` 에서 온다. */
+  observedPeak?: { kW: number; toMs: number }
+): NonNullable<KpiResult['energy']>['billingDemand'] | undefined {
+  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' as const }
+      : fromBill !== undefined
+        ? { kW: fromBill, from: 'bill' as const }
+        : carried !== undefined
+          ? { kW: carried, from: 'carried-forward' as const }
+          : declared !== undefined
+            ? { kW: declared, from: 'declaration' as const }
+            : 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: readonly {
+    from: string
+    to: string
+    startMs: number
+    endMs: number
+    total: number
+    energyCharge: number
+    demandCharge: number
+    currency?: string
+    billingDemandKW: number
+  }[],
+  range: { startMs: number; endMs: number },
+  ours?: { total?: number; demandCharge?: number; energyCharge?: number }
+): NonNullable<KpiResult['energy']>['bill'] | undefined {
+  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: unknown, billed: number): number | undefined =>
+    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) as number } : {}),
+        ...(gap(ours?.demandCharge, b.demandCharge) !== undefined
+          ? { demandCharge: gap(ours?.demandCharge, b.demandCharge) as number }
+          : {}),
+        ...(gap(ours?.energyCharge, b.energyCharge) !== undefined
+          ? { energyCharge: gap(ours?.energyCharge, b.energyCharge) as number }
+          : {})
+      }
+    : {}
+  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: readonly {
     startMs: number
@@ -453,11 +830,56 @@ function measuredFeeders(
 }
 
 /** 폴드 옵션 — 관점 축과, 그 축을 만들기 위해 이벤트 밖에서 와야 하는 지도. */
+/*
+ * ── 같은 사실이 두 벌 있어도 한 번만 센다 (2026-08-30) ──────────────────────
+ *
+ * 마감된 구간 사실은 정체성이 내용에 있다(커널 0.7.81). 그런데 저널에 이미 여러 벌 적힌 것이 있다 —
+ * 쓰는 자리에서 막기 전에 들어간 것들이다(실측: 어느 날의 발전 단가가 세 벌).
+ *
+ * 지난 기록을 지우지 않는다 — 저널은 일어난 일의 기록이다. 대신 **읽을 때 한 번만 센다.**
+ * 그러지 않으면 그 구간의 수익·사용량이 그 횟수만큼 세어진다.
+ */
+function onceById<T extends { payload?: any }>(rows: readonly T[]): T[] {
+  const seen = new Set<string>()
+  return rows.filter(r => {
+    const id = (r as any)?.payload?.eventId
+    if (typeof id !== 'string' || !id) return true
+    if (seen.has(id)) return false
+    seen.add(id)
+    return true
+  })
+}
+
 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>
   /**
@@ -487,7 +909,7 @@ export interface KpiFoldOptions {
   tariff?: TariffDeclaration
   /**
    * 교대 선언 — **이벤트에는 교대가 없다**(시각만 있다). 현장 마스터가 아는 값이라 호출부가 넘긴다.
-   * 없으면 교대 축은 'unknown' 으로 모인다(다른 축으로 조용히 바꾸지 않는다).
+   * 없으면 교대 축은 'unknown' 으로 모인다(다른 축으로 알리지 않고 바꾸지 않는다).
    */
   shifts?: WorkCalendarEntry[]
   /**
@@ -518,7 +940,7 @@ interface CompletionRecord {
   waitMs?: number
 }
 
-/** 이 기록이 요청한 축에서 어느 값에 속하는가. 값이 없으면 'unknown'(조용히 버리지 않는다). */
+/** 이 기록이 요청한 축에서 어느 값에 속하는가. 값이 없으면 'unknown'(알리지 않고 버리지 않는다). */
 function facetKey(rec: CompletionRecord, options: KpiFoldOptions): string {
   const f = rec.facets
   switch (options.groupBy) {
@@ -547,7 +969,7 @@ function facetKey(rec: CompletionRecord, options: KpiFoldOptions): string {
        */
       if (!options.shifts?.length) return 'unknown'
       /* 시각까지 넘긴다 — **휴일에 일어난 일은 어느 교대에도 속하지 않는다.** 되풀이만 보면 그날 서지도
-         않은 교대에 집계돼, 교대별 성과가 조용히 거짓이 된다. */
+         않은 교대에 집계돼, 교대별 성과가 알리지 않고 거짓이 된다. */
       return activeShiftAt(options.shifts, rec.at, options.utcOffsetMinutes) ?? 'unknown'
     default:
       return 'unknown'
@@ -576,7 +998,7 @@ function qualityOf(rows: CompletionRecord[]): { quality?: { good: number; scrap:
  * 기록을 축으로 묶어 축별 통계를 낸다 — **전체와 같은 규칙**으로(같은 stats 함수, 같은 창).
  *
  * 축의 값이 아주 많을 수 있다(오더 축은 수천 개). 그래서 건수 큰 것부터 상한까지만 돌려주고
- * **잘라낸 수를 함께 알린다** — 조용한 절단은 "이게 전부" 라는 거짓을 만든다.
+ * **잘라낸 수를 함께 알린다** — 들어온 것이 없는 절단은 "이게 전부" 라는 거짓을 만든다.
  */
 function groupRecords(
   records: CompletionRecord[],
@@ -644,11 +1066,11 @@ function stats(values: number[]): DurationStats {
 }
 
 /**
- * 이벤트를 접어 시간창 KPI 를 만든다.
+ * 이벤트를 계산해 시간창 KPI 를 만든다.
  *
  * **호출부 규약**: `events` 는 창보다 **넉넉히 앞까지** 담아 넘긴다(예: 창 시작 − 리드타임 상한).
  * 완료된 작업의 시작 이벤트가 창 밖에 있을 수 있기 때문이다. 못 찾은 것은 `unpaired` 로 알린다 —
- * 평균에서 조용히 빠지면 지표가 거짓이 된다.
+ * 평균에서 오류 없이 빠지면 지표가 거짓이 된다.
  *
  * 시간축은 `eventTime`(ISO) 차분이다. sim 클록이 실제 시각과 오프셋이 있어도 **차분은 정확**하다
  * (고정 오프셋은 상쇄된다). 파싱 불가한 줄은 버린다.
@@ -676,7 +1098,7 @@ export function foldKpi(events: KpiEvent[], window: KpiWindow, options: KpiFoldO
        * **끝났나는 커널이 답한다** (2026-08-23) — `isOrderTerminal`.
        *
        * 예전에는 여기서 **동의어 목록**으로 추론했다(`completed`·`fulfilled`·`done`·`finished`).
-       * 그 방식이 낸 대가가 둘이었고 둘 다 조용했다.
+       * 그 방식이 낸 대가가 둘이었고 둘 다 들어온 것이 없었다.
        *
        *  ① 원본의 낱말이 목록에 없으면 완료가 0 이 된다. 실제로 그랬다 — 첫 실 시스템의 `FINISHED`
        *     가 빠져 있었고, 그때 목록에 낱말을 더한 것은 진짜 빈 자리(그 커넥터가 자기 상태 표를
@@ -693,7 +1115,7 @@ export function foldKpi(events: KpiEvent[], window: KpiWindow, options: KpiFoldO
       if (at >= window.fromMs && at <= window.toMs) {
         /*
          * **오더당 한 번만 센다.** 폴링하는 원본은 같은 오더의 종결을 여러 주기에 걸쳐 다시 보낼 수
-         * 있고(그것은 결함이 아니라 폴링의 성질이다), 사건마다 세면 처리량이 조용히 부풀려진다.
+         * 있고(그것은 결함이 아니라 폴링의 성질이다), 사건마다 세면 처리량이 알리지 않고 부풀려진다.
          * 작업 쪽은 커널의 짝맞춤이 이미 그 규율을 갖고 있다(「완료는 작업당 하나」) — 오더만 없었다.
          */
         if (done) {
@@ -701,7 +1123,7 @@ export function foldKpi(events: KpiEvent[], window: KpiWindow, options: KpiFoldO
           if (id && !completedOrderIds.has(id)) {
             completedOrderIds.add(id)
             completedOrders++
-          } else if (!id) completedOrders++ // 정체를 모르면 셈에서 빼지 않는다(조용히 줄이지 않는다)
+          } else if (!id) completedOrders++ // 정체를 모르면 셈에서 빼지 않는다(알리지 않고 줄이지 않는다)
         }
         /*
          * **완료로 세지 않은 낱말의 인구조사.** 「못 읽었다」가 아니다 — `picking` 처럼 완료가 아닌
@@ -744,6 +1166,76 @@ export function foldKpi(events: KpiEvent[], window: KpiWindow, options: KpiFoldO
     })
     .filter(w => Number.isFinite(w.startMs) && Number.isFinite(w.endMs))
 
+  /*
+   * 발전 기간 사실 — 커널이 기간을 마감할 때 낸 것이다. 구간 마감과 같은 규칙으로 **창에 온전히 든
+   * 것만** 센다(걸친 기간을 반만 세면 합이 창을 넘는다).
+   *
+   * 관측 구간(`observedFrom`·`observedTo`)을 함께 읽는다 — 값의 근거가 얼마나 덮였는지가 그 둘에 있다.
+   */
+  const generationPeriods = onceById(events.filter(e => e.eventType === 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 === 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 === 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 === 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: number[] = []
   const works: number[] = []
   const waits: number[] = []
@@ -785,18 +1277,54 @@ export function foldKpi(events: KpiEvent[], window: KpiWindow, options: KpiFoldO
   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 = 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 = 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 as number, 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
+            ? 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 } : {}),
               /* 깎인 양은 **같은 구간의 두 수**의 차이다 — 여기서 한 번만 계산해 두 곳이 갈라지지 않게. */
@@ -813,7 +1341,30 @@ export function foldKpi(events: KpiEvent[], window: KpiWindow, options: KpiFoldO
               ...(measuredFeeders(demandWindows, { startMs: window.fromMs, endMs: window.toMs }, e.kWh, options.meterFeeder) ??
                 feederShares(e.kWh, utilization, options.resourceFeeder)),
               /* 금액은 같은 창의 전력량·최대수요에서 나온다 — 창이 하나뿐이라 어긋날 수 없다. */
-              ...(options.tariff ? { cost: 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 as any)
+                return b ? { bill: b } : {}
+              })()
             }
           }
         })()
@@ -876,7 +1427,7 @@ export function crossGroups(
 
 /* ── 시간 비교 ──────────────────────────────────────────────────────────────
  * 숫자 하나로는 좋아졌는지 나빠졌는지 알 수 없다("29초" 가 개선인지 악화인지). 같은 길이의 창을 옮겨
- * 한 번 더 접으면 되므로(폴드는 순수) 값싸다. 창 옮기기와 차이 계산은 계산 규칙이라 여기 있다 —
+ * 한 번 더 계산하면 되므로(폴드는 순수) 값싸다. 창 옮기기와 차이 계산은 계산 규칙이라 여기 있다 —
  * 조회 층에 두면 테스트가 DB 를 끌고 와야 한다.
  */
 
@@ -913,7 +1464,7 @@ export interface KpiBucket {
 }
 
 /**
- * 창을 N 등분해 구간별로 접는다 — **같은 이벤트를 창만 바꿔** 다시 접는다(조회 추가 없음).
+ * 창을 N 등분해 구간별로 처리한다 — **같은 이벤트를 창만 바꿔** 다시 계산한다(조회 추가 없음).
  *
  * 마지막 구간은 나머지를 흡수한다(부동소수 나눗셈으로 끝이 밀리면 마지막 완료가 빠진다).
  * `count <= 1` 이면 쪼갤 것이 없으므로 빈 배열 — 호출부가 "추세 없음" 으로 다룬다.