@things-factory/headless-twin 10.0.14 → 10.0.17

package/server/engine/kpi-baseline.ts

@@ -6,7 +6,7 @@
  * "어제보다 나아졌다." **어제도 나빴으면 그 말은 쓸모가 없다.** 목표(`kpi-target`)가 그 한계를 한쪽에서
  * 풀지만, 목표를 아직 걸지 않은 현장은 여전히 자기 숫자가 평소와 같은지도 알 수 없다.
  *
- * 최근 며칠의 **같은 시간대**를 함께 접으면 목표 없이도 말할 수 있다 — "오늘 이 시간대는 지난 7일 중
+ * 최근 며칠의 **같은 시간대**를 함께 계산하면 목표 없이도 말할 수 있다 — "오늘 이 시간대는 지난 7일 중
  * 가장 낮다." 그것이 이 파일이 만드는 것이다: 창 여러 개의 **분포**와 그 안에서 현재의 **자리**.
  *
  * ── 이 파일이 하지 않는 것 ──────────────────────────────────────────────────
@@ -18,12 +18,12 @@
  *   퍼센트 임계를 두면 그 숫자가 곧 숨은 목표가 된다.
  *
  * ── 정직성 규율 (이 도메인의 핵심) ──────────────────────────────────────────
- *  ① **결측 창을 조용히 빼지 않는다.** 요청한 창 전부를 `measured` 와 함께 돌려주고, 분포는 측정된
+ *  ① **결측 창을 알리지 않고 빼지 않는다.** 요청한 창 전부를 `measured` 와 함께 돌려주고, 분포는 측정된
  *     것만으로 만든다. 빼고 말하면 "지난 7일" 이 실제로는 3일이었다는 것을 아무도 모른다.
  *  ② **표본이 둘 미만이면 자리를 말하지 않는다.** 하나를 분포라 부를 수 없다.
  *  ③ **현재 값이 없으면 자리를 말하지 않는다.** 결측을 0 으로 읽으면 시간 지표는 "낮을수록 좋다" 라서
  *     **일이 없던 구간이 최고 성적**으로 보고된다(목표 판정에서 이미 겪은 결함이다).
- *  ④ 왜 말하지 않는지를 `reason` 으로 밝힌다 — 조용히 빈 값을 주면 화면이 "분포 없음" 을 "평범함" 으로
+ *  ④ 왜 말하지 않는지를 `reason` 으로 밝힌다 — 알리지 않고 빈 값을 주면 화면이 "분포 없음" 을 "평범함" 으로
  *     그린다.
  */
 
@@ -168,7 +168,7 @@ export function summarizeBaseline<M extends string>(
       ...(sorted.length ? { min: sorted[0], median: medianOf(sorted), max: sorted[sorted.length - 1] } : {})
     }
 
-    /* 자리를 말할 수 없는 두 경우 — 이유를 밝힌다(조용한 빈 값이 "평범함" 으로 읽힌다). */
+    /* 자리를 말할 수 없는 두 경우 — 이유를 밝힌다(들어온 것이 없는 빈 값이 "평범함" 으로 읽힌다). */
     if (!hasCurrent) row.noPosition = 'no-current'
     else if (sorted.length < 2) row.noPosition = 'too-few-samples'
     else {

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,7 +23,7 @@
  * 짝맞춤은 **커널이 소유한다**(`foldTaskRecords`). 완료는 작업당 하나·나중 것이 사실, 착수는 처음 것,
  * 종류·오더는 어느 전이에서든 — 그 규칙은 커널 상태 기계에서 나오는 지식이다. 여기서 다시 적었더니
  * 공정 타임라인과 **다른 답**을 냈다(재전송된 완료를 두 건으로 세어 처리량·점유가 부풀려졌다).
- * 이 파일은 이제 "접힌 기록 → 창 지표" 만 한다.
+ * 이 파일은 이제 "계산한 기록 → 창 지표" 만 한다.
  */
 import {
   ENERGY_EVENT,
@@ -43,7 +43,7 @@ import {
 /** 저널 한 줄 — 필요한 것만(엔티티·typeorm 비의존). */
 export interface KpiEvent {
   eventType?: string
-  /** ISO 시각. 파싱 불가하면 그 줄은 버린다(조용히 0 으로 세지 않는다). */
+  /** ISO 시각. 파싱 불가하면 그 줄은 버린다(알리지 않고 0 으로 세지 않는다). */
   eventTime?: string
   payload?: any
 }
@@ -58,7 +58,7 @@ export interface DurationStats {
   /** 짝이 맞아 계산된 건수. */
   count: number
   /**
-   * 하위 꼬리 — **분포를 양쪽에서 접지하기 위해** 낸다.
+   * 하위 꼬리 — **분포를 양쪽에서 계산하지하기 위해** 낸다.
    * p50·p90 만 있으면 아래쪽 퍼짐을 위쪽에서 거울처럼 베껴 쓸 수밖에 없다(발명). 관측이 말하게 한다.
    */
   p10Ms: number
@@ -94,7 +94,7 @@ export interface KpiGroup {
    * **품질 판정이 있었던 건수만** 센다 (2026-08-19).
    *
    * 판정이 없는 작업(이동·체류·중간 스테이션)은 어느 쪽에도 세지 않는다 — 모름을 양품으로 세면 양품률이
-   * 조용히 100% 로 올라간다. 그래서 `good + scrap` 은 `tasks` 보다 작을 수 있고, 그것이 정상이다.
+   * 알리지 않고 100% 로 올라간다. 그래서 `good + scrap` 은 `tasks` 보다 작을 수 있고, 그것이 정상이다.
    *
    * 판정이 하나도 없으면 **필드를 만들지 않는다**(0/0 을 「양품률 0%」로 읽히게 두지 않는다).
    */
@@ -135,9 +135,99 @@ 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 }[]
+    }
+    /**
+     * `kWh` 가 어느 회계에서 왔나.
+     *
+     *   'demand-window'   우리가 표본에서 마감한 구간 (계량이 오는 현장)
+     *   'usage-period'    밖에서 마감되어 온 구간 (계량 표본이 없는 현장)
+     *
+     * 둘을 더하지 않는다 — 같은 전기를 두 번 센다. 둘 다 있으면 계량 쪽을 쓰고 그 사실을 낸다.
+     */
+    kWhBasis?: 'demand-window' | 'usage-period'
+    /**
+     * 기본요금을 매긴 **요금적용전력과 그 근거**.
+     *
+     * 이 값은 매달 다시 정해진다. 선언에 박아 두면 사람이 갱신해야 하고, 안 하면 낡은 값으로
+     * 기본요금이 조용히 틀린다. 그래서 **청구서가 먼저다** — 원본이 매일 실어 보낸다.
+     *
+     *   'bill'             이 창을 덮는 청구서가 말한 값
+     *   'carried-forward'  가장 최근 청구서의 값을 이어 쓴다(요금 제도가 실제로 그렇게 군다)
+     *   'declaration'      청구가 오지 않는 현장 — 모델의 선언
+     *
+     * `declaredKW` 와 다르면 **선언이 낡았다**(`stale`). 그 사실을 감추면 아무도 다시 읽지 않는다.
+     */
+    billingDemand?: {
+      kW: number
+      from: 'bill' | 'carried-forward' | 'declaration'
+      declaredKW?: number
+      stale?: boolean
+    }
+    /**
+     * 밖에서 마감되어 온 사용 구간 — 계량 표본이 없는 현장의 유일한 근거다.
+     *
+     * `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 +247,7 @@ export interface KpiResult {
      * 붙지 않는 부하도 그 비율에 섞인다 — 화면이 그 문장을 함께 말해야 한다.
      */
     byFeeder?: {
-      /** 자리(분기·수전) id. 자리를 모르는 자원은 `unknown` 으로 모인다(조용히 버리지 않는다). */
+      /** 자리(분기·수전) id. 자리를 모르는 자원은 `unknown` 으로 모인다(알리지 않고 버리지 않는다). */
       key: string
       kWh: number
       /**
@@ -186,7 +276,7 @@ export interface KpiResult {
       peakKW?: number
     }[]
     /**
-     * 나누지 못한 양과 그 이유 — **조용히 0 으로 만들지 않는다.**
+     * 나누지 못한 양과 그 이유 — **알리지 않고 0 으로 만들지 않는다.**
      * `no-weights` = 그 창에 돌아간 자원이 없다(가동시간이 전부 0). 그러면 총량은 그대로 남는다.
      */
     unattributedKWh?: number
@@ -222,7 +312,7 @@ export interface KpiResult {
   utilization: { resourceId: string; busyMs: number; ratio: number }[]
   /**
    * **셈에서 빠진 것** — 완료는 창 안이지만 시작 이벤트를 못 찾은 건수.
-   * 조회 구간이 짧아 시작이 잘렸거나 저널이 유실된 경우다. 이 값을 숨기면 평균이 조용히 거짓이 된다.
+   * 조회 구간이 짧아 시작이 잘렸거나 저널이 유실된 경우다. 이 값을 숨기면 평균이 알리지 않고 거짓이 된다.
    */
   unpaired: { leadTime: number; workTime: number }
   /**
@@ -372,6 +462,183 @@ function feederShares(
  * 분기 계량 합이 뿌리보다 크면(회계가 다른 두 계량기) **그 사실을 낸다** — 값을 깎아 맞추면 계량을
  * 우리가 고쳐 쓰는 것이다.
  */
+/**
+ * 창의 **발전량** — 커널이 마감한 기간 사실을 합한다.
+ *
+ * ── 왜 합이 전부인가 ───────────────────────────────────────────────────────
+ * 기간 발전량은 커널이 이미 확정한 사실이다(적산의 종류마다 다른 규칙으로 얻는다). 여기서 다시
+ * 계산하면 규칙이 두 벌이 되고, 그때부터 두 화면이 다른 발전량을 말한다. 이 함수가 하는 일은
+ * **창에 든 것을 고르고, 설비별로 묶고, 근거가 얼마나 덮였는지 세는 것**이다.
+ *
+ * ── 걸친 기간은 세지 않는다 ─────────────────────────────────────────────────
+ * 구간 마감과 같은 규칙이다. 하루의 절반이 창에 들었다고 절반을 세면 그것은 관측이 아니라 우리가 나눈
+ * 값이고, 합이 창을 넘는다.
+ *
+ * ── 덜 덮인 기간을 센다 ─────────────────────────────────────────────────────
+ * 기간의 끝이 자정인데 마지막 표본이 저녁이었으면 그 사이는 재지 않은 것이다. 그 수를 함께 내야 화면이
+ * 「이 합은 이만큼 덜 잰 것」이라고 말할 수 있다. 얼마나 어긋나면 문제인지는 현장이 정한다.
+ */
+function generatedOfPeriods(
+  periods: readonly {
+    equipmentId: string
+    kWh: number
+    startMs: number
+    endMs: number
+    observedFromMs: number
+    observedToMs: number
+  }[],
+  range: { startMs: number; endMs: number }
+): Partial<NonNullable<KpiResult['energy']>> {
+  const inside = periods.filter(g => g.startMs >= range.startMs && g.endMs <= range.endMs)
+  if (!inside.length) return {}
+
+  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++
+  }
+
+  return {
+    generated: {
+      kWh: inside.reduce((a, g) => a + g.kWh, 0),
+      counted: inside.length,
+      partial,
+      byEquipment: [...byEquipment.entries()]
+        .map(([id, kWh]) => ({ id, kWh }))
+        .sort((a, b) => b.kWh - a.kWh)
+    }
+  }
+}
+
+/**
+ * 밖에서 마감되어 온 사용 구간을 합한다 — **구간 마감과 더하지 않는다.**
+ *
+ * 두 회계가 같은 전기를 말한다. 더하면 두 번 세고, 둘 다 있는 현장에서는 계량 쪽이 강한 근거이므로
+ * 그쪽을 쓴다. 여기서는 이쪽 몫만 계산하고, 무엇을 쓸지는 부르는 쪽이 정한다.
+ *
+ * 단가는 **모든 구간이 실었을 때만** 요금을 만든다. 일부만 실었는데 있는 것만 더하면 그 합이 창의
+ * 요금인 척한다 — 못 매긴 구간 수를 함께 낸다.
+ */
+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 }[],
+  lastBill: { billingDemandKW?: number } | undefined,
+  declaredKW: number | undefined
+): 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 picked =
+    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
+  return {
+    ...picked,
+    ...(declared !== undefined ? { declaredKW: declared } : {}),
+    ...(stale ? { stale: true } : {})
+  }
+}
+
+/**
+ * 창에 온전히 든 청구서 하나 — 가장 늦게 끝난 것.
+ *
+ * **창이 청구 주기와 같을 때만 견준다.** 한 달 청구서를 하루 창의 값과 빼면 그 차이는 아무것도 뜻하지
+ * 않는다. 그래서 같은지를 값과 함께 낸다.
+ */
+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
@@ -455,9 +722,16 @@ function measuredFeeders(
 /** 폴드 옵션 — 관점 축과, 그 축을 만들기 위해 이벤트 밖에서 와야 하는 지도. */
 export interface KpiFoldOptions {
   groupBy?: KpiGroupBy
+  /**
+   * 이 트윈이 이어받고 있는 **마지막 청구서** — 요금적용전력의 우선 근거(§`billingDemandOf`).
+   *
+   * 창 밖의 청구서는 저널 조회에 걸리지 않는다. 그런데 그 값은 이 창에도 적용되므로 호출부가
+   * 커널 상태에서 읽어 넘긴다.
+   */
+  lastBill?: { to: string; billingDemandKW?: number }
   /**
    * 노드 → 구역 지도. **이벤트에는 구역이 없다**(노드까지만 있다) — 스냅샷·마스터가 아는 값이라
-   * 호출부가 넘긴다. 없으면 구역 축은 'unknown' 으로 모인다(조용히 다른 축으로 바꾸지 않는다).
+   * 호출부가 넘긴다. 없으면 구역 축은 'unknown' 으로 모인다(알리지 않고 다른 축으로 바꾸지 않는다).
    */
   locationArea?: Record<string, string>
   /**
@@ -487,7 +761,7 @@ export interface KpiFoldOptions {
   tariff?: TariffDeclaration
   /**
    * 교대 선언 — **이벤트에는 교대가 없다**(시각만 있다). 현장 마스터가 아는 값이라 호출부가 넘긴다.
-   * 없으면 교대 축은 'unknown' 으로 모인다(다른 축으로 조용히 바꾸지 않는다).
+   * 없으면 교대 축은 'unknown' 으로 모인다(다른 축으로 알리지 않고 바꾸지 않는다).
    */
   shifts?: WorkCalendarEntry[]
   /**
@@ -518,7 +792,7 @@ interface CompletionRecord {
   waitMs?: number
 }
 
-/** 이 기록이 요청한 축에서 어느 값에 속하는가. 값이 없으면 'unknown'(조용히 버리지 않는다). */
+/** 이 기록이 요청한 축에서 어느 값에 속하는가. 값이 없으면 'unknown'(알리지 않고 버리지 않는다). */
 function facetKey(rec: CompletionRecord, options: KpiFoldOptions): string {
   const f = rec.facets
   switch (options.groupBy) {
@@ -547,7 +821,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 +850,7 @@ function qualityOf(rows: CompletionRecord[]): { quality?: { good: number; scrap:
  * 기록을 축으로 묶어 축별 통계를 낸다 — **전체와 같은 규칙**으로(같은 stats 함수, 같은 창).
  *
  * 축의 값이 아주 많을 수 있다(오더 축은 수천 개). 그래서 건수 큰 것부터 상한까지만 돌려주고
- * **잘라낸 수를 함께 알린다** — 조용한 절단은 "이게 전부" 라는 거짓을 만든다.
+ * **잘라낸 수를 함께 알린다** — 들어온 것이 없는 절단은 "이게 전부" 라는 거짓을 만든다.
  */
 function groupRecords(
   records: CompletionRecord[],
@@ -644,11 +918,11 @@ function stats(values: number[]): DurationStats {
 }
 
 /**
- * 이벤트를 접어 시간창 KPI 를 만든다.
+ * 이벤트를 계산해 시간창 KPI 를 만든다.
  *
  * **호출부 규약**: `events` 는 창보다 **넉넉히 앞까지** 담아 넘긴다(예: 창 시작 − 리드타임 상한).
  * 완료된 작업의 시작 이벤트가 창 밖에 있을 수 있기 때문이다. 못 찾은 것은 `unpaired` 로 알린다 —
- * 평균에서 조용히 빠지면 지표가 거짓이 된다.
+ * 평균에서 오류 없이 빠지면 지표가 거짓이 된다.
  *
  * 시간축은 `eventTime`(ISO) 차분이다. sim 클록이 실제 시각과 오프셋이 있어도 **차분은 정확**하다
  * (고정 오프셋은 상쇄된다). 파싱 불가한 줄은 버린다.
@@ -676,7 +950,7 @@ export function foldKpi(events: KpiEvent[], window: KpiWindow, options: KpiFoldO
        * **끝났나는 커널이 답한다** (2026-08-23) — `isOrderTerminal`.
        *
        * 예전에는 여기서 **동의어 목록**으로 추론했다(`completed`·`fulfilled`·`done`·`finished`).
-       * 그 방식이 낸 대가가 둘이었고 둘 다 조용했다.
+       * 그 방식이 낸 대가가 둘이었고 둘 다 들어온 것이 없었다.
        *
        *  ① 원본의 낱말이 목록에 없으면 완료가 0 이 된다. 실제로 그랬다 — 첫 실 시스템의 `FINISHED`
        *     가 빠져 있었고, 그때 목록에 낱말을 더한 것은 진짜 빈 자리(그 커넥터가 자기 상태 표를
@@ -693,7 +967,7 @@ export function foldKpi(events: KpiEvent[], window: KpiWindow, options: KpiFoldO
       if (at >= window.fromMs && at <= window.toMs) {
         /*
          * **오더당 한 번만 센다.** 폴링하는 원본은 같은 오더의 종결을 여러 주기에 걸쳐 다시 보낼 수
-         * 있고(그것은 결함이 아니라 폴링의 성질이다), 사건마다 세면 처리량이 조용히 부풀려진다.
+         * 있고(그것은 결함이 아니라 폴링의 성질이다), 사건마다 세면 처리량이 알리지 않고 부풀려진다.
          * 작업 쪽은 커널의 짝맞춤이 이미 그 규율을 갖고 있다(「완료는 작업당 하나」) — 오더만 없었다.
          */
         if (done) {
@@ -701,7 +975,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 +1018,65 @@ export function foldKpi(events: KpiEvent[], window: KpiWindow, options: KpiFoldO
     })
     .filter(w => Number.isFinite(w.startMs) && Number.isFinite(w.endMs))
 
+  /*
+   * 발전 기간 사실 — 커널이 기간을 마감할 때 낸 것이다. 구간 마감과 같은 규칙으로 **창에 온전히 든
+   * 것만** 센다(걸친 기간을 반만 세면 합이 창을 넘는다).
+   *
+   * 관측 구간(`observedFrom`·`observedTo`)을 함께 읽는다 — 값의 근거가 얼마나 덮였는지가 그 둘에 있다.
+   */
+  const generationPeriods = 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 = 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),
+        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 === 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 leads: number[] = []
   const works: number[] = []
   const waits: number[] = []
@@ -785,18 +1118,47 @@ 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 billingDemand = billingDemandOf(
+            bills.filter(b => Number.isFinite(b.billingDemandKW)).map(b => ({ endMs: b.endMs, billingDemandKW: b.billingDemandKW })),
+            options.lastBill,
+            options.tariff?.billingDemandKW
+          )
+          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 +1175,13 @@ 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 }),
+              /* 청구서는 사실이다 — 우리 계산을 덮지 않고 나란히 둔다(§`billOfWindow`). */
+              ...(() => {
+                const b = billOfWindow(bills, { startMs: window.fromMs, endMs: window.toMs }, cost as any)
+                return b ? { bill: b } : {}
+              })()
             }
           }
         })()
@@ -876,7 +1244,7 @@ export function crossGroups(
 
 /* ── 시간 비교 ──────────────────────────────────────────────────────────────
  * 숫자 하나로는 좋아졌는지 나빠졌는지 알 수 없다("29초" 가 개선인지 악화인지). 같은 길이의 창을 옮겨
- * 한 번 더 접으면 되므로(폴드는 순수) 값싸다. 창 옮기기와 차이 계산은 계산 규칙이라 여기 있다 —
+ * 한 번 더 계산하면 되므로(폴드는 순수) 값싸다. 창 옮기기와 차이 계산은 계산 규칙이라 여기 있다 —
  * 조회 층에 두면 테스트가 DB 를 끌고 와야 한다.
  */
 
@@ -913,7 +1281,7 @@ export interface KpiBucket {
 }
 
 /**
- * 창을 N 등분해 구간별로 접는다 — **같은 이벤트를 창만 바꿔** 다시 접는다(조회 추가 없음).
+ * 창을 N 등분해 구간별로 처리한다 — **같은 이벤트를 창만 바꿔** 다시 계산한다(조회 추가 없음).
  *
  * 마지막 구간은 나머지를 흡수한다(부동소수 나눗셈으로 끝이 밀리면 마지막 완료가 빠진다).
  * `count <= 1` 이면 쪼갤 것이 없으므로 빈 배열 — 호출부가 "추세 없음" 으로 다룬다.