@things-factory/headless-twin 10.0.8 → 10.0.10

package/test/kpi-baseline-db.test.ts

@@ -0,0 +1,216 @@
+/*
+ * ★ 여러 구간 동시 비교 — **실 DB로 배관을 넘어 본다.**
+ *
+ * 분포 산수는 `kpi-baseline.test.ts`(순수)가 지킨다. 여기서 지키는 것은 **호스트 배관**이다:
+ * 창을 하루씩 뒤로 옮겨 **각 창을 따로 읽는가** · 그 창을 같은 규칙으로 접는가 · 지표 값을 정본 표
+ * (`TWIN_METRIC`)로 꺼내는가 · 기록 없는 날을 결측으로 남기는가.
+ *
+ * 이 배관은 **경계를 넘어야만** 틀리는 것이 드러난다. 실제로 앱의 시뮬 트윈은 저널이 두 시간 남짓이라
+ * "지난 7일" 을 물어도 과거 창이 모두 비어 있어(정직하게 자리를 거부한다) 분포 경로를 한 번도 밟지
+ * 못했다. 그래서 여러 날에 걸친 저널을 손으로 심어 그 경로를 통과시킨다.
+ *
+ * 실 엔티티·실 네이밍 전략의 sqlite in-memory 스키마에 **빌드 산출물**을 실행한다.
+ * **소스를 고친 뒤에는 `npm run build:server` 를 먼저 돌려야 반영된다.**
+ */
+import { test, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { createRequire } from 'node:module'
+import type { DataSource } from 'typeorm'
+
+const req = createRequire(import.meta.url)
+const { NamingStrategy, addDataSource, entities: shellEntities, Domain } = req('@things-factory/shell')
+const { entities: authEntities } = req('@things-factory/auth-base')
+const { entities: twinEntities } = req('../dist-server/service/index.js')
+const { computeTwinKpi } = req('../dist-server/engine/index.js')
+const { TwinEvent } = req('../dist-server/service/twin-event/twin-event.js')
+const { TwinInstance } = req('../dist-server/service/twin-instance/twin-instance.js')
+const { DataSource: TypeOrmDataSource } = req('typeorm')
+
+let ds: DataSource
+let domainId: string
+
+const INSTANCE = 'baseline-probe'
+const MS_DAY = 24 * 60 * 60_000
+
+/** 창의 끝 — 고정 시각을 쓴다(테스트가 벽시계에 흔들리지 않게). */
+const TO = Date.parse('2026-03-10T10:00:00.000Z')
+const FROM = TO - 60 * 60_000
+
+/**
+ * 완료 한 건 = 시작 + 완료 두 줄. 소요시간이 짝맞춤에서 나오므로 둘 다 필요하다.
+ * 완료 시각이 창 안에 들면 그 창의 성과로 센다.
+ */
+function taskRows(dayBack: number, count: number, workMs: number, revBase: number) {
+  const rows: any[] = []
+  const endBase = TO - dayBack * MS_DAY - 60_000 // 창 끝 1분 전에 완료
+  for (let i = 0; i < count; i++) {
+    const taskId = `t-${dayBack}-${i}`
+    const done = endBase - i * 1000
+    const started = done - workMs
+    rows.push(
+      {
+        domain: { id: domainId },
+        instanceId: INSTANCE,
+        revision: revBase + i * 2,
+        eventType: 'task.status',
+        eventTime: new Date(started).toISOString(),
+        payload: { data: { taskId, status: 'in-progress', resourceRef: 'fk-1' } }
+      },
+      {
+        domain: { id: domainId },
+        instanceId: INSTANCE,
+        revision: revBase + i * 2 + 1,
+        eventType: 'task.status',
+        eventTime: new Date(done).toISOString(),
+        /* 완료 어휘는 **커널이 소유한다**(`foldTaskRecords`) — 'done' 이 아니라 'completed' 다.
+           처음에 'done' 으로 심었더니 창은 잡히는데 건수가 0 이었다(이 DB 스펙이 그것을 잡았다). */
+        payload: { data: { taskId, status: 'completed', resourceRef: 'fk-1' } }
+      }
+    )
+  }
+  return rows
+}
+
+before(async () => {
+  ds = new TypeOrmDataSource({
+    type: 'sqlite',
+    database: ':memory:',
+    synchronize: true,
+    dropSchema: true,
+    namingStrategy: new NamingStrategy(),
+    entities: [...shellEntities, ...authEntities, ...twinEntities],
+    logging: false
+  })
+  await ds.initialize()
+  addDataSource('default', ds)
+  const d = await ds.getRepository(Domain).save({ name: 'baseline-test', subdomain: 'baseline-test' } as any)
+  domainId = d.id
+
+  await ds.getRepository(TwinInstance).save({
+    domain: { id: domainId },
+    instanceId: INSTANCE,
+    kind: 'wms',
+    realityMode: 'sim-experiment', /* 선언은 이제 필수 — 비워 두면 읽는 자리마다 기본값을 고른다 */
+    purpose: 'operational',
+    status: 'stopped',
+    model: { locations: [{ id: 'dock', type: 'dock', capacity: 10 }], equipment: [{ id: 'fk-1', kind: 'forklift', homeLocation: 'dock' }] }
+  } as any)
+
+  /*
+   * 지금 창 20건 · 어제 40건 · 그제 60건 · **3일 전은 기록 없음** · 4일 전 80건.
+   * 3일 전을 비워 두는 것이 이 스펙의 요점이다 — 그 날이 결측으로 남고 분포에서 빠지는지 본다
+   * (조용히 빼면 "지난 4일" 이 실제로는 3일이었다는 것을 아무도 모른다).
+   */
+  const rows = [
+    ...taskRows(0, 20, 30_000, 1000),
+    ...taskRows(1, 40, 40_000, 3000),
+    ...taskRows(2, 60, 50_000, 6000),
+    ...taskRows(4, 80, 60_000, 9000)
+  ]
+  await ds.getRepository(TwinEvent).save(rows)
+})
+
+after(async () => {
+  await ds?.destroy()
+})
+
+const kpi = (periods: number, stride?: 'day' | 'week') =>
+  computeTwinKpi({
+    domainId,
+    instanceId: INSTANCE,
+    fromTime: new Date(FROM).toISOString(),
+    toTime: new Date(TO).toISOString(),
+    baseline: { periods, ...(stride ? { stride } : {}) }
+  })
+
+test('과거 창을 하루씩 따로 읽어 분포를 만든다', async () => {
+  const out: any = await kpi(4)
+  const tasks = out.baseline.metrics.find((m: any) => m.metric === 'throughput.tasks')
+
+  assert.equal(out.baseline.stride, 'day')
+  assert.equal(out.baseline.periods, 4)
+  assert.equal(tasks.current, 20, '지금 창')
+  /* 어제 40 · 그제 60 · 3일 전 없음 · 4일 전 80. */
+  assert.deepEqual([tasks.min, tasks.median, tasks.max], [40, 60, 80])
+})
+
+test('기록 없는 날을 **결측으로 남긴다** — 요청한 창 수와 측정된 수를 함께 답한다', async () => {
+  const out: any = await kpi(4)
+  const tasks = out.baseline.metrics.find((m: any) => m.metric === 'throughput.tasks')
+
+  assert.equal(tasks.requested, 4)
+  assert.equal(tasks.measuredCount, 3, '3일 전은 기록이 없다')
+  assert.equal(tasks.samples.length, 4, '창 자체는 네 개 모두 돌려준다')
+  assert.deepEqual(tasks.samples.map((s: any) => s.measured), [true, true, false, true])
+  assert.deepEqual(tasks.samples.map((s: any) => s.value), [40, 60, undefined, 80])
+})
+
+test('처리량이 지난 며칠 중 가장 낮으면 worst — 이 축이 답하려던 질문', async () => {
+  /* 예전에는 "어제보다 나아졌나" 까지만 답할 수 있었다. 지금 창(20)은 어제(40)보다도 낮고
+     최근 어느 날보다도 낮다 — 그것을 한 번에 말할 수 있어야 한다. */
+  const out: any = await kpi(4)
+  const tasks = out.baseline.metrics.find((m: any) => m.metric === 'throughput.tasks')
+
+  assert.equal(tasks.standing, 'worst')
+  assert.equal(tasks.rank, 1, '오름차순 첫째')
+  assert.equal(tasks.rankOf, 4, '표본 3 + 현재 1')
+})
+
+test('방향은 지표가 안다 — 작업시간이 가장 짧으면 best', async () => {
+  const out: any = await kpi(4)
+  const work = out.baseline.metrics.find((m: any) => m.metric === 'workTime.p50Ms')
+
+  assert.equal(work.current, 30_000)
+  assert.deepEqual([work.min, work.max], [40_000, 60_000])
+  assert.equal(work.standing, 'best', '짧을수록 좋다')
+})
+
+test('구간 수를 줄이면 그만큼만 본다 — 창을 지어내지 않는다', async () => {
+  const out: any = await kpi(1)
+  const tasks = out.baseline.metrics.find((m: any) => m.metric === 'throughput.tasks')
+
+  assert.equal(tasks.requested, 1)
+  assert.equal(tasks.measuredCount, 1)
+  /* 표본 하나는 분포가 아니다. */
+  assert.equal(tasks.noPosition, 'too-few-samples')
+  assert.equal(tasks.standing, undefined)
+})
+
+test('주 단위는 같은 요일을 본다 — 하루 전 기록에 걸리지 않는다', async () => {
+  const out: any = await kpi(2, 'week')
+  const tasks = out.baseline.metrics.find((m: any) => m.metric === 'throughput.tasks')
+
+  assert.equal(out.baseline.stride, 'week')
+  /* 심어 둔 기록은 최근 나흘뿐이라 지난주 같은 요일에는 아무것도 없다 — 지어내지 않는다. */
+  assert.equal(tasks.measuredCount, 0)
+  assert.equal(tasks.noPosition, 'too-few-samples')
+})
+
+test('요청하지 않으면 분포를 만들지 않는다 — 조회가 공짜가 아니다', async () => {
+  const out: any = await computeTwinKpi({
+    domainId,
+    instanceId: INSTANCE,
+    fromTime: new Date(FROM).toISOString(),
+    toTime: new Date(TO).toISOString()
+  })
+
+  assert.equal(out.baseline, undefined)
+})
+
+test('지금 창에 기록이 없어도 분포는 낸다 — 그때가 가장 알고 싶은 순간이다', async () => {
+  /* 심어 둔 기록이 없는 시각을 창으로 잡는다(3일 전). 평소엔 일이 있었는데 지금 없다 = 멈춘 신호. */
+  const quietTo = TO - 3 * MS_DAY
+  const out: any = await computeTwinKpi({
+    domainId,
+    instanceId: INSTANCE,
+    fromTime: new Date(quietTo - 60 * 60_000).toISOString(),
+    toTime: new Date(quietTo).toISOString(),
+    baseline: { periods: 2 }
+  })
+
+  assert.equal(out.measured, false, '지금 창에는 측정할 기록이 없다')
+  assert.ok(out.baseline, '그래도 분포는 낸다')
+  const tasks = out.baseline.metrics.find((m: any) => m.metric === 'throughput.tasks')
+  assert.equal(tasks.measuredCount, 1, '4일 전 하루만 걸린다(5일 전은 기록 없음)')
+  assert.equal(tasks.samples.find((s: any) => s.measured).value, 80)
+})

package/test/kpi-baseline.test.ts

@@ -0,0 +1,196 @@
+/*
+ * 여러 구간 동시 비교 — **"어제보다 나아졌다" 를 넘어선다.**
+ *
+ * 비교 축이 한 구간만 볼 때는 판단이 한 문장에서 멈췄다: "어제보다 나아졌다." 어제도 나빴으면 쓸모가
+ * 없다. 최근 며칠의 같은 시간대를 함께 보면 목표 없이도 "지난 7일 중 가장 낮다" 를 말할 수 있다.
+ *
+ * 이 테스트가 지키는 것은 산수보다 **정직성**이다. 이 도메인에서 값이 없는 것을 0 으로 읽으면 시간
+ * 지표는 "낮을수록 좋다" 라서 **일이 없던 구간이 최고 성적으로** 보고된다 — 목표 판정에서 이미 겪은
+ * 결함이라 여기서 되풀이하지 않는다.
+ */
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  MAX_BASELINE_PERIODS,
+  baselineWindows,
+  summarizeBaseline,
+  type MetricSpecLike
+} from '../server/engine/kpi-baseline.ts'
+
+const MS_DAY = 24 * 60 * 60_000
+const HOUR = 60 * 60_000
+
+/* 실제 표(`TWIN_METRIC`)의 성질만 흉내 낸 최소 사양 — 어휘는 그쪽이 소유한다. */
+const SPECS = {
+  'throughput.tasks': { direction: 'higher', unit: 'count' },
+  'workTime.p50Ms': { direction: 'lower', unit: 'ms' }
+} satisfies Record<string, MetricSpecLike>
+
+type M = keyof typeof SPECS
+
+/** 과거 창 표본 — 값만 신경 쓰는 테스트를 짧게 쓰기 위한 도우미. */
+const sample = (dayBack: number, values: Partial<Record<M, number | undefined>>) => ({
+  fromMs: -dayBack * MS_DAY,
+  toMs: -dayBack * MS_DAY + HOUR,
+  values
+})
+
+test('같은 시간대를 하루씩 뒤로 옮긴다 — 가까운 것부터', () => {
+  const from = 10 * MS_DAY
+  const to = from + HOUR
+
+  const windows = baselineWindows(from, to, 3)
+
+  assert.equal(windows.length, 3)
+  assert.deepEqual(windows[0], { fromMs: from - MS_DAY, toMs: to - MS_DAY }, '어제가 먼저')
+  assert.deepEqual(windows[2], { fromMs: from - 3 * MS_DAY, toMs: to - 3 * MS_DAY })
+  /* 길이는 그대로여야 한다 — 길이가 달라지면 처리량을 비교할 수 없다. */
+  for (const w of windows) assert.equal(w.toMs - w.fromMs, to - from)
+})
+
+test('주 단위는 같은 요일을 본다 — 주말·평일이 섞이지 않게', () => {
+  const from = 30 * MS_DAY
+  const windows = baselineWindows(from, from + HOUR, 2, 'week')
+
+  assert.equal(windows[0].fromMs, from - 7 * MS_DAY)
+  assert.equal(windows[1].fromMs, from - 14 * MS_DAY)
+})
+
+test('구간 수에 상한이 있고, 이상한 입력은 창을 만들지 않는다', () => {
+  assert.equal(baselineWindows(0, HOUR, 999).length, MAX_BASELINE_PERIODS)
+  assert.equal(baselineWindows(0, HOUR, 0).length, 0)
+  assert.equal(baselineWindows(0, HOUR, -3).length, 0)
+  /* 끝이 시작보다 앞이면 창이 아니다 — 지어내지 않는다. */
+  assert.equal(baselineWindows(HOUR, 0, 3).length, 0)
+  assert.equal(baselineWindows(Number.NaN, HOUR, 3).length, 0)
+})
+
+test('분포는 측정된 표본만으로 만들되, **결측 창도 남긴다**', () => {
+  /* 빼고 말하면 "지난 5일" 이 실제로는 3일이었다는 것을 아무도 모른다. */
+  const [row] = summarizeBaseline({ 'throughput.tasks': SPECS['throughput.tasks'] }, { 'throughput.tasks': 50 }, [
+    sample(1, { 'throughput.tasks': 40 }),
+    sample(2, {}), // 기록 없음
+    sample(3, { 'throughput.tasks': 60 }),
+    sample(4, { 'throughput.tasks': undefined }), // 기록 없음
+    sample(5, { 'throughput.tasks': 80 })
+  ])
+
+  assert.equal(row.requested, 5)
+  assert.equal(row.measuredCount, 3)
+  assert.equal(row.samples.length, 5, '요청한 창 전부를 돌려준다')
+  assert.deepEqual(
+    row.samples.map(s => s.measured),
+    [true, false, true, false, true]
+  )
+  assert.deepEqual([row.min, row.median, row.max], [40, 60, 80])
+})
+
+test('현재 값이 없으면 순위를 내지 않는다 — 결측을 0 으로 읽으면 최고 성적으로 뒤집힌다', () => {
+  /* 시간 지표는 "낮을수록 좋다" 라서 결측을 0 으로 놓으면 **일이 없던 구간이 1등**이 된다. */
+  const [row] = summarizeBaseline({ 'workTime.p50Ms': SPECS['workTime.p50Ms'] }, {}, [
+    sample(1, { 'workTime.p50Ms': 30_000 }),
+    sample(2, { 'workTime.p50Ms': 40_000 })
+  ])
+
+  assert.equal(row.current, undefined)
+  assert.equal(row.standing, undefined)
+  assert.equal(row.rank, undefined)
+  assert.equal(row.noPosition, 'no-current')
+  /* 그래도 분포 자체는 낸다 — "평소 얼마였나" 는 여전히 답할 수 있는 사실이다. */
+  assert.deepEqual([row.min, row.max], [30_000, 40_000])
+})
+
+test('표본이 둘 미만이면 순위를 내지 않는다 — 하나를 분포라 부를 수 없다', () => {
+  const one = summarizeBaseline({ 'throughput.tasks': SPECS['throughput.tasks'] }, { 'throughput.tasks': 10 }, [
+    sample(1, { 'throughput.tasks': 40 })
+  ])[0]
+
+  assert.equal(one.noPosition, 'too-few-samples')
+  assert.equal(one.standing, undefined)
+
+  const none = summarizeBaseline({ 'throughput.tasks': SPECS['throughput.tasks'] }, { 'throughput.tasks': 10 }, [])[0]
+  assert.equal(none.noPosition, 'too-few-samples')
+  assert.equal(none.min, undefined)
+})
+
+test('방향을 지표가 안다 — 같은 자리가 처리량과 소요시간에서 반대로 읽힌다', () => {
+  const past = [sample(1, { 'throughput.tasks': 40, 'workTime.p50Ms': 40_000 }), sample(2, { 'throughput.tasks': 60, 'workTime.p50Ms': 60_000 }), sample(3, { 'throughput.tasks': 80, 'workTime.p50Ms': 80_000 })]
+
+  /* 값이 표본 전부보다 크다 — 처리량은 최고, 소요시간은 최악이다. */
+  const rows = summarizeBaseline(SPECS, { 'throughput.tasks': 90, 'workTime.p50Ms': 90_000 }, past)
+  const by = Object.fromEntries(rows.map(r => [r.metric, r]))
+
+  assert.equal(by['throughput.tasks'].standing, 'best')
+  assert.equal(by['workTime.p50Ms'].standing, 'worst')
+  /* 순위는 **방향 없는 사실**이다 — 둘 다 오름차순 4번째다. */
+  assert.equal(by['throughput.tasks'].rank, 4)
+  assert.equal(by['workTime.p50Ms'].rank, 4)
+  assert.equal(by['workTime.p50Ms'].rankOf, 4)
+})
+
+test('전부보다 나쁘면 worst — 처리량이 지난 3일 중 가장 낮은 경우', () => {
+  const [row] = summarizeBaseline({ 'throughput.tasks': SPECS['throughput.tasks'] }, { 'throughput.tasks': 10 }, [
+    sample(1, { 'throughput.tasks': 40 }),
+    sample(2, { 'throughput.tasks': 60 }),
+    sample(3, { 'throughput.tasks': 80 })
+  ])
+
+  assert.equal(row.standing, 'worst')
+  assert.equal(row.rank, 1, '오름차순 첫째')
+})
+
+test('중앙값과 같으면 typical — 임의의 임계를 만들지 않는다', () => {
+  const [row] = summarizeBaseline({ 'throughput.tasks': SPECS['throughput.tasks'] }, { 'throughput.tasks': 60 }, [
+    sample(1, { 'throughput.tasks': 40 }),
+    sample(2, { 'throughput.tasks': 60 }),
+    sample(3, { 'throughput.tasks': 80 })
+  ])
+
+  assert.equal(row.standing, 'typical')
+})
+
+test('중앙값 양쪽을 방향에 따라 구분한다', () => {
+  const past = [sample(1, { 'throughput.tasks': 40 }), sample(2, { 'throughput.tasks': 60 }), sample(3, { 'throughput.tasks': 80 })]
+  const spec = { 'throughput.tasks': SPECS['throughput.tasks'] }
+
+  assert.equal(summarizeBaseline(spec, { 'throughput.tasks': 70 }, past)[0].standing, 'better-than-typical')
+  assert.equal(summarizeBaseline(spec, { 'throughput.tasks': 50 }, past)[0].standing, 'worse-than-typical')
+
+  /* 소요시간은 반대다 — 중앙값보다 낮은 것이 좋다. */
+  const lower = { 'workTime.p50Ms': SPECS['workTime.p50Ms'] }
+  const pastMs = [sample(1, { 'workTime.p50Ms': 40 }), sample(2, { 'workTime.p50Ms': 60 }), sample(3, { 'workTime.p50Ms': 80 })]
+  assert.equal(summarizeBaseline(lower, { 'workTime.p50Ms': 50 }, pastMs)[0].standing, 'better-than-typical')
+  assert.equal(summarizeBaseline(lower, { 'workTime.p50Ms': 70 }, pastMs)[0].standing, 'worse-than-typical')
+})
+
+test('짝수 표본의 중앙값은 가운데 둘의 평균이다', () => {
+  const [row] = summarizeBaseline({ 'throughput.tasks': SPECS['throughput.tasks'] }, { 'throughput.tasks': 55 }, [
+    sample(1, { 'throughput.tasks': 40 }),
+    sample(2, { 'throughput.tasks': 50 }),
+    sample(3, { 'throughput.tasks': 60 }),
+    sample(4, { 'throughput.tasks': 70 })
+  ])
+
+  assert.equal(row.median, 55)
+  assert.equal(row.standing, 'typical')
+})
+
+test('열거된 지표만 낸다 — 모르는 이름을 짐작하지 않는다', () => {
+  const rows = summarizeBaseline({ 'throughput.tasks': SPECS['throughput.tasks'] }, { 'throughput.tasks': 10, 'made.up': 99 } as any, [
+    sample(1, { 'throughput.tasks': 5 } as any)
+  ])
+
+  assert.deepEqual(rows.map(r => r.metric), ['throughput.tasks'])
+})
+
+test('무한·NaN 은 측정으로 세지 않는다', () => {
+  const [row] = summarizeBaseline({ 'throughput.tasks': SPECS['throughput.tasks'] }, { 'throughput.tasks': Number.NaN }, [
+    sample(1, { 'throughput.tasks': Number.POSITIVE_INFINITY }),
+    sample(2, { 'throughput.tasks': 40 }),
+    sample(3, { 'throughput.tasks': 60 })
+  ])
+
+  assert.equal(row.measuredCount, 2, '무한은 표본이 아니다')
+  assert.equal(row.noPosition, 'no-current', 'NaN 은 값이 아니다')
+})