@things-factory/headless-twin 10.0.14 → 10.0.17

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

@@ -19,6 +19,8 @@ exports.computeTwinKpi = computeTwinKpi;
  * 어떤 기준을 썼는지는 결과의 `window.basis` 로 밝힌다 — 숨기면 사용자가 숫자를 오해한다.
  */
 const log_js_1 = require("./log.js");
+const event_type_split_shape_js_1 = require("../service/twin-journal/event-type-split-shape.js");
+const read_time_js_1 = require("./read-time.js");
 const typeorm_1 = require("typeorm");
 const twin_kernel_1 = require("@operato/twin-kernel");
 const shell_1 = require("@things-factory/shell");
@@ -39,16 +41,24 @@ const kpi_baseline_js_1 = require("./kpi-baseline.js");
  * 나눈 값이라, 두 사실이 한 폴드에 들어와야 창이 어긋날 수 없다. 표본(`energy.measured`)은 읽지 않는다 —
  * 저널에 없고(§4.1 인제스트 계약) 여기서 필요한 것은 마감된 구간뿐이다.
  */
-const BUSINESS_EVENTS = ['task.status', 'order.status', 'energy.demand.window'];
-/** 한 번에 접을 이벤트 상한 — 큰 구간이 서버를 붙잡지 않게. */
+const BUSINESS_EVENTS = ['task.status', 'order.status', 'energy.demand.window', 'energy.generation.period', 'energy.usage.period', 'energy.bill'];
+/** 한 번에 계산할 이벤트 상한 — 큰 구간이 서버를 붙잡지 않게. */
 const MAX_EVENTS = 20000;
+/**
+ * 종류를 나눠 물을 때 만들 갈래 수의 상한 — 대상 × 종류.
+ *
+ * 갈래마다 상한(`MAX_EVENTS`)까지 받아야 합친 결과가 정확하다(§`mergeStreams`). 그래서 갈래가 늘면
+ * 메모리가 그만큼 든다. 셋(종류) × 둘(트윈)까지는 최악에 12만 행이고, 그 이상은 예전 한 질의로 간다 —
+ * 느리지만 답은 같다.
+ */
+const KPI_MAX_SPLIT = 6;
 /**
  * 노드 → 구역 지도. **저널에는 구역이 없다**(노드까지만 있다) — 모델 정의의 `locations[].parentId` 가
  * 마스터 계층에서 온 소속이다. 기동하지 않은 트윈도 모델은 남아 있어 이 경로가 가장 튼튼하다.
  *
  * **한 홉만 보면 안 된다.** `parentId` 는 구역일 수도 있고 중간 단(라인·셀)일 수도 있다. 라인이 끼면
  * 한 홉짜리 코드는 "구역이 LINE-1" 이라고 답하고, 그 id 는 구역 목록에 없으므로 그 아래 스테이션이
- * **집계에서 조용히 빠진다**(에러 없이 틀린 숫자). 그래서 커널 `hierarchyOf` 로 사슬을 끝까지 걷는다 —
+ * **집계에서 오류 없이 빠진다**(에러 없이 틀린 숫자). 그래서 커널 `hierarchyOf` 로 사슬을 끝까지 걷는다 —
  * 걷는 규칙은 커널에 한 벌뿐이고 소비처는 그것만 부른다.
  */
 /**
@@ -170,7 +180,7 @@ async function locationAreaMap(domainId, instanceIds, spaceId) {
  *
  * 여러 에너지 트윈이 한 현장에 있으면 **처음 선언된 것 하나**를 쓴다. 평균을 내거나 합치지 않는다:
  * 요금은 계약이고, 두 계약을 섞은 단가는 어느 계약도 아니다. 서로 다른 단가가 선언돼 있으면 그것을
- * 밝힌다(조용히 하나를 고르면 왜 그 금액인지 아무도 설명할 수 없다).
+ * 밝힌다(알리지 않고 하나를 고르면 왜 그 금액인지 아무도 설명할 수 없다).
  */
 async function tariffOf(domainId, instanceIds) {
     if (!instanceIds.length)
@@ -188,12 +198,15 @@ async function tariffOf(domainId, instanceIds) {
             };
             const d = num(twin_kernel_1.EMS_PROPERTY.demandChargePerKW);
             const e = num(twin_kernel_1.EMS_PROPERTY.energyChargePerKWh);
+            /* 요금적용전력 — 있으면 기본요금이 조건부 파생이 아니라 사실이 된다(§`electricityCost`). */
+            const b = num(twin_kernel_1.EMS_PROPERTY.billingDemandKW);
             const cur = props.get(twin_kernel_1.EMS_PROPERTY.currency);
             if (d === undefined && e === undefined)
                 continue;
             found.push({
                 ...(d !== undefined ? { demandChargePerKW: d } : {}),
                 ...(e !== undefined ? { energyChargePerKWh: e } : {}),
+                ...(b !== undefined ? { billingDemandKW: b } : {}),
                 ...(cur ? { currency: String(cur) } : {})
             });
         }
@@ -201,7 +214,10 @@ async function tariffOf(domainId, instanceIds) {
     if (!found.length)
         return {};
     const first = found[0];
-    const same = found.every(t => t.demandChargePerKW === first.demandChargePerKW && t.energyChargePerKWh === first.energyChargePerKWh && t.currency === first.currency);
+    const same = found.every(t => t.demandChargePerKW === first.demandChargePerKW &&
+        t.energyChargePerKWh === first.energyChargePerKWh &&
+        t.billingDemandKW === first.billingDemandKW &&
+        t.currency === first.currency);
     return { tariff: first, ...(same ? {} : { conflict: true }) };
 }
 async function resourceFeederMap(domainId, instanceIds) {
@@ -267,11 +283,33 @@ async function resourceFeederMap(domainId, instanceIds) {
     return { resourceFeeder, meterFeeder, labels };
 }
 /**
- * 이 공간의 에너지 트윈들의 계통도 — 모델을 읽어 트리로 접는다.
+ * 이 공간의 에너지 트윈들의 계통도 — 모델을 읽어 트리로 처리한다.
  *
  * 여러 트윈이 한 공간에 있으면 **각 트윈의 뿌리를 나란히** 둔다(하나로 합치면 없는 결선을 그리게 된다).
  * 에너지 트윈이 없으면 만들지 않는다 — 빈 그림은 고장으로 읽힌다.
  */
+/**
+ * 이 트윈들이 이어받고 있는 **마지막 청구서** — 요금적용전력의 우선 근거.
+ *
+ * 저널이 아니라 상태에서 읽는 이유: 청구는 한 달에 한 번이라 하루 창의 조회에는 걸리지 않는다.
+ * 그런데 그 값은 **그 창에도 적용된다**(요금 제도가 그렇게 군다). 커널이 재기동에서도 이어받으므로
+ * 상태가 그 자리다.
+ *
+ * 트윈이 여럿이면 가장 늦게 끝난 것을 쓴다 — 현장 하나에 청구가 여럿이면 그것은 다른 문제이고,
+ * 여기서 골라 감추지 않는다.
+ */
+function latestBillOf(domainId, instanceIds) {
+    let best;
+    for (const instanceId of instanceIds) {
+        const bill = twin_engine_js_1.TwinEngine.snapshot(domainId, instanceId)?.energy?.lastBill;
+        if (!bill?.to)
+            continue;
+        if (!best || Date.parse(bill.to) > Date.parse(best.to)) {
+            best = { to: String(bill.to), ...(Number.isFinite(Number(bill.billingDemandKW)) ? { billingDemandKW: Number(bill.billingDemandKW) } : {}) };
+        }
+    }
+    return best;
+}
 async function energyTopologyOf(domainId, instanceIds, energy) {
     if (!instanceIds.length)
         return undefined;
@@ -294,16 +332,46 @@ async function energyTopologyOf(domainId, instanceIds, energy) {
     }
     return merged.roots.length ? merged : undefined;
 }
-/** 이 대상들의 마지막 업무 기록 시각(ISO). 기록이 없으면 null. */
+/**
+ * 이 대상들의 **마지막 업무 기록 시각**(ISO). 기록이 없으면 null.
+ *
+ * ── 두 가지를 함께 고쳤다 (2026-08-28 실측) ─────────────────────────────────
+ * 예전 판은 이랬다.
+ *
+ *   findOne({ where: { domain: { id }, instanceId: In(…), eventType: In(셋) }, order: { revision: 'DESC' } })
+ *
+ * **① 관계로 물어 두 단계 질의가 된다.** 안쪽에 상한이 없어 조건에 맞는 행을 **전부 만든 뒤** 하나를
+ * 고른다 — 그 트윈의 업무 사실이 97만 행이고 `payload` 까지 실려 온다. 이 파일의 다른 자리가 같은 것을
+ * 실측해 적어 두었다(§`twinEvents`: 0.024초 대 12초). 서버 로그에 「느린 질의」로 찍혀 있던 것이
+ * 이것이고, 현장 성과 화면의 7.2초가 여기서 나왔다.
+ *
+ * **② 「마지막 시각」을 원하면서 `revision` 으로 정렬했다.** 그 둘은 어긋난다 — 연결된 시스템을 되읽는
+ * 트윈은 원본의 시각을 싣고 도착 순서로 리비전을 받으므로, 리비전이 가장 큰 행이 4월 사실일 수 있다
+ * (같은 어긋남을 오늘 저널 목록에서도 고쳤다). 창의 끝을 그 값으로 잡으면 **창 자체가 틀린다.**
+ *
+ * 지금은 종류마다 `MAX(eventTime)` 을 묻는다. `(domain, instance, event_type, event_time)` 색인의
+ * 끝을 집으므로 종류당 한 번이고, 셋 중 가장 늦은 것이 답이다.
+ */
 async function latestEventTime(domainId, instanceIds) {
     if (instanceIds.length === 0)
         return null;
-    const row = await (0, shell_1.getRepository)(twin_event_js_1.TwinEvent).findOne({
-        where: { domain: { id: domainId }, instanceId: (0, typeorm_1.In)(instanceIds), eventType: (0, typeorm_1.In)(BUSINESS_EVENTS) },
-        order: { revision: 'DESC' }
-    });
-    /* 소비처는 ISO 문자열을 기대한다(시각 축의 공용 표기) — 컬럼이 날짜가 됐으므로 여기서 옮긴다. */
-    return row?.eventTime ? row.eventTime.toISOString() : null;
+    const rows = await Promise.all(instanceIds.flatMap(instanceId => BUSINESS_EVENTS.map(eventType => (0, shell_1.getReadRepository)(twin_event_js_1.TwinEvent)
+        .createQueryBuilder('e')
+        .select('MAX(e.eventTime)', 'at')
+        .where('e.domain = :domainId', { domainId })
+        .andWhere('e.instanceId = :instanceId', { instanceId })
+        .andWhere('e.eventType = :eventType', { eventType })
+        .getRawOne()
+        .catch(() => null))));
+    /* 드라이버가 준 값은 시간대가 없을 수 있다 — 컬럼 변환을 지나게 한다(§`hydratedDate`). */
+    const repo = (0, shell_1.getReadRepository)(twin_event_js_1.TwinEvent);
+    let latest = null;
+    for (const r of rows) {
+        const at = (0, read_time_js_1.hydratedDate)(repo, 'eventTime', r?.at);
+        if (at && (!latest || at.getTime() > latest.getTime()))
+            latest = at;
+    }
+    return latest ? latest.toISOString() : null;
 }
 /**
  * 창 구간의 업무 이벤트 — 창보다 `lookbackMs` 만큼 앞까지 읽는다(완료된 작업의 시작이 창 밖일 수 있다).
@@ -369,23 +437,79 @@ async function fetchEvents(domainId, instanceIds, fromMs, toMs, lookbackMs) {
      * 남는 비용을 감추지 않는다: `payload` 파싱은 여전히 메인 스레드 일이고 연결을 나눠도 나뉘지 않는다
      * (실측 평균 1.5초). 그것을 더 줄이려면 폴드가 payload 에서 무엇을 쓰는지 좁혀야 한다 — 별 건이다.
      */
-    const raw = await (0, shell_1.getReadRepository)(twin_event_js_1.TwinEvent)
+    const from = new Date(fromMs - lookbackMs);
+    const to = new Date(toMs);
+    /**
+     * 한 갈래를 묻는다 — **종류를 정확일치로** 준다. 그것이 이 고침의 요점이다.
+     */
+    const readOne = (instanceId, eventType) => (0, shell_1.getReadRepository)(twin_event_js_1.TwinEvent)
         .createQueryBuilder('e')
-        .select(['e.eventType AS "eventType"', 'e.eventTime AS "eventTime"', 'e.payload AS "payload"'])
+        .select(['e.eventType AS "eventType"', 'e.eventTime AS "eventTime"', 'e.revision AS "revision"', 'e.payload AS "payload"'])
         .where('e.domain = :domainId', { domainId })
-        .andWhere('e.instanceId IN (:...instanceIds)', { instanceIds })
-        .andWhere('e.eventType IN (:...types)', { types: BUSINESS_EVENTS })
-        .andWhere('e.eventTime BETWEEN :from AND :to', { from: new Date(fromMs - lookbackMs), to: new Date(toMs) })
+        .andWhere('e.instanceId = :instanceId', { instanceId })
+        .andWhere('e.eventType = :eventType', { eventType })
+        .andWhere('e.eventTime BETWEEN :from AND :to', { from, to })
         .orderBy('e.eventTime', 'ASC')
         .addOrderBy('e.revision', 'ASC')
         .limit(MAX_EVENTS)
         .getRawMany();
-    /* 상한에 정확히 닿으면 **더 있었을 수 있다** — 그 사실을 돌려준다. 조용히 잘라내면 숫자가 조용히
+    /*
+     * ── **종류를 나눠 묻는다** (2026-08-28 실측) ────────────────────────────────
+     *
+     * 예전에는 `eventType IN (셋)` + 시각 범위 + 시각순이었다. 그 모양에서 sqlite 는 종류 색인을 버리고
+     * 시각 색인으로 **구간 전체를 걸으며 행마다 종류를 확인한다.** 승화푸드(저널 3,140만행) 실측:
+     *
+     *   창 1시간    구간 안 0행 · 쓰는 행 0          40밀리초
+     *   창 24시간   구간 안 254,185행 · 쓰는 행 0   3,776밀리초   ← 25만 행을 걸어 0건을 쓴다
+     *   창 7일      구간 안 2,070,625행 · 34,143    173밀리초    ← 상한에 일찍 닿아 오히려 빠르다
+     *
+     * 창을 넓히면 빨라지는 것 자체가 신호였다. 종류를 정확일치로 물으면
+     * `ix_twin_event_7 (domain, instance, event_type, event_time)` 이 범위까지 색인에서 준다.
+     *
+     * 나눌 수를 제한한다 — 갈래마다 상한까지 받아야 정확하므로(§`mergeStreams`) 갈래가 많으면 메모리가
+     * 그만큼 든다. 넘으면 예전 한 질의로 간다(느리지만 답은 같다).
+     */
+    const pairs = instanceIds.length * BUSINESS_EVENTS.length;
+    let raw;
+    let mergedCapped = false;
+    if (pairs && pairs <= KPI_MAX_SPLIT) {
+        const streams = await Promise.all(instanceIds.flatMap(instanceId => BUSINESS_EVENTS.map(eventType => readOne(instanceId, eventType))));
+        const merged = (0, event_type_split_shape_js_1.mergeStreams)(streams, MAX_EVENTS, (a, b) => {
+            const at = String(a.eventTime ?? '').localeCompare(String(b.eventTime ?? ''));
+            if (at !== 0)
+                return at;
+            return Number(a.revision ?? 0) - Number(b.revision ?? 0);
+        });
+        if (merged.underfilled) {
+            /* 있을 수 없는 일이다 — 갈래가 상한보다 많이 받아 왔다. 조용히 쓰지 않고 말한다. */
+            (0, log_js_1.twinWarn)('[twin-kpi] a per-type stream returned more than the cap — the merge cannot be trusted; falling back');
+            raw = [];
+        }
+        else {
+            raw = merged.items;
+            mergedCapped = merged.capped;
+        }
+    }
+    else {
+        raw = await (0, shell_1.getReadRepository)(twin_event_js_1.TwinEvent)
+            .createQueryBuilder('e')
+            .select(['e.eventType AS "eventType"', 'e.eventTime AS "eventTime"', 'e.revision AS "revision"', 'e.payload AS "payload"'])
+            .where('e.domain = :domainId', { domainId })
+            .andWhere('e.instanceId IN (:...instanceIds)', { instanceIds })
+            .andWhere('e.eventType IN (:...types)', { types: BUSINESS_EVENTS })
+            .andWhere('e.eventTime BETWEEN :from AND :to', { from, to })
+            .orderBy('e.eventTime', 'ASC')
+            .addOrderBy('e.revision', 'ASC')
+            .limit(MAX_EVENTS)
+            .getRawMany();
+        mergedCapped = raw.length >= MAX_EVENTS;
+    }
+    /* 상한에 정확히 닿으면 **더 있었을 수 있다** — 그 사실을 돌려준다. 알리지 않고 잘라내면 숫자가 알리지 않고
      * 작아지고, 사용자는 그것을 성과 하락으로 읽는다(가장 나쁜 종류의 거짓이다). */
     return {
         /* 폴드는 ISO 문자열 축으로 수행된다(kpi-fold) — 경계에서 한 번만 옮긴다. */
         events: raw.map(r => ({ eventType: r.eventType, eventTime: isoOf(r.eventTime), payload: jsonOf(r.payload) })),
-        capped: raw.length >= MAX_EVENTS
+        capped: mergedCapped
     };
 }
 /**
@@ -425,8 +549,30 @@ function jsonOf(v) {
 /**
  * 집계 대상 트윈 목록.
  *
- * 공간이 주어지면 **가동 중이고 운영 목적인** 것만 모은다 — 벤치 사본은 사용자가 보는 현장이 아니다.
+ * 공간이 주어지면 그 공간의 **운영 목적** 트윈을 모은다 — 벤치 사본은 사용자가 보는 현장이 아니다.
  * 트윈이 지정되면 그것 하나. 둘 다 없으면 무엇을 재야 할지 알 수 없으므로 명시 실패한다.
+ *
+ * ── **「지금 도는가」로 걸러내지 않는다** (2026-08-28 실측) ──────────────────
+ * 여기에 `running` 조건이 있었다. 그래서 멈춘 트윈은 현장으로 물었을 때 대상에서 빠졌고, 화면은
+ * 「기록이 없습니다」라고 말했다 — **저널에는 있는데.**
+ *
+ *   twinEventList(instanceId: "ems-plant-1")      1,792건
+ *   twinEventList(spaceId:    "ems-plant-1-site")     0건   ← 같은 트윈, 같은 도메인
+ *
+ * 규모로 보면 이것은 예외가 아니라 기본값이었다: 등록된 트윈 30개 중 **도는 것이 2개, 멈춘 것이 28개**다.
+ * 즉 현장으로 묻는 저널 조회가 대부분의 현장에서 거짓 「없다」를 냈다.
+ *
+ * 지운 이유는 두 가지다.
+ *
+ *  ① **저널은 기록이고, 프로세스가 지금 도는지는 다른 축이다.** 창 안에 있는 사실은 사실이다.
+ *     아래 줄이 트윈을 지정한 경우에 대해 이미 그 원칙을 적어 두었다(「정지·비등록이어도 저널은 남아
+ *     있을 수 있다」). 같은 원칙이 현장 경로에만 적용되지 않고 있었다.
+ *  ② 옛 주석이 대는 이유(「벤치 사본은 사용자가 보는 현장이 아니다」)는 **벤치 제외만** 설명한다.
+ *     `running` 에는 근거가 적혀 있지 않았다.
+ *
+ * **바뀌는 것**: 현장 KPI 가 이제 멈춘 트윈의 지난 기록도 센다. 창 안의 사실을 세는 것이 그 지표의
+ * 정의이므로 그것이 맞다. 「지금 도는 것만」이 필요한 화면이 생기면 그때 **이름 있는 축**으로 받는다 —
+ * 여기에 숨겨 두면 두 물음이 한 칸을 쓴다.
  */
 async function resolveTargets(input) {
     if (!input.instanceId && !input.spaceId)
@@ -434,7 +580,7 @@ async function resolveTargets(input) {
     const list = await twin_engine_js_1.TwinEngine.list(input.domainId);
     const rows = input.instanceId
         ? list.filter((x) => x?.instanceId === input.instanceId)
-        : list.filter((x) => x?.running && x.spaceId === input.spaceId && x.purpose !== 'bench' && x.instanceId);
+        : list.filter((x) => x?.spaceId === input.spaceId && x.purpose !== 'bench' && x.instanceId);
     /* 목록에서 못 찾아도(정지·비등록) 지정된 트윈은 그대로 조회한다 — 저널은 남아 있을 수 있다. */
     const instanceIds = rows.length ? rows.map((x) => x.instanceId) : input.instanceId ? [input.instanceId] : [];
     /* 컬럼이 NOT NULL 이라 'unknown' 으로 메울 일이 없다 — 비면 계약이 깨진 것이지 모르는 상태가 아니다. */
@@ -500,12 +646,23 @@ async function computeTwinKpi(input) {
     const feederMap = await resourceFeederMap(input.domainId, instanceIds);
     /* 요금 단가도 축과 무관하게 읽는다 — 금액은 같은 창의 전력량·최대수요에서 나오는 사실이다. */
     const tariffFound = await tariffOf(input.domainId, instanceIds);
+    /*
+     * ── 요금적용전력은 **청구서가 먼저다** (2026-08-29) ─────────────────────────
+     *
+     * 그 값은 최근 몇 달의 최고 수요로 **매달 다시 정해진다.** 선언에 박아 두면 매달 사람이 갱신해야
+     * 하고, 안 하면 낡은 값으로 기본요금이 조용히 틀린다.
+     *
+     * 원본이 청구서에 그 값을 실어 매일 보낸다. 창 밖의 청구서는 저널 조회에 걸리지 않으므로
+     * **커널 상태에 이어져 있는 마지막 청구서**를 함께 넘긴다(§`EnergyState.lastBill`).
+     */
+    const lastBill = latestBillOf(input.domainId, instanceIds);
     const kpi = (0, kpi_fold_js_1.foldKpi)(events, { fromMs, toMs }, {
         groupBy: input.groupBy,
         locationArea: areaMap.locationArea,
         resourceFeeder: feederMap.resourceFeeder,
         meterFeeder: feederMap.meterFeeder,
         ...(tariffFound.tariff ? { tariff: tariffFound.tariff } : {}),
+        ...(lastBill ? { lastBill } : {}),
         ...shiftCtx,
         groupLimit: input.groupLimit
     });
@@ -514,14 +671,14 @@ async function computeTwinKpi(input) {
      *
      * 폴드는 순수하다(로그를 모른다) — 그래서 부르는 쪽이 말한다. 왜 말해야 하나: 이 폴드는 오더의
      * 완료를 **동의어 목록**으로 판정하고, 그것은 원본의 낱말에서 뜻을 추론하는 것이다. 커넥터가
-     * 자기 표로 옮기지 않으면 그 낱말이 목록에 없어 **완료가 조용히 0 으로 세어진다.**
+     * 자기 표로 옮기지 않으면 그 낱말이 목록에 없어 **완료가 알리지 않고 0 으로 세어진다.**
      *
      * 실제로 그랬다: 첫 실 원본의 `FINISHED` 가 목록에 없어 완료 오더가 전부 0 이었고, 사람이 화면을
      * 보고 의심해서야 드러났다(그 커넥터에는 상태 표가 정의돼 **있으면서** 오더 경로에서 쓰이지 않았다).
      * 그때 목록에 낱말을 더한 것은 그 사실을 가린 땜빵이었다.
      *
      * 그러니 이 로그는 「목록을 늘려라」가 아니라 **「그 커넥터가 옮기지 않았다」**를 뜻한다. 화면을 보지
-     * 않는 사람도 알아야 하므로 로그에 남긴다 — 조용한 0 이 이 시스템에서 가장 비싼 침묵이다.
+     * 않는 사람도 알아야 하므로 로그에 남긴다 — 들어온 것이 없는 0 이 이 시스템에서 가장 비싼 침묵이다.
      *
      * 완료가 하나도 없을 때만 말한다: `picking` 처럼 완료가 아닌 낱말이 섞여 있는 것은 정상이고,
      * 그것까지 매번 경고하면 진짜 신호가 묻힌다.
@@ -561,7 +718,7 @@ async function computeTwinKpi(input) {
         for (const w of windows) {
             const { events: pastEvents, capped: pastCapped } = await fetchEvents(input.domainId, instanceIds, w.fromMs, w.toMs, lookbackMs);
             baseCapped = baseCapped || pastCapped;
-            /* 축 없이, **같은 교대 정의**로 접는다(정의가 다르면 같은 시간대가 아니게 된다). */
+            /* 축 없이, **같은 교대 정의**로 처리한다(정의가 다르면 같은 시간대가 아니게 된다). */
             const past = (0, kpi_fold_js_1.foldKpi)(pastEvents, w, { locationArea: areaMap.locationArea, ...shiftCtx });
             const values = {};
             for (const metric of Object.keys(kpi_target_js_1.TWIN_METRIC))
@@ -599,7 +756,7 @@ async function computeTwinKpi(input) {
             workP50Ms: b.workP50Ms
         }))
         : undefined;
-    /* 비교 구간 — **같은 길이·같은 규칙**으로 한 번 더 접는다. 기록이 없으면 delta 를 만들지 않는다
+    /* 비교 구간 — **같은 길이·같은 규칙**으로 한 번 더 계산한다. 기록이 없으면 delta 를 만들지 않는다
      * (없는 것을 0 으로 그리면 "변화 없음" 이라는 거짓이 된다). */
     let comparison;
     /* 관점 × 비교 교차 — 축별 delta 와 **사라진 축**(전에 있었고 지금 없는 것). */
@@ -609,13 +766,13 @@ async function computeTwinKpi(input) {
     if (input.compareTo === 'previous' || input.compareTo === 'yesterday') {
         const w = (0, kpi_fold_js_1.shiftWindow)(fromMs, toMs, input.compareTo);
         const { events: prevEvents, capped: prevCapped } = await fetchEvents(input.domainId, instanceIds, w.fromMs, w.toMs, lookbackMs);
-        /* 축이 요청됐으면 비교 구간도 **같은 축**으로 접는다 — 교차("구역별로 어제 대비")를 내기 위해.
+        /* 축이 요청됐으면 비교 구간도 **같은 축**으로 처리한다 — 교차("구역별로 어제 대비")를 내기 위해.
          * 상한은 축이 서로 어긋나지 않게 넉넉히 둔다(현재 축이 상한 안에 있는데 비교 축에서 밀려나면
          * 있는데 없다고 말하게 된다). */
         const prev = (0, kpi_fold_js_1.foldKpi)(prevEvents, w, {
             groupBy: input.groupBy,
             locationArea: areaMap.locationArea,
-            ...shiftCtx, // 비교 구간도 **같은 교대 정의**로 접는다(정의가 다르면 축이 어긋난다)
+            ...shiftCtx, // 비교 구간도 **같은 교대 정의**로 처리한다(정의가 다르면 축이 어긋난다)
             groupLimit: input.groupBy ? 100 : undefined
         });
         prevCappedFlag = prevCapped;