@things-factory/headless-twin 10.0.8 → 10.0.10

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

@@ -28,14 +28,22 @@ const twin_space_js_1 = require("../service/twin-space/twin-space.js");
 const twin_target_js_1 = require("../service/twin-target/twin-target.js");
 const kpi_target_js_1 = require("./kpi-target.js");
 const twin_engine_js_1 = require("./twin-engine.js");
+const energy_topology_js_1 = require("./energy-topology.js");
 const kpi_fold_js_1 = require("./kpi-fold.js");
-/** 업무 전이만 읽는다 — 설비 상태(equipment.status)는 OEE 누적기의 몫이고 여기선 쓰지 않는다. */
-const BUSINESS_EVENTS = ['task.status', 'order.status'];
+const kpi_baseline_js_1 = require("./kpi-baseline.js");
+/**
+ * 업무 전이만 읽는다 — 설비 상태(equipment.status)는 OEE 누적기의 몫이고 여기선 쓰지 않는다.
+ *
+ * **에너지 구간 마감**은 함께 읽는다(2026-08-14): 원단위는 분자(전력량)와 분모(산출)를 **같은 창**에서
+ * 나눈 값이라, 두 사실이 한 폴드에 들어와야 창이 어긋날 수 없다. 표본(`energy.measured`)은 읽지 않는다 —
+ * 저널에 없고(§4.1 인제스트 계약) 여기서 필요한 것은 마감된 구간뿐이다.
+ */
+const BUSINESS_EVENTS = ['task.status', 'order.status', 'energy.demand.window'];
 /** 한 번에 접을 이벤트 상한 — 큰 구간이 서버를 붙잡지 않게. */
 const MAX_EVENTS = 20000;
 /**
- * 노드 → 구역 지도. **저널에는 구역이 없다**(노드까지만 있다) — 보드 정의의 `locations[].parentId` 가
- * 마스터 계층에서 온 소속이다. 기동하지 않은 트윈도 보드는 남아 있어 이 경로가 가장 튼튼하다.
+ * 노드 → 구역 지도. **저널에는 구역이 없다**(노드까지만 있다) — 모델 정의의 `locations[].parentId` 가
+ * 마스터 계층에서 온 소속이다. 기동하지 않은 트윈도 모델은 남아 있어 이 경로가 가장 튼튼하다.
  *
  * **한 홉만 보면 안 된다.** `parentId` 는 구역일 수도 있고 중간 단(라인·셀)일 수도 있다. 라인이 끼면
  * 한 홉짜리 코드는 "구역이 LINE-1" 이라고 답하고, 그 id 는 구역 목록에 없으므로 그 아래 스테이션이
@@ -48,11 +56,11 @@ const MAX_EVENTS = 20000;
  * 저널에는 시각만 있고 교대가 없다(일부러 그렇게 뒀다 — 교대는 파생이라 찍어 두면 나중에 교대 시간을
  * 고쳤을 때 과거가 옛 구분으로 굳는다). 그래서 폴드가 계산할 재료를 여기서 모은다.
  *
- * 선언의 출처는 **보드의 설비**다. 여러 설비가 서로 다른 교대를 가질 수 있지만, 축은 하나여야 하므로
+ * 선언의 출처는 **모델의 설비**다. 여러 설비가 서로 다른 교대를 가질 수 있지만, 축은 하나여야 하므로
  * **가장 많이 쓰이는 선언 한 벌**을 쓴다 — 3교대 공장은 전 설비가 같은 교대이므로 이것이 곧 정답이고,
  * 자원마다 교대가 다른 현장에서는 이 축이 거칠다는 뜻이다(그 사실을 여기 적어 둔다).
  *
- * 시각 기준은 보드에 실려 있다(`utcOffsetMinutes` — 공간이 갖는 값을 기동 시 호스트가 풀어 넣는다).
+ * 시각 기준은 모델에 실려 있다(`utcOffsetMinutes` — 공간이 갖는 값을 기동 시 호스트가 풀어 넣는다).
  * 없으면 UTC 로 읽고, 그 기본값은 커널 계약에 밝혀져 있다.
  */
 /**
@@ -74,10 +82,10 @@ async function shiftContext(domainId, instanceIds) {
     const tally = new Map();
     let utcOffsetMinutes;
     for (const row of rows) {
-        const board = row.board;
-        if (utcOffsetMinutes === undefined && typeof board?.utcOffsetMinutes === 'number')
-            utcOffsetMinutes = board.utcOffsetMinutes;
-        for (const e of (board?.equipment ?? [])) {
+        const model = row.model;
+        if (utcOffsetMinutes === undefined && typeof model?.utcOffsetMinutes === 'number')
+            utcOffsetMinutes = model.utcOffsetMinutes;
+        for (const e of (model?.equipment ?? [])) {
             const decl = e?.workCalendar;
             if (!Array.isArray(decl) || !decl.length)
                 continue;
@@ -102,13 +110,18 @@ async function locationAreaMap(domainId, instanceIds, spaceId) {
             where: { domain: { id: domainId }, instanceId: (0, typeorm_1.In)(instanceIds) }
         });
         for (const row of rows) {
-            const locations = (row.board?.locations ?? []).filter(n => n?.id);
+            const locations = (row.model?.locations ?? []).filter(n => n?.id);
             if (!locations.length)
                 continue;
             /* 순환은 hierarchyOf 가 던진다 — 한 트윈의 잘못된 계층이 다른 트윈의 집계까지 죽이지 않게 여기서 가둔다. */
             let h;
             try {
-                h = (0, twin_kernel_1.hierarchyOf)({ locations });
+                /*
+                 * 단 해석기를 함께 넘긴다 — 자리가 `level` 을 적지 않으면 **타입이 답한다**(카탈로그 선언).
+                 * 이 집계는 지금 구역 롤업(`rollupOf`)만 쓰므로 결과가 달라지지 않는다. 그래도 여기서
+                 * 잇는다: 단으로 묻는 질의(`ancestorOfLevel`)가 생길 때 배선을 다시 찾지 않게 한다.
+                 */
+                h = (0, twin_kernel_1.hierarchyOf)({ locations }, t => (0, twin_kernel_1.levelOfLocationType)(t, row.kind));
             }
             catch (e) {
                 console.warn(`[twin-kpi] "${row.instanceId}": location hierarchy is broken — area rollup skipped for this twin: ${e?.message}`);
@@ -136,6 +149,150 @@ async function locationAreaMap(domainId, instanceIds, spaceId) {
     }
     return { locationArea, labels };
 }
+/**
+ * 자원 → **배전 계통의 자리**(분기·수전) 지도와 그 자리의 이름.
+ *
+ * ── 무엇을 읽나 ─────────────────────────────────────────────────────────────
+ * 에너지 트윈의 모델이 「이 설비가 어느 자리에 매달렸나」를 선언한다(`homeLocation`). 그 자리가 분기가
+ * 아니라 하위 자리라면 부모를 타고 올라가 **전기 계통의 자리**를 찾는다 — 전기의 계통은 물리 구역과
+ * 다른 나무이므로 구역 롤업(`locationAreaMap`)을 쓸 수 없다.
+ *
+ * ── 왜 에너지 트윈만 읽나 ───────────────────────────────────────────────────
+ * 같은 설비가 공장 트윈에서는 자원(작업을 한다)이고 에너지 트윈에서는 부하(전기를 먹는다)다 — 사실 둘,
+ * id 하나. 가동시간은 공장 트윈의 저널에서 오고, 전기 계통의 소속은 이 모델에서 온다. 그 둘을 id 로
+ * 잇는 것이 이 지도의 일이다.
+ *
+ * 자리를 말하지 않는 설비는 **넣지 않는다** — 없는 소속을 만들면 그 몫이 엉뚱한 분기의 것이 된다.
+ */
+/**
+ * 선언된 **전기요금 단가** — 에너지 트윈의 자리 속성에서 읽는다(계약전력과 같은 자리).
+ *
+ * 여러 에너지 트윈이 한 현장에 있으면 **처음 선언된 것 하나**를 쓴다. 평균을 내거나 합치지 않는다:
+ * 요금은 계약이고, 두 계약을 섞은 단가는 어느 계약도 아니다. 서로 다른 단가가 선언돼 있으면 그것을
+ * 밝힌다(조용히 하나를 고르면 왜 그 금액인지 아무도 설명할 수 없다).
+ */
+async function tariffOf(domainId, instanceIds) {
+    if (!instanceIds.length)
+        return {};
+    const rows = await (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance).find({ where: { domain: { id: domainId }, instanceId: (0, typeorm_1.In)(instanceIds) } });
+    const found = [];
+    for (const row of rows) {
+        if (row.kind !== 'ems')
+            continue;
+        for (const loc of (row.model?.locations ?? [])) {
+            const props = new Map((loc?.properties ?? []).map(p => [String(p?.id), p?.value]));
+            const num = (id) => {
+                const v = Number(props.get(id));
+                return Number.isFinite(v) && v > 0 ? v : undefined;
+            };
+            const d = num(twin_kernel_1.EMS_PROPERTY.demandChargePerKW);
+            const e = num(twin_kernel_1.EMS_PROPERTY.energyChargePerKWh);
+            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 } : {}),
+                ...(cur ? { currency: String(cur) } : {})
+            });
+        }
+    }
+    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);
+    return { tariff: first, ...(same ? {} : { conflict: true }) };
+}
+async function resourceFeederMap(domainId, instanceIds) {
+    const resourceFeeder = {};
+    /** 계량 지점 → 그것이 재는 분기. 있으면 그 분기 값은 **측정**이다(배분보다 강한 근거). */
+    const meterFeeder = {};
+    const labels = {};
+    if (!instanceIds.length)
+        return { resourceFeeder, meterFeeder, labels };
+    const rows = await (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance).find({ where: { domain: { id: domainId }, instanceId: (0, typeorm_1.In)(instanceIds) } });
+    for (const row of rows) {
+        if (row.kind !== 'ems')
+            continue; // 전기 계통을 선언하는 것은 에너지 트윈이다
+        const model = row.model ?? {};
+        const locations = (model.locations ?? []).filter((n) => n?.id);
+        const byId = new Map(locations.map((n) => [String(n.id), n]));
+        const electrical = new Set(twin_kernel_1.EMS_LOCATION_TYPES);
+        /**
+         * 이 자리에서 **전기 상류**로 올라가 처음 만나는 계통의 자리. 없으면 undefined.
+         *
+         * 상류의 뜻은 커널이 읽는다(`electricalUpstreamOf`) — 공간 부모(공장·구역)를 따라 올라가면 전기적으로
+         * 뜻이 없는 길을 걷게 되고, 옛 세대(분기의 `parentId` 에 수전)와 새 세대(`upstreamId`)가 섞여 있으므로
+         * 그 판정을 여기서 다시 쓰면 두 벌이 된다.
+         */
+        const feederOf = (startId) => {
+            const seen = new Set();
+            let cur = byId.get(startId);
+            while (cur && !seen.has(String(cur.id))) {
+                seen.add(String(cur.id)); // 잘못된 모델의 순환이 여기서 멈춘다
+                if (electrical.has(String(cur.type)))
+                    return String(cur.id);
+                const up = (0, twin_kernel_1.electricalUpstreamOf)(locations, String(cur.id));
+                cur = up ? byId.get(up) : cur.parentId ? byId.get(String(cur.parentId)) : undefined;
+            }
+            return undefined;
+        };
+        for (const e of (model.equipment ?? [])) {
+            const home = e?.homeLocation ?? e?.homeLocationId;
+            if (!e?.id || !home)
+                continue;
+            /*
+             * 계량기는 부하가 아니다 — 그것의 「몫」을 세면 총량이 이중으로 나뉜다. 대신 **어디를 재는지**를
+             * 따로 모은다: 계량기가 분기에 있으면 그 분기 값은 배분이 아니라 **측정**이다(가장 강한 근거).
+             */
+            if (e.kind === 'meter') {
+                const at = feederOf(String(home));
+                /* 뿌리(수전)를 재는 계량기는 분기의 것이 아니다 — 그 값은 총량이고, 나머지는 뺄셈으로 나온다. */
+                if (at && String(byId.get(at)?.type) !== 'incoming')
+                    meterFeeder[String(e.id)] = at;
+                continue;
+            }
+            /* 차단기·태양광·축전지도 부하가 아니다. */
+            if (e.kind === 'breaker' || e.kind === 'pv-array' || e.kind === 'battery')
+                continue;
+            const feeder = feederOf(String(home));
+            if (feeder)
+                resourceFeeder[String(e.id)] = feeder;
+        }
+        for (const n of locations)
+            if (electrical.has(String(n.type)) && n.name)
+                labels[String(n.id)] = String(n.name);
+    }
+    return { resourceFeeder, meterFeeder, labels };
+}
+/**
+ * 이 공간의 에너지 트윈들의 계통도 — 모델을 읽어 트리로 접는다.
+ *
+ * 여러 트윈이 한 공간에 있으면 **각 트윈의 뿌리를 나란히** 둔다(하나로 합치면 없는 결선을 그리게 된다).
+ * 에너지 트윈이 없으면 만들지 않는다 — 빈 그림은 고장으로 읽힌다.
+ */
+async function energyTopologyOf(domainId, instanceIds, energy) {
+    if (!instanceIds.length)
+        return undefined;
+    const rows = await (0, shell_1.getRepository)(twin_instance_js_1.TwinInstance).find({ where: { domain: { id: domainId }, instanceId: (0, typeorm_1.In)(instanceIds) } });
+    const ems = rows.filter(r => r.kind === 'ems' && r.model);
+    if (!ems.length)
+        return undefined;
+    const merged = { roots: [], unplaced: [], unmetered: [], loadsOnIncoming: 0 };
+    for (const row of ems) {
+        /*
+         * 지금의 설비 상태를 함께 넘긴다 — 발전·저장의 **지금 값**은 구간 폴드가 아니라 스냅샷이 안다.
+         * 없으면(정지된 트윈) 구조만 그린다.
+         */
+        const snap = twin_engine_js_1.TwinEngine.snapshot(domainId, row.instanceId);
+        const t = (0, energy_topology_js_1.buildEnergyTopology)(row.model, energy, snap?.equipment);
+        merged.roots.push(...t.roots);
+        merged.unplaced.push(...t.unplaced);
+        merged.unmetered.push(...t.unmetered);
+        merged.loadsOnIncoming += t.loadsOnIncoming;
+    }
+    return merged.roots.length ? merged : undefined;
+}
 /** 이 대상들의 마지막 업무 기록 시각(ISO). 기록이 없으면 null. */
 async function latestEventTime(domainId, instanceIds) {
     if (instanceIds.length === 0)
@@ -144,13 +301,14 @@ async function latestEventTime(domainId, instanceIds) {
         where: { domain: { id: domainId }, instanceId: (0, typeorm_1.In)(instanceIds), eventType: (0, typeorm_1.In)(BUSINESS_EVENTS) },
         order: { revision: 'DESC' }
     });
-    return row?.eventTime ?? null;
+    /* 소비처는 ISO 문자열을 기대한다(시각 축의 공용 표기) — 컬럼이 날짜가 됐으므로 여기서 옮긴다. */
+    return row?.eventTime ? row.eventTime.toISOString() : null;
 }
 /**
  * 창 구간의 업무 이벤트 — 창보다 `lookbackMs` 만큼 앞까지 읽는다(완료된 작업의 시작이 창 밖일 수 있다).
  *
- * eventTime 은 ISO 문자열 컬럼이라 사전식 비교가 성립한다(같은 파일군의 시각 커서와 동일 전제).
- * 비교 구간도 같은 규칙으로 읽어야 하므로 함수로 둔다 — 두 곳에 적으면 규칙이 갈라진다.
+ * eventTime 은 날짜 컬럼이라 DB 가 시각으로 비교한다 — 예전 문자열 컬럼 시절의 "UTC ISO 만 들어오면
+ * 사전식 비교가 맞는다" 는 전제가 필요 없다.
  */
 async function fetchEvents(domainId, instanceIds, fromMs, toMs, lookbackMs) {
     if (instanceIds.length === 0)
@@ -160,7 +318,7 @@ async function fetchEvents(domainId, instanceIds, fromMs, toMs, lookbackMs) {
             domain: { id: domainId },
             instanceId: (0, typeorm_1.In)(instanceIds),
             eventType: (0, typeorm_1.In)(BUSINESS_EVENTS),
-            eventTime: (0, typeorm_1.Between)(new Date(fromMs - lookbackMs).toISOString(), new Date(toMs).toISOString())
+            eventTime: (0, typeorm_1.Between)(new Date(fromMs - lookbackMs), new Date(toMs))
         },
         order: { revision: 'ASC' },
         take: MAX_EVENTS
@@ -168,7 +326,8 @@ async function fetchEvents(domainId, instanceIds, fromMs, toMs, lookbackMs) {
     /* 상한에 정확히 닿으면 **더 있었을 수 있다** — 그 사실을 돌려준다. 조용히 잘라내면 숫자가 조용히
      * 작아지고, 사용자는 그것을 성과 하락으로 읽는다(가장 나쁜 종류의 거짓이다). */
     return {
-        events: rows.map(r => ({ eventType: r.eventType, eventTime: r.eventTime, payload: r.payload })),
+        /* 폴드는 ISO 문자열 축으로 수행된다(kpi-fold) — 경계에서 한 번만 옮긴다. */
+        events: rows.map(r => ({ eventType: r.eventType, eventTime: r.eventTime?.toISOString(), payload: r.payload })),
         capped: rows.length >= MAX_EVENTS
     };
 }
@@ -187,7 +346,8 @@ async function resolveTargets(input) {
         : list.filter((x) => x?.running && x.spaceId === input.spaceId && x.purpose !== 'bench' && x.instanceId);
     /* 목록에서 못 찾아도(정지·비등록) 지정된 트윈은 그대로 조회한다 — 저널은 남아 있을 수 있다. */
     const instanceIds = rows.length ? rows.map((x) => x.instanceId) : input.instanceId ? [input.instanceId] : [];
-    const realityModes = [...new Set(rows.map((x) => String(x.realityMode ?? 'unknown')))];
+    /* 컬럼이 NOT NULL 이라 'unknown' 으로 메울 일이 없다 — 비면 계약이 깨진 것이지 모르는 상태가 아니다. */
+    const realityModes = [...new Set(rows.map((x) => String(x.realityMode)))];
     return { instanceIds, realityModes };
 }
 /**
@@ -242,9 +402,19 @@ async function computeTwinKpi(input) {
     /* 구역·교대 축은 **이벤트 밖의 지식**을 필요로 한다 — 다른 축은 payload 에서 바로 나온다. */
     const areaMap = input.groupBy === 'area' ? await locationAreaMap(input.domainId, instanceIds, input.spaceId) : { locationArea: {}, labels: {} };
     const shiftCtx = input.groupBy === 'shift' ? await shiftContext(input.domainId, instanceIds) : {};
+    /*
+     * 전기 계통 소속은 **축과 무관하게** 읽는다 — 분기별 몫은 관점 축이 아니라 에너지 사실의 일부라
+     * (같은 창의 총량을 나눈 것) 어느 축을 보고 있든 함께 나가야 한다.
+     */
+    const feederMap = await resourceFeederMap(input.domainId, instanceIds);
+    /* 요금 단가도 축과 무관하게 읽는다 — 금액은 같은 창의 전력량·최대수요에서 나오는 사실이다. */
+    const tariffFound = await tariffOf(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 } : {}),
         ...shiftCtx,
         groupLimit: input.groupLimit
     });
@@ -261,12 +431,47 @@ async function computeTwinKpi(input) {
         minutes: Math.round((toMs - fromMs) / 60_000),
         basis
     };
+    /**
+     * 여러 구간 분포를 만든다 — **현재 창에 기록이 없어도 낸다.**
+     *
+     * 그때가 오히려 가장 알고 싶은 순간이다("지금 아무 기록이 없는데 평소엔 60건이었다" = 멈춘 신호).
+     * 그래서 조기 반환보다 앞에 두고 두 경로가 함께 쓴다.
+     */
+    const computeBaseline = async () => {
+        if (!input.baseline || !(input.baseline.periods > 0))
+            return undefined;
+        const stride = input.baseline.stride ?? 'day';
+        const windows = (0, kpi_baseline_js_1.baselineWindows)(fromMs, toMs, input.baseline.periods, stride);
+        let baseCapped = false;
+        const samples = [];
+        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))
+                values[metric] = kpi_target_js_1.TWIN_METRIC[metric].of(past);
+            samples.push({ fromMs: w.fromMs, toMs: w.toMs, values });
+        }
+        const current = {};
+        for (const metric of Object.keys(kpi_target_js_1.TWIN_METRIC))
+            current[metric] = kpi_target_js_1.TWIN_METRIC[metric].of(kpi);
+        return {
+            stride,
+            periods: windows.length,
+            metrics: (0, kpi_baseline_js_1.summarizeBaseline)(kpi_target_js_1.TWIN_METRIC, current, samples),
+            ...(baseCapped ? { capped: true } : {})
+        };
+    };
     if (kpi.eventsInWindow === 0) {
+        const baseline = await computeBaseline();
         return {
             window,
             measured: false,
             scope,
-            note: 'no operational events in this window — nothing to measure (this is NOT "zero throughput").'
+            note: 'no operational events in this window — nothing to measure (this is NOT "zero throughput").',
+            ...(baseline ? { baseline } : {})
         };
     }
     /* 구간별 값 — 쪼개기 규칙은 순수 모듈이 소유한다(테스트 가능). 여기서는 시각을 ISO 로 옮기기만. */
@@ -326,6 +531,15 @@ async function computeTwinKpi(input) {
                     }
                 };
     }
+    /*
+     * 여러 구간 동시 비교 — **같은 시간대를 며칠 뒤로** 옮겨 분포를 만든다(성과 맵 ③).
+     *
+     * 창마다 조회가 한 번 더 붙지만 각 창은 현재 창과 같은 길이라(보통 1~24h) 값싸다. 축(groupBy)은
+     * 넘기지 않는다 — 분포는 **전체 지표**의 질문이고, 축별 분포까지 내면 응답이 축 수만큼 부푼다
+     * (필요해지면 그때 축을 지정해 다시 묻는 것이 정직하다).
+     *
+     * 지표 어휘는 `TWIN_METRIC` 이 계속 소유하고, 여기서는 **값만 꺼내** 분포 모듈에 넘긴다.
+     */
     /* 관점 값은 시각 변환이 없어 그대로 통과한다. 붙이는 것은 ① 사람이 읽는 이름과 ② 축이 통째로
      * 비었을 때의 이유다 — "구역별 0건" 과 "노드에 구역이 안 붙어 있다" 는 완전히 다른 상황이다. */
     const groups = kpi.groups
@@ -369,8 +583,35 @@ async function computeTwinKpi(input) {
      * **목표가 없으면 판정하지 않는다** — 필드 자체를 만들지 않는다. 전부 "목표 없음" 으로 채우면
      * 화면이 회색 노이즈가 되고, 목표가 있는 지표가 묻힌다.
      */
+    /* 분포는 **한 번만** 계산한다 — 창마다 조회가 붙으므로 두 번 부르면 조회가 두 배가 된다. */
+    const baseline = await computeBaseline();
     /* 폴드가 돌려준 raw 창(ms)은 버린다 — 위의 ISO 창이 사람이 읽을 정본이다. */
     const { window: _rawWindow, groups: _rawGroups, ...rest } = kpi;
+    /*
+     * 자리에 **부르는 이름**을 붙인다 — `feeder-2` 는 id 이고 사람은 「가공 라인」으로 부른다.
+     * 이름을 모르는 자리는 id 그대로 둔다(지어내지 않는다).
+     */
+    /* 단가가 갈려 있으면 밝힌다 — 우리가 고른 하나로 낸 금액이라는 사실을 화면이 말할 수 있게. */
+    if (rest.energy?.cost && tariffFound.conflict)
+        rest.energy = { ...rest.energy, tariffConflict: true };
+    if (rest.energy?.byFeeder?.length) {
+        rest.energy = {
+            ...rest.energy,
+            byFeeder: rest.energy.byFeeder.map(row => ({ ...row, ...(feederMap.labels[row.key] ? { label: feederMap.labels[row.key] } : {}) }))
+        };
+    }
+    /*
+     * 계통도 — **선언된 관계와 계량이 덮는 범위**를 함께 낸다.
+     *
+     * 값은 여기서 다시 계산하지 않는다(폴드가 낸 분기별 몫을 그대로 노드에 얹는다). 계통은 모델이 아는
+     * 사실이므로 저널만 보는 폴드가 아니라 여기서 조립한다 — 화면이 모델을 따로 또 조회하지 않아도 되고,
+     * AI 도 같은 값을 읽는다(규칙 한 벌).
+     */
+    if (rest.energy) {
+        const topo = await energyTopologyOf(input.domainId, instanceIds, rest.energy);
+        if (topo)
+            rest.energy = { ...rest.energy, topology: topo };
+    }
     return {
         window,
         measured: true,
@@ -380,7 +621,8 @@ async function computeTwinKpi(input) {
         ...(buckets ? { buckets } : {}),
         ...(groups ? { groups } : {}),
         ...(verdicts.length ? { targets: verdicts } : {}),
-        ...(comparison ? { comparison } : {})
+        ...(comparison ? { comparison } : {}),
+        ...(baseline ? { baseline } : {})
     };
 }
 //# sourceMappingURL=kpi-query.js.map