@things-factory/headless-twin 10.0.6 → 10.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/headless-twin",
-  "version": "10.0.6",
+  "version": "10.0.7",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh <heartyoh@hatiolab.com>",
@@ -25,11 +25,11 @@
     "test": "node --test test/*.test.ts"
   },
   "dependencies": {
-    "@operato/twin-kernel": "^0.1.0",
-    "@things-factory/auth-base": "^10.0.6",
-    "@things-factory/cache-service": "^10.0.6",
+    "@operato/twin-kernel": "^0.4.0",
+    "@things-factory/auth-base": "^10.0.7",
+    "@things-factory/cache-service": "^10.0.7",
     "@things-factory/env": "^10.0.0",
-    "@things-factory/shell": "^10.0.6"
+    "@things-factory/shell": "^10.0.7"
   },
-  "gitHead": "b929c16f83f70bfcc9a144ac6a50232efa56cd64"
+  "gitHead": "fffd94e886b67ed9019993a572a632054e812fa3"
 }

package/server/engine/entity-delta.ts

@@ -1,9 +1,28 @@
 /*
  * 트윈 State 스냅샷 → 라이브 바인딩 delta 목록 (순수 매핑 — pubsub/도메인 무관 → 단위 테스트 가능).
  * publishEntityData 가 이 목록을 엔티티별 시그니처로 dedup 후 data(tag) 채널로 발행한다.
- * payload 계약은 씬 컴포넌트가 소비(twin-storage·mover·equipment·trend·order-tracker·resource-control):
- *   node: occupancy/capacity/status/type · mover: location/motion/status/held/oee(정수 퍼센트) ·
- *   order: status/progress/held · __orders__: 전체 오더 집약(Trackable 뷰).
+ *
+ * ── 규율: 레퍼런스가 아는 것은 **전부** 내보낸다 ────────────────────────────
+ * 트윈에서 사소한 속성은 없다. 소속 구역·소속 팔레트·수량·만료처럼 곁가지로 보이는 값이 실제로는
+ * 구역 롤업·적재 표현·로트 추적의 전제다. 그래서 여기서 **필드를 손으로 골라 담지 않는다.**
+ *
+ * 예전에는 엔티티마다 필요할 것 같은 필드만 열거했고, 그 결과 계약에 있는 것이 조용히 누락됐다
+ * (2026-08-01 감사: 노드 parentId 누락 · 작업 전량 누락 · 물품 전량 누락). 화이트리스트 방식은
+ * **계약이 자라도 화면이 따라오지 못한다** — 커널이 속성을 늘릴 때마다 이 파일을 고쳐야 하고, 고치는
+ * 것을 잊으면 아무 신호 없이 정보가 사라진다.
+ *
+ * 그래서 반대로 한다: **상태 객체가 가진 것을 그대로 통과**시키고, 통과시키지 **않을** 것만 이유와 함께
+ * 열거한다(EXCLUDED). 새 속성은 자동으로 화면에 도달하고, 빼려면 이유를 적어야 한다.
+ *
+ * ── 표식은 도메인 낱말을 훔치지 않는다 ─────────────────────────────────────
+ * 예전 payload 는 엔티티 종류 표식을 `kind` 로 실었다. 그런데 `kind` 는 **도메인의 낱말**이다 —
+ * 무버 kind=cutter, 작업 kind=putaway, 오더 kind=workorder. 표식이 그 이름을 차지하면 도메인 속성을
+ * 실을 자리가 없어진다(같은 병을 오늘 ox-timeline 의 `group` 에서도 고쳤다).
+ * 그래서 표식은 `entity`(우리 이름)로 옮기고 `kind` 는 도메인에 돌려준다.
+ *
+ * payload 계약(씬 컴포넌트가 소비): `entity`(표식) + 그 엔티티의 모든 속성(도메인 `kind` 포함).
+ *   entity = location · equipment · person · asset · order · task · item,
+ *   그리고 집약 태그(__orders__ · __tasks__ · __items__ · __persons__ · __assets__).
  */
 
 export interface EntityDelta {
@@ -11,11 +30,26 @@ export interface EntityDelta {
   data: any
 }
 
-/** 오더 집약 고정 태그 — 클라 provider(ORDERS_TAG)와 일치. */
+/** 집약 고정 태그 — 클라 provider 와 일치해야 한다(런타임 생성 엔티티는 개별 배치가 불가하므로 집약 뷰). */
 export const ORDERS_TAG = '__orders__'
+export const TASKS_TAG = '__tasks__'
+export const ITEMS_TAG = '__items__'
+export const PERSONS_TAG = '__persons__'
+export const ASSETS_TAG = '__assets__'
 
-/** OEE 원시 비율/카운트 → 표시용 정수 퍼센트 + 카운트. 원시 누적 ms(idleMs 등)는 매 delta 증가해
- *  무변화-생략을 무력화하므로 제외(idle 자원의 매초 재방송 억제). oee 미측정이면 undefined. */
+/**
+ * 통과시키지 않는 필드 — **빼는 데는 이유가 필요하다.**
+ *
+ * · `id`/`epc` — 태그로 이미 나가므로 개별 payload 에 중복해 싣지 않는다(집약 뷰에는 넣는다).
+ * · `oee` — 원시 누적(idleMs 등)이 매 delta 증가해 "무변화 생략" 을 무력화한다. shapeOee 로 정형화해 얹는다.
+ */
+const EXCLUDED = new Set(['id', 'epc', 'oee'])
+
+/**
+ * OEE 원시 비율/카운트 → 표시용 정수 퍼센트 + 카운트.
+ * 원시 누적 ms(idleMs 등)는 매 delta 증가해 무변화-생략을 무력화하므로 제외(유휴 자원의 매초 재방송 억제).
+ * oee 미측정이면 undefined.
+ */
 function shapeOee(o: any): any {
   if (!o) return undefined
   return {
@@ -28,22 +62,108 @@ function shapeOee(o: any): any {
   }
 }
 
+/**
+ * 엔티티 하나의 payload — `entity` 표식 + 나머지 전부(도메인 `kind` 포함).
+ *
+ * `undefined` 값은 싣지 않는다(키의 유무가 시그니처를 흔들지 않게). 값이 없는 것과 키가 없는 것은
+ * 소비처에서 같으므로 안전하고, 무변화 생략이 잘 듣는다.
+ */
+function payloadOf(entityKind: string, entity: any): any {
+  /* 표식은 `entity` — 도메인의 `kind` 를 덮지 않는다. */
+  const data: any = { entity: entityKind }
+  for (const [k, v] of Object.entries(entity ?? {})) {
+    if (EXCLUDED.has(k) || v === undefined) continue
+    data[k] = v
+  }
+  return data
+}
+
+/**
+ * 집약 뷰의 항목 — 개별 payload 와 같은 내용 + 식별자.
+ * 집약은 "전체를 한 컴포넌트가 추적" 하는 용도라 식별자가 있어야 한다.
+ */
+function aggregateItem(entity: any, idKey: 'id' | 'epc'): any {
+  const out: any = { [idKey]: entity?.[idKey] }
+  for (const [k, v] of Object.entries(entity ?? {})) {
+    if (k === idKey || k === 'oee' || v === undefined) continue
+    out[k] = v
+  }
+  const shaped = shapeOee(entity?.oee)
+  if (shaped) out.oee = shaped
+  return out
+}
+
+/**
+ * 물품 집약의 상한 — 큰 현장은 물품이 수만 개라, 전량을 매 방송에 실으면 전달이 현장을 느리게 한다.
+ *
+ * **조용히 자르지 않는다**: 넘치면 `total`(전체 수)과 `truncated`(잘린 수)를 함께 실어, 소비처가
+ * "이게 전부" 라고 오해하지 않게 한다. 개별 물품은 태그별 delta 로 따로 나가고 그쪽은 시그니처 dedup
+ * 이 걸려 **변한 것만** 재방송된다.
+ */
+export const ITEMS_AGGREGATE_LIMIT = 500
+
 export function buildEntityDeltas(state: any): EntityDelta[] {
   const out: EntityDelta[] = []
-  for (const n of state?.nodes ?? []) {
-    out.push({ tag: n.id, data: { kind: 'node', occupancy: n.occupancy, capacity: n.capacity, status: n.status, type: n.type } })
+
+  for (const n of state?.locations ?? []) {
+    out.push({ tag: n.id, data: payloadOf('location', n) })
+  }
+  for (const m of state?.equipment ?? []) {
+    /* Mobile(location/motion) + Operable(status/held) + Processable(oee) — 한 payload 로.
+     * oee 만 정형화가 필요해 따로 얹는다(나머지는 통과). */
+    const data = payloadOf('equipment', m)
+    const oee = shapeOee(m?.oee)
+    if (oee) data.oee = oee
+    out.push({ tag: m.id, data })
   }
-  for (const m of state?.movers ?? []) {
-    // Mobile(location/motion) + Operable(status/held) + Processable(oee) 를 한 payload 로.
-    out.push({ tag: m.id, data: { kind: 'mover', location: m.location, motion: m.motion, status: m.status, held: m.held, oee: shapeOee(m.oee) } })
+  /* 사람 — 설비와 별개 엔티티다. 같은 통과 규칙(가진 것을 전부 내보낸다). */
+  for (const p of state?.persons ?? []) {
+    out.push({ tag: p.id, data: payloadOf('person', p) })
+  }
+  /* 물리 자산(반복사용) — 물품도 설비도 아닌 네 번째 자원. */
+  for (const a of state?.assets ?? []) {
+    out.push({ tag: a.id, data: payloadOf('asset', a) })
   }
   for (const o of state?.orders ?? []) {
-    out.push({ tag: o.id, data: { kind: 'order', status: o.status, progress: o.progress, held: o.held } })
+    out.push({ tag: o.id, data: payloadOf('order', o) })
+  }
+  for (const t of state?.tasks ?? []) {
+    out.push({ tag: t.id, data: payloadOf('task', t) })
+  }
+  for (const it of state?.items ?? []) {
+    /* 물품의 태그는 epc(개체 식별자) — 노드·무버와 달리 id 가 아니다. */
+    if (it?.epc) out.push({ tag: it.epc, data: payloadOf('item', it) })
   }
-  // 집약(Trackable) — 오더는 런타임 생성이라 개별 배치 불가 → 한 컴포넌트가 전체 추적(집약 N:M). 항상 방출.
+
+  /* ── 집약 뷰 ──────────────────────────────────────────────────────────────
+   * 런타임에 생기고 사라지는 엔티티(오더·작업·물품)는 보드에 개별 배치할 수 없다 → 한 컴포넌트가
+   * 전체를 추적하는 집약 태그를 항상 방출한다. */
+  const orders = state?.orders ?? []
+  out.push({ tag: ORDERS_TAG, data: { entity: 'orders', orders: orders.map((o: any) => aggregateItem(o, 'id')) } })
+
+  const tasks = state?.tasks ?? []
+  out.push({ tag: TASKS_TAG, data: { entity: 'tasks', tasks: tasks.map((t: any) => aggregateItem(t, 'id')) } })
+
+  /* 사람 집약 — 인원은 보드에 개별 배치할 수도 있지만(설비처럼), 전체를 한눈에 보는 소비처도 있다.
+   * 인원을 선언하지 않은 트윈에서는 빈 배열이 나간다(없음과 모름을 구별). */
+  const persons = state?.persons ?? []
+  out.push({ tag: PERSONS_TAG, data: { entity: 'persons', persons: persons.map((p: any) => aggregateItem(p, 'id')) } })
+
+  const assets = state?.assets ?? []
+  out.push({ tag: ASSETS_TAG, data: { entity: 'assets', assets: assets.map((a: any) => aggregateItem(a, 'id')) } })
+
+  const items = state?.items ?? []
+  const shown = items.slice(0, ITEMS_AGGREGATE_LIMIT)
   out.push({
-    tag: ORDERS_TAG,
-    data: { kind: 'orders', orders: (state?.orders ?? []).map((o: any) => ({ id: o.id, kind: o.kind, status: o.status, progress: o.progress, held: o.held })) }
+    tag: ITEMS_TAG,
+    data: {
+      entity: 'items',
+      items: shown.map((it: any) => aggregateItem(it, 'epc')),
+      total: items.length,
+      /* 잘렸으면 그 사실을 말한다 — "이게 전부" 로 읽히면 재고를 과소 판단한다. */
+      ...(items.length > shown.length ? { truncated: items.length - shown.length } : {})
+    }
   })
+
   return out
 }

package/server/engine/index.ts

@@ -2,3 +2,7 @@ export * from './twin-engine.js'
 export * from './canonical-ingest.js'
 export * from './kpi-fold.js'
 export * from './kpi-query.js'
+export * from './spec-coverage.js'
+export * from './travel-estimator.js'
+export * from './measured-estimator.js'
+export * from './model-basis.js'

package/server/engine/kpi-fold.ts

@@ -25,7 +25,7 @@
  * 공정 타임라인과 **다른 답**을 냈다(재전송된 완료를 두 건으로 세어 처리량·점유가 부풀려졌다).
  * 이 파일은 이제 "접힌 기록 → 창 지표" 만 한다.
  */
-import { foldTaskRecords, type TaskFacets } from '@operato/twin-kernel'
+import { foldTaskRecords, activeShiftAt, type TaskFacets, type WorkCalendarEntry } from '@operato/twin-kernel'
 
 /** 저널 한 줄 — 필요한 것만(엔티티·typeorm 비의존). */
 export interface KpiEvent {
@@ -44,6 +44,11 @@ export interface KpiWindow {
 export interface DurationStats {
   /** 짝이 맞아 계산된 건수. */
   count: number
+  /**
+   * 하위 꼬리 — **분포를 양쪽에서 접지하기 위해** 낸다.
+   * p50·p90 만 있으면 아래쪽 퍼짐을 위쪽에서 거울처럼 베껴 쓸 수밖에 없다(발명). 관측이 말하게 한다.
+   */
+  p10Ms: number
   p50Ms: number
   p90Ms: number
   avgMs: number
@@ -56,10 +61,11 @@ export interface DurationStats {
  * 축을 못 내면 AI 도 못 낸다 — 그래서 축은 계산 층의 능력이어야 한다.
  *
  *   resource  자원별(누가 했나)      taskKind  작업 종류별(무엇을 했나)
- *   node      도착 지점별(어디서)    order     오더별(무엇을 위해)
+ *   location  도착 지점별(어디서)    order     오더별(무엇을 위해)
  *   area      구역별 — 노드→구역 지도가 필요하다(이벤트에 없다. 호출부가 준다)
+ *   shift     교대별(언제) — 완료 시각 + 현장의 시각 기준에서 **계산한다**(이벤트에 없다)
  */
-export type KpiGroupBy = 'resource' | 'taskKind' | 'node' | 'order' | 'area'
+export type KpiGroupBy = 'resource' | 'taskKind' | 'location' | 'order' | 'area' | 'shift'
 
 export interface KpiGroup {
   /** 축의 값(자원 id·작업 종류·노드 id·오더 id·구역 id). 값이 없던 기록은 'unknown'. */
@@ -115,7 +121,17 @@ export interface KpiFoldOptions {
    * 노드 → 구역 지도. **이벤트에는 구역이 없다**(노드까지만 있다) — 스냅샷·마스터가 아는 값이라
    * 호출부가 넘긴다. 없으면 구역 축은 'unknown' 으로 모인다(조용히 다른 축으로 바꾸지 않는다).
    */
-  nodeArea?: Record<string, string>
+  locationArea?: Record<string, string>
+  /**
+   * 교대 선언 — **이벤트에는 교대가 없다**(시각만 있다). 현장 마스터가 아는 값이라 호출부가 넘긴다.
+   * 없으면 교대 축은 'unknown' 으로 모인다(다른 축으로 조용히 바꾸지 않는다).
+   */
+  shifts?: WorkCalendarEntry[]
+  /**
+   * 현장의 시각 기준(분) — 교대 축이 `HH:MM` 을 어느 기준으로 읽을지. **공간이 갖는 값**이다
+   * (테넌트가 아니다: 한 테넌트가 다른 시간대의 공장을 함께 가질 수 있다). 없으면 UTC.
+   */
+  utcOffsetMinutes?: number
   /**
    * 축의 상한(기본 20). 넘치면 잘라내고 **잘린 축의 수와 그 안의 건수를 함께 알린다**.
    *
@@ -147,14 +163,29 @@ function facetKey(rec: CompletionRecord, options: KpiFoldOptions): string {
       return f.resource ?? 'unknown'
     case 'taskKind':
       return f.kind ?? 'unknown'
-    case 'node':
-      return f.node ?? 'unknown'
+    case 'location':
+      return f.location ?? 'unknown'
     case 'order':
       return f.order ?? 'unknown'
     case 'area':
       /* 구역은 이벤트 밖의 지식이다 — 지도가 없으면 없다고 말한다(노드 id 로 대체하면 사용자가
        * 그것을 구역으로 오해한다). */
-      return (f.node && options.nodeArea?.[f.node]) ?? 'unknown'
+      return (f.location && options.locationArea?.[f.location]) ?? 'unknown'
+    case 'shift':
+      /*
+       * 교대는 **저널에 찍혀 있지 않다 — 계산한다.**
+       *
+       * 이벤트에 교대 이름을 스탬프하면 두 가지가 무너진다: ① 같은 사실이 두 곳에 생기고,
+       * ② 나중에 교대 시간을 고치면 **과거가 옛 구분으로 굳어** 다시 셀 수 없다. 교대는
+       * `완료 시각 + 현장의 시각 기준 + 교대 선언`에서 나오는 순수 파생이므로 여기서 낸다 —
+       * 라이브·히스토리·예측이 **커널과 같은 함수**(`activeShiftOf`)를 쓴다.
+       *
+       * 선언이 없으면 'unknown' 이다. 교대를 나눠 놓지 않은 현장에 이름을 지어내지 않는다.
+       */
+      if (!options.shifts?.length) return 'unknown'
+      /* 시각까지 넘긴다 — **휴일에 일어난 일은 어느 교대에도 속하지 않는다.** 되풀이만 보면 그날 서지도
+         않은 교대에 집계돼, 교대별 성과가 조용히 거짓이 된다. */
+      return activeShiftAt(options.shifts, rec.at, options.utcOffsetMinutes) ?? 'unknown'
     default:
       return 'unknown'
   }
@@ -218,11 +249,12 @@ function quantile(sorted: number[], q: number): number {
 }
 
 function stats(values: number[]): DurationStats {
-  if (values.length === 0) return { count: 0, p50Ms: 0, p90Ms: 0, avgMs: 0 }
+  if (values.length === 0) return { count: 0, p10Ms: 0, p50Ms: 0, p90Ms: 0, avgMs: 0 }
   const sorted = [...values].sort((a, b) => a - b)
   const sum = sorted.reduce((a, b) => a + b, 0)
   return {
     count: sorted.length,
+    p10Ms: quantile(sorted, 0.1),
     p50Ms: quantile(sorted, 0.5),
     p90Ms: quantile(sorted, 0.9),
     avgMs: Math.round(sum / sorted.length)

package/server/engine/kpi-query.ts

@@ -16,12 +16,16 @@
  */
 import { Between, In } from 'typeorm'
 
+import { hierarchyOf } from '@operato/twin-kernel'
+
 import { getRepository } from '@things-factory/shell'
 
 import { TwinEvent } from '../service/twin-event/twin-event.js'
 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 { TwinEngine } from './twin-engine.js'
 import {
   crossGroups,
@@ -118,6 +122,14 @@ export interface TwinKpiOutput extends Omit<Partial<KpiResult>, 'window'> {
   scope: { spaceId?: string; instanceIds: string[]; realityModes: string[] }
   /** 구간별 값(요청했을 때만) — 추세를 그리기 위한 최소 정보. */
   buckets?: { fromTime: string; toTime: string; tasks: number; orders: number; workP50Ms: number }[]
+  /**
+   * **목표 대비 판정** — 숫자를 판단으로 바꾸는 값(§kpi-target).
+   *
+   * 목표가 걸린 지표만 들어온다. 목표가 없거나 그 구간에 값이 없는 지표는 **여기 나타나지 않는다** —
+   * 전부 "목표 없음" 으로 채우면 화면이 회색 노이즈가 되고, 없는 값을 0 으로 놓으면 "목표 크게 미달"
+   * 이라는 없는 사실이 만들어진다.
+   */
+  targets?: TargetVerdict[]
   /**
    * 비교 구간(요청했을 때만) — 같은 규칙·같은 길이로 접은 앞 구간과의 차이.
    *
@@ -159,24 +171,94 @@ type KpiGroupOut = NonNullable<KpiResult['groups']>['items'][number] &
   Partial<Pick<CrossedGroup, 'prevTasks' | 'deltaTasks' | 'deltaWorkP50Ms' | 'isNew'>>
 
 /**
- * 노드 → 구역 지도. **저널에는 구역이 없다**(노드까지만 있다) — 보드 정의의 `nodes[].parentId` 가
- * 마스터 계층에서 온 소속 구역이다. 기동하지 않은 트윈도 보드는 남아 있어 이 경로가 가장 튼튼하다.
+ * 노드 → 구역 지도. **저널에는 구역이 없다**(노드까지만 있다) — 보드 정의의 `locations[].parentId` 가
+ * 마스터 계층에서 온 소속이다. 기동하지 않은 트윈도 보드는 남아 있어 이 경로가 가장 튼튼하다.
+ *
+ * **한 홉만 보면 안 된다.** `parentId` 는 구역일 수도 있고 중간 단(라인·셀)일 수도 있다. 라인이 끼면
+ * 한 홉짜리 코드는 "구역이 LINE-1" 이라고 답하고, 그 id 는 구역 목록에 없으므로 그 아래 스테이션이
+ * **집계에서 조용히 빠진다**(에러 없이 틀린 숫자). 그래서 커널 `hierarchyOf` 로 사슬을 끝까지 걷는다 —
+ * 걷는 규칙은 커널에 한 벌뿐이고 소비처는 그것만 부른다.
+ */
+/**
+ * 교대 축의 재료 — **교대 선언과 현장의 시각 기준.**
  *
- * 구역 이름은 `TwinArea` 에 따로 있다 — id 만 보여주면 사용자가 무엇인지 모른다.
+ * 저널에는 시각만 있고 교대가 없다(일부러 그렇게 뒀다 — 교대는 파생이라 찍어 두면 나중에 교대 시간을
+ * 고쳤을 때 과거가 옛 구분으로 굳는다). 그래서 폴드가 계산할 재료를 여기서 모은다.
+ *
+ * 선언의 출처는 **보드의 설비**다. 여러 설비가 서로 다른 교대를 가질 수 있지만, 축은 하나여야 하므로
+ * **가장 많이 쓰이는 선언 한 벌**을 쓴다 — 3교대 공장은 전 설비가 같은 교대이므로 이것이 곧 정답이고,
+ * 자원마다 교대가 다른 현장에서는 이 축이 거칠다는 뜻이다(그 사실을 여기 적어 둔다).
+ *
+ * 시각 기준은 보드에 실려 있다(`utcOffsetMinutes` — 공간이 갖는 값을 기동 시 호스트가 풀어 넣는다).
+ * 없으면 UTC 로 읽고, 그 기본값은 커널 계약에 밝혀져 있다.
  */
-async function nodeAreaMap(
+/**
+ * 이 범위에 걸린 운영 목표 — **좁은 선언이 넓은 선언을 덮는다.**
+ *
+ * 공간 전체 목표 위에 인스턴스 목표를 얹을 수 있어야 예외를 표현할 수 있다("이 라인만 다르다").
+ * 같은 지표에 둘 다 있으면 인스턴스가 이긴다.
+ */
+async function loadTargets(
+  domainId: string,
+  spaceId: string | undefined,
+  instanceIds: string[],
+  axis?: string
+): Promise<ScopedTargets> {
+  /* 조회는 **가져오기만** 한다 — 어느 목표가 이기는지는 순수 함수(`scopedTargets`)가 정한다.
+     그 규칙이 DB 접근 뒤에 있으면 화면을 눌러 봐야만 확인된다(그리고 실제로 확인되지 않았다). */
+  const rows = await getRepository(TwinTarget).find({ where: { domain: { id: domainId } } }).catch(() => [])
+  return scopedTargets(rows, { spaceId, instanceIds, axis })
+}
+
+async function shiftContext(
+  domainId: string,
+  instanceIds: string[]
+): Promise<{ shifts?: any[]; utcOffsetMinutes?: number }> {
+  if (!instanceIds.length) return {}
+  const rows = await getRepository(TwinInstance).find({ where: { domain: { id: domainId }, instanceId: In(instanceIds) } })
+  const tally = new Map<string, { decl: any[]; n: number }>()
+  let utcOffsetMinutes: number | undefined
+  for (const row of rows) {
+    const board = row.board as any
+    if (utcOffsetMinutes === undefined && typeof board?.utcOffsetMinutes === 'number') utcOffsetMinutes = board.utcOffsetMinutes
+    for (const e of (board?.equipment ?? []) as any[]) {
+      const decl = e?.workCalendar
+      if (!Array.isArray(decl) || !decl.length) continue
+      const key = JSON.stringify(decl)
+      const hit = tally.get(key)
+      if (hit) hit.n++
+      else tally.set(key, { decl, n: 1 })
+    }
+  }
+  let best: { decl: any[]; n: number } | undefined
+  for (const v of tally.values()) if (!best || v.n > best.n) best = v
+  return { ...(best ? { shifts: best.decl } : {}), ...(utcOffsetMinutes !== undefined ? { utcOffsetMinutes } : {}) }
+}
+
+async function locationAreaMap(
   domainId: string,
   instanceIds: string[],
   spaceId?: string
-): Promise<{ nodeArea: Record<string, string>; labels: Record<string, string> }> {
-  const nodeArea: Record<string, string> = {}
+): Promise<{ locationArea: Record<string, string>; labels: Record<string, string> }> {
+  const locationArea: Record<string, string> = {}
   if (instanceIds.length) {
     const rows = await getRepository(TwinInstance).find({
       where: { domain: { id: domainId }, instanceId: In(instanceIds) }
     })
     for (const row of rows) {
-      for (const n of ((row.board as any)?.nodes ?? []) as any[]) {
-        if (n?.id && n?.parentId) nodeArea[String(n.id)] = String(n.parentId)
+      const locations = (((row.board as any)?.locations ?? []) as any[]).filter(n => n?.id)
+      if (!locations.length) continue
+      /* 순환은 hierarchyOf 가 던진다 — 한 트윈의 잘못된 계층이 다른 트윈의 집계까지 죽이지 않게 여기서 가둔다. */
+      let h
+      try {
+        h = hierarchyOf({ locations })
+      } catch (e: any) {
+        console.warn(`[twin-kpi] "${row.instanceId}": location hierarchy is broken — area rollup skipped for this twin: ${e?.message}`)
+        continue
+      }
+      for (const n of locations) {
+        const area = h.rollupOf(String(n.id))
+        if (area) locationArea[String(n.id)] = area // 구역 미상은 넣지 않는다 — 없는 구역을 만들지 않는다
       }
     }
   }
@@ -192,7 +274,7 @@ async function nodeAreaMap(
       for (const a of areas) if (a.areaId && a.name) labels[a.areaId] = a.name
     }
   }
-  return { nodeArea, labels }
+  return { locationArea, labels }
 }
 
 /** 이 대상들의 마지막 업무 기록 시각(ISO). 기록이 없으면 null. */
@@ -305,14 +387,24 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
 
   const { events, capped } = await fetchEvents(input.domainId, instanceIds, fromMs, toMs, lookbackMs)
 
-  /* 구역 축만 이벤트 밖의 지식을 필요로 한다 — 다른 축은 payload 에서 바로 나온다. */
+  /* 구역·교대 축은 **이벤트 밖의 지식**을 필요로 한다 — 다른 축은 payload 에서 바로 나온다. */
   const areaMap =
-    input.groupBy === 'area' ? await nodeAreaMap(input.domainId, instanceIds, input.spaceId) : { nodeArea: {}, labels: {} }
+    input.groupBy === 'area' ? await locationAreaMap(input.domainId, instanceIds, input.spaceId) : { locationArea: {}, labels: {} }
+  const shiftCtx = input.groupBy === 'shift' ? await shiftContext(input.domainId, instanceIds) : {}
   const kpi = foldKpi(events, { fromMs, toMs }, {
     groupBy: input.groupBy,
-    nodeArea: areaMap.nodeArea,
+    locationArea: areaMap.locationArea,
+    ...shiftCtx,
     groupLimit: input.groupLimit
   })
+  /*
+   * 목표를 **폴드 뒤, 그룹 조립 앞**에 읽는다 — 전체 판정과 축별 판정이 같은 목록에서 나와야
+   * 두 곳의 임계가 갈라지지 않는다. 폴드 자체는 목표를 모른다(사실 층과 판정 층의 분리).
+   */
+  const scoped = await loadTargets(input.domainId, input.spaceId, instanceIds, input.groupBy)
+  const verdicts = judgeTargets(kpi, scoped.overall)
+  const groupTargets = scoped.byAxisKey
+
   const window = {
     fromTime: new Date(fromMs).toISOString(),
     toTime: new Date(toMs).toISOString(),
@@ -361,7 +453,8 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
      * 있는데 없다고 말하게 된다). */
     const prev = foldKpi(prevEvents, w, {
       groupBy: input.groupBy,
-      nodeArea: areaMap.nodeArea,
+      locationArea: areaMap.locationArea,
+      ...shiftCtx, // 비교 구간도 **같은 교대 정의**로 접는다(정의가 다르면 축이 어긋난다)
       groupLimit: input.groupBy ? 100 : undefined
     })
     prevCappedFlag = prevCapped
@@ -397,10 +490,16 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
   const groups = kpi.groups
     ? {
         by: kpi.groups.by,
-        items: (crossed?.items ?? kpi.groups.items).map(g => ({
-          ...g,
-          ...(areaMap.labels[g.key] ? { label: areaMap.labels[g.key] } : {})
-        })),
+        items: (crossed?.items ?? kpi.groups.items).map(g => {
+          /* 축의 이 값에 목표가 걸려 있으면 판정을 함께 낸다 — "이 구역만 목표가 다르다" 를
+             표에서 바로 볼 수 있게. 목표가 없는 축값에는 필드를 만들지 않는다. */
+          const gt = judgeGroupTargets(g as any, groupTargets[g.key])
+          return {
+            ...g,
+            ...(areaMap.labels[g.key] ? { label: areaMap.labels[g.key] } : {}),
+            ...(gt.length ? { targets: gt } : {})
+          }
+        }),
         ...(crossed?.disappeared.length
           ? {
               disappeared: crossed.disappeared.map(d => ({
@@ -413,13 +512,23 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
           ? { truncated: kpi.groups.truncated, truncatedTasks: kpi.groups.truncatedTasks ?? 0 }
           : {}),
         ...(input.groupBy === 'area' &&
-        Object.keys(areaMap.nodeArea).length === 0 &&
+        Object.keys(areaMap.locationArea).length === 0 &&
         kpi.groups.items.some(g => g.key === 'unknown')
-          ? { note: 'nodes carry no area (parentId) in this twin — cannot break down by area. this is NOT "no work in areas".' }
+          ? { note: 'locations carry no area (parentId) in this twin — cannot break down by area. this is NOT "no work in areas".' }
           : {})
       }
     : undefined
 
+  /*
+   * 목표 대비 판정 — **사실 계산 뒤에 얹는다.**
+   *
+   * 폴드는 목표를 모른다(사실만 낸다). 목표를 아는 순간 "세는 규칙" 과 "잘했나 판정하는 규칙" 이
+   * 한 함수에 섞이고, 목표가 바뀔 때마다 사실 계산을 건드리게 된다. 그래서 조회 층에서 목표를
+   * 실어 오고, 판정은 순수 함수(`judgeTargets`)가 한다.
+   *
+   * **목표가 없으면 판정하지 않는다** — 필드 자체를 만들지 않는다. 전부 "목표 없음" 으로 채우면
+   * 화면이 회색 노이즈가 되고, 목표가 있는 지표가 묻힌다.
+   */
   /* 폴드가 돌려준 raw 창(ms)은 버린다 — 위의 ISO 창이 사람이 읽을 정본이다. */
   const { window: _rawWindow, groups: _rawGroups, ...rest } = kpi
   return {
@@ -430,6 +539,7 @@ export async function computeTwinKpi(input: TwinKpiInput): Promise<TwinKpiOutput
     ...rest,
     ...(buckets ? { buckets } : {}),
     ...(groups ? { groups } : {}),
+    ...(verdicts.length ? { targets: verdicts } : {}),
     ...(comparison ? { comparison } : {})
   }
 }