@things-factory/headless-twin 10.0.17 → 10.0.18

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

@@ -22,7 +22,7 @@ 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 ops_contract_1 = require("@operato/ops-contract");
 const shell_1 = require("@things-factory/shell");
 const twin_event_js_1 = require("../service/twin-event/twin-event.js");
 const twin_instance_js_1 = require("../service/twin-instance/twin-instance.js");
@@ -41,7 +41,7 @@ const kpi_baseline_js_1 = require("./kpi-baseline.js");
  * 나눈 값이라, 두 사실이 한 폴드에 들어와야 창이 어긋날 수 없다. 표본(`energy.measured`)은 읽지 않는다 —
  * 저널에 없고(§4.1 인제스트 계약) 여기서 필요한 것은 마감된 구간뿐이다.
  */
-const BUSINESS_EVENTS = ['task.status', 'order.status', 'energy.demand.window', 'energy.generation.period', 'energy.usage.period', 'energy.bill'];
+const BUSINESS_EVENTS = ['task.status', 'order.status', 'energy.demand.window', 'energy.generation.period', 'energy.usage.period', 'energy.bill', 'energy.generation.price'];
 /** 한 번에 계산할 이벤트 상한 — 큰 구간이 서버를 붙잡지 않게. */
 const MAX_EVENTS = 20000;
 /**
@@ -51,7 +51,27 @@ const MAX_EVENTS = 20000;
  * 메모리가 그만큼 든다. 셋(종류) × 둘(트윈)까지는 최악에 12만 행이고, 그 이상은 예전 한 질의로 간다 —
  * 느리지만 답은 같다.
  */
-const KPI_MAX_SPLIT = 6;
+/*
+ * ── 나눠 물을 수 있는 갈래의 최대 (2026-08-30 실측) ──────────────────────────
+ *
+ * 6 이었다. 그런데 **한 현장에 트윈이 여럿인 것이 이 제품의 정상**이다(창고·공정·야드가 한 현실을
+ * 각각 본다). 트윈 3개 × 종류 6가지 = 18 이라 조건에 안 걸렸고, 한 질의로 떨어졌다.
+ *
+ * 같은 창·같은 행으로 두 모양을 쟀다(hatio-us, order.status 345만 건이 있는 하루):
+ *
+ *   한 질의(종류 IN + 시각순)   ix_twin_event_1 로 그 날 전체를 걷는다   25.987초 · 20,000건(잘림)
+ *   갈래 하나(종류 정확일치)     ix_twin_event_7 이 순서까지 준다          0.286초
+ *
+ * 91배다. 그리고 25초를 기다린 끝에 나오는 값이 **잘린 값**이다 — 사용자는 그 사실을 25초 뒤에 본다.
+ *
+ * ── 늘리는 대가 ────────────────────────────────────────────────────────────
+ * 갈래마다 상한까지 받아야 합칠 때 정확하므로(§`mergeStreams`), 갈래가 많으면 그만큼 든다.
+ * 최악은 `갈래 수 × MAX_EVENTS` 행이다. 다만 그 최악은 **모든 갈래가 창을 가득 채울 때**이고,
+ * 그때는 어차피 결과가 잘린다(그 사실은 `capped` 로 나간다).
+ *
+ * 32 는 트윈 4개 × 종류 8가지를 덮는다. 어휘가 더 늘면 이 수를 다시 재고 정한다.
+ */
+const KPI_MAX_SPLIT = 32;
 /**
  * 노드 → 구역 지도. **저널에는 구역이 없다**(노드까지만 있다) — 모델 정의의 `locations[].parentId` 가
  * 마스터 계층에서 온 소속이다. 기동하지 않은 트윈도 모델은 남아 있어 이 경로가 가장 튼튼하다.
@@ -132,7 +152,7 @@ async function locationAreaMap(domainId, instanceIds, spaceId) {
                  * 이 집계는 지금 구역 롤업(`rollupOf`)만 쓰므로 결과가 달라지지 않는다. 그래도 여기서
                  * 잇는다: 단으로 묻는 질의(`ancestorOfLevel`)가 생길 때 배선을 다시 찾지 않게 한다.
                  */
-                h = (0, twin_kernel_1.hierarchyOf)({ locations }, t => (0, twin_kernel_1.levelOfLocationType)(t, row.kind));
+                h = (0, ops_contract_1.hierarchyOf)({ locations }, t => (0, ops_contract_1.levelOfLocationType)(t, row.kind));
             }
             catch (e) {
                 (0, log_js_1.twinWarn)(`[twin-kpi] "${row.instanceId}": location hierarchy is broken — area rollup skipped for this twin: ${e?.message}`);
@@ -196,11 +216,11 @@ async function tariffOf(domainId, instanceIds) {
                 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 d = num(ops_contract_1.EMS_PROPERTY.demandChargePerKW);
+            const e = num(ops_contract_1.EMS_PROPERTY.energyChargePerKWh);
             /* 요금적용전력 — 있으면 기본요금이 조건부 파생이 아니라 사실이 된다(§`electricityCost`). */
-            const b = num(twin_kernel_1.EMS_PROPERTY.billingDemandKW);
-            const cur = props.get(twin_kernel_1.EMS_PROPERTY.currency);
+            const b = num(ops_contract_1.EMS_PROPERTY.billingDemandKW);
+            const cur = props.get(ops_contract_1.EMS_PROPERTY.currency);
             if (d === undefined && e === undefined)
                 continue;
             found.push({
@@ -234,7 +254,7 @@ async function resourceFeederMap(domainId, instanceIds) {
         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);
+        const electrical = new Set(ops_contract_1.EMS_LOCATION_TYPES);
         /**
          * 이 자리에서 **전기 상류**로 올라가 처음 만나는 계통의 자리. 없으면 undefined.
          *
@@ -249,7 +269,7 @@ async function resourceFeederMap(domainId, instanceIds) {
                 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));
+                const up = (0, ops_contract_1.electricalUpstreamOf)(locations, String(cur.id));
                 cur = up ? byId.get(up) : cur.parentId ? byId.get(String(cur.parentId)) : undefined;
             }
             return undefined;
@@ -310,6 +330,55 @@ function latestBillOf(domainId, instanceIds) {
     }
     return best;
 }
+/** 이 트윈들이 이어받고 있는 **발전 단가** — 창 안에 단가 사실이 없을 때 쓴다. */
+function latestGenerationPriceOf(domainId, instanceIds) {
+    let best;
+    for (const instanceId of instanceIds) {
+        const p = twin_engine_js_1.TwinEngine.snapshot(domainId, instanceId)?.energy?.generationPrice;
+        if (!p?.from || !Number.isFinite(Number(p.unitPrice)) || !p.currency)
+            continue;
+        if (!best || Date.parse(p.from) > Date.parse(best.from)) {
+            best = { from: String(p.from), to: String(p.to), unitPrice: Number(p.unitPrice), currency: String(p.currency) };
+        }
+    }
+    return best;
+}
+/**
+ * 이 트윈들의 **발전 정격** — 이용률의 분모.
+ *
+ * 커널이 고른다(설비 합 → 자리 합계, 교류 → 직류). 여러 트윈이면 합한다 — 한 현장의 발전은
+ * 트윈마다 나뉘어 있어도 같은 현장의 발전이다. 근거가 갈리면 약한 쪽(직류·자리)으로 적는다.
+ */
+function generationRatedOf(domainId, instanceIds) {
+    let kW = 0;
+    let basis = 'ac';
+    let from = 'equipment';
+    for (const instanceId of instanceIds) {
+        /* 스냅샷에서 읽는다 — 커널이 고른 값이다. 여기서 모델을 다시 뒤지면 고르는 규칙이 두 벌이 된다. */
+        const r = twin_engine_js_1.TwinEngine.snapshot(domainId, instanceId)?.energy?.generationRated;
+        if (!r || !(Number(r.kW) > 0))
+            continue;
+        kW += Number(r.kW);
+        if (r.basis === 'dc')
+            basis = 'dc';
+        if (r.from === 'location')
+            from = 'location';
+    }
+    return kW > 0 ? { kW, basis, from } : undefined;
+}
+/** 이 트윈들이 이어받고 있는 **요금 기준** — 이 주기에 적용되는 값(청구서보다 먼저다). */
+function latestTariffBasisOf(domainId, instanceIds) {
+    let best;
+    for (const instanceId of instanceIds) {
+        const b = twin_engine_js_1.TwinEngine.snapshot(domainId, instanceId)?.energy?.tariffBasis;
+        if (!b?.from)
+            continue;
+        if (!best || Date.parse(b.from) > Date.parse(best.from)) {
+            best = { from: String(b.from), ...(Number.isFinite(Number(b.billingDemandKW)) ? { billingDemandKW: Number(b.billingDemandKW) } : {}) };
+        }
+    }
+    return best;
+}
 async function energyTopologyOf(domainId, instanceIds, energy) {
     if (!instanceIds.length)
         return undefined;
@@ -628,7 +697,19 @@ async function computeTwinKpi(input) {
                     : 'no operational events in the journal yet — there is nothing to measure (this is NOT "zero throughput").'
             };
         }
-        toMs = Date.parse(latest);
+        /*
+         * ── **미래를 성과 구간으로 삼지 않는다** (2026-08-30) ──────────────────────
+         *
+         * 마지막 기록이 미래일 수 있다. 한 원본이 **끝나지 않은 이번 달**의 요금 정보를 청구서로 보냈고,
+         * 청구서의 사건 시각은 기간의 끝이라 그 사실이 **내일** 일어난 것으로 적혔다. 그러자 구간이
+         * `내일 00:00 → 모레 00:00` 이 되어 그 현장의 화면에서 **어제 발전량이 사라졌다.** 오류는 나지
+         * 않았고 화면만 비어 있었다.
+         *
+         * 커널이 이제 그런 사실을 받지 않는다. 그래도 여기서 막는다 — **이미 적힌 것은 사라지지 않고**,
+         * 저널은 지우지 않기 때문이다. 그리고 성과는 지나간 일이다. 아직 오지 않은 구간의 성과라는 것은
+         * 없다.
+         */
+        toMs = Math.min(Date.parse(latest), Date.now());
         basis = 'latest-event';
     }
     const fromMs = input.fromTime ? Date.parse(input.fromTime) : toMs - minutes * 60_000;
@@ -656,6 +737,10 @@ async function computeTwinKpi(input) {
      * **커널 상태에 이어져 있는 마지막 청구서**를 함께 넘긴다(§`EnergyState.lastBill`).
      */
     const lastBill = latestBillOf(input.domainId, instanceIds);
+    const tariffBasis = latestTariffBasisOf(input.domainId, instanceIds);
+    /* 이용률의 분모 — 커널이 모델의 선언에서 고른다(설비 합 → 자리 합계, 교류 → 직류). */
+    const generationRated = generationRatedOf(input.domainId, instanceIds);
+    const generationPrice = latestGenerationPriceOf(input.domainId, instanceIds);
     const kpi = (0, kpi_fold_js_1.foldKpi)(events, { fromMs, toMs }, {
         groupBy: input.groupBy,
         locationArea: areaMap.locationArea,
@@ -663,6 +748,9 @@ async function computeTwinKpi(input) {
         meterFeeder: feederMap.meterFeeder,
         ...(tariffFound.tariff ? { tariff: tariffFound.tariff } : {}),
         ...(lastBill ? { lastBill } : {}),
+        ...(tariffBasis ? { tariffBasis } : {}),
+        ...(generationRated ? { generationRated } : {}),
+        ...(generationPrice ? { generationPrice } : {}),
         ...shiftCtx,
         groupLimit: input.groupLimit
     });