@things-factory/headless-twin 10.0.7 → 10.0.9

package/server/engine/kpi-query.ts

@@ -25,7 +25,7 @@ import { TwinInstance } from '../service/twin-instance/twin-instance.js'
 import { TwinArea } from '../service/twin-space/twin-area.js'
 import { TwinSpace } from '../service/twin-space/twin-space.js'
 import { TwinTarget } from '../service/twin-target/twin-target.js'
-import { judgeTargets, judgeGroupTargets, scopedTargets, type ScopedTargets, type TargetVerdict } from './kpi-target.js'
+import { TWIN_METRIC, judgeTargets, judgeGroupTargets, scopedTargets, type ScopedTargets, type TargetVerdict, type TwinMetricId } from './kpi-target.js'
 import { TwinEngine } from './twin-engine.js'
 import {
   crossGroups,
@@ -38,6 +38,7 @@ import {
   type KpiGroupBy,
   type KpiResult
 } from './kpi-fold.js'
+import { MAX_BASELINE_PERIODS, baselineWindows, summarizeBaseline, type BaselineStride, type MetricBaseline } from './kpi-baseline.js'
 
 /** 업무 전이만 읽는다 — 설비 상태(equipment.status)는 OEE 누적기의 몫이고 여기선 쓰지 않는다. */
 const BUSINESS_EVENTS = ['task.status', 'order.status']
@@ -87,6 +88,18 @@ export interface TwinKpiInput {
    * 없는 것을 0% 로 그리면 "변화 없음" 이라는 거짓이 된다.
    */
   compareTo?: 'previous' | 'yesterday'
+  /**
+   * **여러 구간 동시 비교** — 최근 N 구간의 같은 시간대를 함께 접어 **분포**와 그 안의 자리를 낸다.
+   *
+   * `compareTo` 는 한 구간만 봐서 판단이 "어제보다 나아졌다" 에서 멈춘다 — 어제도 나빴으면 쓸모가 없다.
+   * 최근 며칠의 같은 시간대를 보면 목표 없이도 "지난 7일 중 가장 낮다" 를 말할 수 있다.
+   *
+   * `stride: 'week'` 는 같은 요일을 본다(주말·평일이 섞이지 않게). `periods` 는 1~14
+   * (창마다 조회가 한 번 더 붙는다 — 값을 공짜로 말하지 않는다).
+   *
+   * `compareTo` 와 함께 쓸 수 있다: 다른 질문이기 때문이다(직전 한 구간 vs 최근 분포).
+   */
+  baseline?: { periods: number; stride?: BaselineStride }
 }
 
 export interface TwinKpiOutput extends Omit<Partial<KpiResult>, 'window'> {
@@ -147,6 +160,21 @@ export interface TwinKpiOutput extends Omit<Partial<KpiResult>, 'window'> {
     waitTime?: KpiResult['waitTime']
     delta?: { tasks: number; orders: number; workP50Ms?: number; leadP50Ms?: number; waitP50Ms?: number }
   }
+  /**
+   * **여러 구간 분포**(요청했을 때만) — 지표별로 최근 N 구간의 분포와 지금의 자리.
+   *
+   * `samples` 는 **요청한 창 전부**다(기록 없는 창도 `measured:false` 로 남는다) — 빼고 말하면
+   * "지난 7일" 이 실제로는 3일이었다는 것을 아무도 모른다. 자리를 말할 수 없으면 `noPosition` 이
+   * 이유를 밝힌다(표본 부족·현재 값 없음). 방향은 지표의 성질이라 `standing` 이 그것을 적용한 읽기다.
+   */
+  baseline?: {
+    stride: BaselineStride
+    /** 요청한 과거 구간 수(상한 적용 후). */
+    periods: number
+    metrics: MetricBaseline[]
+    /** 과거 창 조회 중 하나라도 상한에 걸렸나 — 그 창의 값은 하한이라 분포가 낮게 보일 수 있다. */
+    capped?: boolean
+  }
   /**
    * 관점별 값(요청했을 때만). `key` 는 식별자, `label` 은 사람이 읽는 이름(있을 때만 — 구역은 이름이
    * 따로 저장되어 있다). `truncated` 는 상한 때문에 빠진 축의 수다.
@@ -411,12 +439,49 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
     minutes: Math.round((toMs - fromMs) / 60_000),
     basis
   }
+  /**
+   * 여러 구간 분포를 만든다 — **현재 창에 기록이 없어도 낸다.**
+   *
+   * 그때가 오히려 가장 알고 싶은 순간이다("지금 아무 기록이 없는데 평소엔 60건이었다" = 멈춘 신호).
+   * 그래서 조기 반환보다 앞에 두고 두 경로가 함께 쓴다.
+   */
+  const computeBaseline = async (): Promise<TwinKpiOutput['baseline']> => {
+    if (!input.baseline || !(input.baseline.periods > 0)) return undefined
+    const stride = input.baseline.stride ?? 'day'
+    const windows = baselineWindows(fromMs, toMs, input.baseline.periods, stride)
+    let baseCapped = false
+    const samples: { fromMs: number; toMs: number; values: Partial<Record<TwinMetricId, number | undefined>> }[] = []
+
+    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 = foldKpi(pastEvents, w, { locationArea: areaMap.locationArea, ...shiftCtx })
+      const values: Partial<Record<TwinMetricId, number | undefined>> = {}
+      for (const metric of Object.keys(TWIN_METRIC) as TwinMetricId[]) values[metric] = TWIN_METRIC[metric].of(past)
+      samples.push({ fromMs: w.fromMs, toMs: w.toMs, values })
+    }
+
+    const current: Partial<Record<TwinMetricId, number | undefined>> = {}
+    for (const metric of Object.keys(TWIN_METRIC) as TwinMetricId[]) current[metric] = TWIN_METRIC[metric].of(kpi)
+
+    return {
+      stride,
+      periods: windows.length,
+      metrics: summarizeBaseline(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 } : {})
     }
   }
 
@@ -485,6 +550,15 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
           }
   }
 
+  /*
+   * 여러 구간 동시 비교 — **같은 시간대를 며칠 뒤로** 옮겨 분포를 만든다(성과 맵 ③).
+   *
+   * 창마다 조회가 한 번 더 붙지만 각 창은 현재 창과 같은 길이라(보통 1~24h) 값싸다. 축(groupBy)은
+   * 넘기지 않는다 — 분포는 **전체 지표**의 질문이고, 축별 분포까지 내면 응답이 축 수만큼 부푼다
+   * (필요해지면 그때 축을 지정해 다시 묻는 것이 정직하다).
+   *
+   * 지표 어휘는 `TWIN_METRIC` 이 계속 소유하고, 여기서는 **값만 꺼내** 분포 모듈에 넘긴다.
+   */
   /* 관점 값은 시각 변환이 없어 그대로 통과한다. 붙이는 것은 ① 사람이 읽는 이름과 ② 축이 통째로
    * 비었을 때의 이유다 — "구역별 0건" 과 "노드에 구역이 안 붙어 있다" 는 완전히 다른 상황이다. */
   const groups = kpi.groups
@@ -529,6 +603,9 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
    * **목표가 없으면 판정하지 않는다** — 필드 자체를 만들지 않는다. 전부 "목표 없음" 으로 채우면
    * 화면이 회색 노이즈가 되고, 목표가 있는 지표가 묻힌다.
    */
+  /* 분포는 **한 번만** 계산한다 — 창마다 조회가 붙으므로 두 번 부르면 조회가 두 배가 된다. */
+  const baseline = await computeBaseline()
+
   /* 폴드가 돌려준 raw 창(ms)은 버린다 — 위의 ISO 창이 사람이 읽을 정본이다. */
   const { window: _rawWindow, groups: _rawGroups, ...rest } = kpi
   return {
@@ -540,6 +617,7 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
     ...(buckets ? { buckets } : {}),
     ...(groups ? { groups } : {}),
     ...(verdicts.length ? { targets: verdicts } : {}),
-    ...(comparison ? { comparison } : {})
+    ...(comparison ? { comparison } : {}),
+    ...(baseline ? { baseline } : {})
   }
 }

package/server/engine/live-attentions.ts

@@ -6,7 +6,7 @@
  */
 import { deriveAttentions } from '@operato/twin-kernel'
 
-export function withLiveAttentions<S extends { equipment?: any[]; locations?: any[]; orders?: any[]; tasks?: any[]; attentions?: any[]; nowTime?: string }>(
+export function withLiveAttentions<S extends { equipment?: any[]; locations?: any[]; orders?: any[]; tasks?: any[]; attentions?: any[]; acked?: string[]; nowTime?: string }>(
   state: S
 ): S {
   if (!state) return state
@@ -18,7 +18,12 @@ export function withLiveAttentions<S extends { equipment?: any[]; locations?: an
      */
     attentions: deriveAttentions(
       { equipment: state.equipment ?? [], locations: state.locations ?? [], orders: state.orders ?? [], tasks: state.tasks ?? [] },
-      undefined,
+      /*
+       * **확인(ack)해 둔 것을 함께 넘긴다.** 예전에는 여기에 undefined 를 넘겨서, 라이브에서는
+       * 확인 처리가 화면에 전혀 반영되지 않았다 — 사람이 확인해도 신호가 계속 활성으로 나갔다.
+       * 확인 사실은 이제 저널에 남고(`attention.acked`) 프로젝터가 상태에 실어 오므로 여기서 받는다.
+       */
+      state.acked?.length ? new Set(state.acked) : undefined,
       state.nowTime
     )
   }

package/server/engine/runtime-key.ts

@@ -0,0 +1,58 @@
+/*
+ * 런타임 레지스트리 키 — **트윈의 정체성은 `(도메인, 인스턴스 id)` 다.** 순수.
+ *
+ * ── 왜 있나 (2026-08-06 테넌트 격리 전수 확인) ───────────────────────────────
+ * `TwinEngine.instances` 와 `recovered` 가 **`instanceId` 하나로** 키를 잡고 있었다. 그런데 DB 유일성은
+ * `[domain, instanceId]` 이고(`TwinInstance` 인덱스) 트윈의 정체성도 그쪽이다. 즉 런타임 맵만 **전역
+ * 이름 공간**이었다.
+ *
+ * **충돌은 이론이 아니다.** 레퍼런스 경로가 `instanceId` 로 **레퍼런스 소스 이름**을 쓴다
+ * (`sap-ewm-1710`). 벤더 시스템 이름은 테넌트가 **공유하는 어휘**라, 두 테넌트가 같은 시스템에
+ * 연결하면 같은 id 가 된다 — 드문 사고가 아니라 예상되는 경우다.
+ *
+ * 그래서 무엇이 어긋났나:
+ *  · `startLive` 의 조기 반환이 A 의 런타임을 B 에게 돌려주고 `ingestLive` 는 도메인을 확인하지 않아
+ *    **B 의 라이브 이벤트가 A 의 커널에 적용**될 수 있었다.
+ *  · `recovered` 가 겹치면 웜스타트 씨앗이 **남의 스냅샷**이 되어 재고가 섞인다.
+ *  · `start`/`stop` 이 남의 런타임을 집으므로 B 는 "기동됨" 을 받고도 이후 전부 거부됐다.
+ *
+ * 이 부류는 **이미 한 번 물었다** — `twin-lifecycle-mutation.ts` 주석이 증언한다: "과거엔
+ * `Object.keys(TwinEngine.instances)` 로 전역 반환 → 다른 도메인 트윈이 새던 버그." 그 자리만 고쳤다.
+ * 그래서 이번에는 가드를 더 붙이지 않고 **키를 고친다** — 저수준 메서드가 `domainId` 를 받게 되는 것이
+ * 요점이다. "누구의 트윈인가" 를 말하지 않고는 만질 수 없다.
+ *
+ * ── 구분자 규약 ─────────────────────────────────────────────────────────────
+ * `${domainId}:${instanceId}` — 이 저장소가 이미 쓰는 모양이다(`structureRevCache`·`measuredCache`).
+ * 새 모양을 만들지 않는다. 파싱은 **첫 구분자**에서 자르므로 `instanceId` 에 `:` 가 들어 있어도
+ * 안전하다(레퍼런스 소스 이름에 들어갈 수 있다). 대신 `domainId` 에 구분자가 있으면 키가 모호해지므로
+ * **그때는 던진다** — 조용히 잘못된 키를 만들면 그게 곧 이 결함의 재발이다.
+ */
+
+/** 도메인과 인스턴스 id 를 잇는 문자 — 저장소의 기존 캐시 키와 같은 모양. */
+export const RUNTIME_KEY_SEP = ':'
+
+/**
+ * 런타임 레지스트리 키.
+ *
+ * @throws 도메인 id 가 비었거나 구분자를 담고 있으면(키가 모호해진다). 인스턴스 id 가 비었으면.
+ */
+export function runtimeKey(domainId: string, instanceId: string): string {
+  if (!domainId) throw new Error('runtimeKey: domainId is required — a twin runtime always belongs to a tenant')
+  if (!instanceId) throw new Error('runtimeKey: instanceId is required')
+  if (domainId.includes(RUNTIME_KEY_SEP)) {
+    throw new Error(`runtimeKey: domainId must not contain "${RUNTIME_KEY_SEP}" (would make the key ambiguous)`)
+  }
+  return `${domainId}${RUNTIME_KEY_SEP}${instanceId}`
+}
+
+/** 키를 되돌린다 — 첫 구분자에서 자른다(인스턴스 id 안의 구분자는 보존). */
+export function parseRuntimeKey(key: string): { domainId: string; instanceId: string } {
+  const at = key.indexOf(RUNTIME_KEY_SEP)
+  if (at <= 0 || at === key.length - 1) throw new Error(`parseRuntimeKey: "${key}" is not a runtime key`)
+  return { domainId: key.slice(0, at), instanceId: key.slice(at + 1) }
+}
+
+/** 이 키가 이 테넌트의 것인가 — 레지스트리를 훑을 때 도메인으로 걸러낸다. */
+export function isOfDomain(key: string, domainId: string): boolean {
+  return !!domainId && key.startsWith(`${domainId}${RUNTIME_KEY_SEP}`)
+}

package/server/engine/state-axes.ts

@@ -0,0 +1,55 @@
+/*
+ * 상태 축 고르기 — **순수**. "요청한 축만 남긴다."
+ *
+ * ── 왜 있나 (2026-08-05) ────────────────────────────────────────────────────
+ * 지도는 구독으로 "바뀌었다" 신호를 받고 상태를 다시 읽는다. 그 신호는 의도적으로 가볍고(`{kind,
+ * revision}`) 리프레시도 250ms 로 합쳐진다 — 거기까지는 설계대로다. 문제는 **리프레시가 통째로**
+ * 라는 것이다: 실 저널로 재 보니 트윈 하나가 최대 710KB 이고, 같은 공간에 셋이면 한 번에 약 2MB 다.
+ *
+ * 그런데 지도가 실제로 쓰는 것은 `locations`·`attentions`·`nowTime` **셋뿐**이다(코드 확인). 물품
+ * 2,278건·작업·오더를 받아 놓고 쓰지 않는다. 축을 골라 받으면 트윈에 따라 1.7~15배 줄어든다
+ * (물품이 많은 트윈은 15배, 신호가 많은 트윈은 2배 — 신호가 큰 쪽은 그것이 다음 과제다).
+ *
+ * ── 화면 이름을 API 에 넣지 않는다 ──────────────────────────────────────────
+ * `twinMapState` 같은 화면 전용 질의를 만들지 않는다. 호출부가 **필요한 축을 말하고** 서버가 자른다 —
+ * 새 화면이 생길 때마다 질의가 늘지 않고, 어휘도 화면 이름이 아니라 상태의 축이다(무방언).
+ *
+ * 모르는 축 이름은 **조용히 버리지 않고 무시하되 그 사실을 돌려준다** — 오타 하나로 화면이 빈
+ * 채로 뜨는 것이 가장 나쁘다.
+ */
+
+/** 상태가 들고 있는 축 — 이 목록 밖의 이름은 고를 수 없다. */
+export const STATE_AXES = ['locations', 'items', 'equipment', 'persons', 'assets', 'tasks', 'orders', 'attentions', 'acked'] as const
+export type StateAxis = (typeof STATE_AXES)[number]
+
+/** 축과 무관하게 늘 남는 것 — 이것이 없으면 무엇을 받았는지 알 수 없다. */
+const ALWAYS = ['revision', 'nowTime', 'simClockMs', 'corrections'] as const
+
+export interface PickedAxes {
+  /** 고른 축만 남은 상태. `axes` 가 비었으면 원본 그대로(자르지 않는다). */
+  state: any
+  /** 상태 축이 아닌 이름 — 호출부가 오타를 알 수 있게 돌려준다. */
+  unknown: string[]
+}
+
+/**
+ * 요청한 축만 남긴다.
+ *
+ * `axes` 가 비어 있으면 **자르지 않는다** — 기본값이 "전부" 여야 기존 호출부가 그대로 동작한다
+ * (자르는 쪽이 기본이면 축을 말하지 않은 화면이 조용히 비어 버린다).
+ */
+export function pickAxes(state: any, axes: readonly string[] | undefined | null): PickedAxes {
+  if (!state || typeof state !== 'object') return { state, unknown: [] }
+  if (!axes?.length) return { state, unknown: [] }
+
+  const known = new Set<string>(STATE_AXES as readonly string[])
+  const wanted = axes.filter(a => known.has(a))
+  const unknown = axes.filter(a => !known.has(a))
+  /* 아는 축이 하나도 없으면 자르지 않는다 — 전부 오타인 경우에 빈 화면을 만들지 않는다. */
+  if (!wanted.length) return { state, unknown }
+
+  const out: any = {}
+  for (const k of ALWAYS) if (k in state) out[k] = state[k]
+  for (const a of wanted) if (a in state) out[a] = state[a]
+  return { state: out, unknown }
+}