@things-factory/headless-twin 10.0.8 → 10.0.10

package/server/engine/entity-delta.ts

@@ -1,169 +0,0 @@
-/*
- * 트윈 State 스냅샷 → 라이브 바인딩 delta 목록 (순수 매핑 — pubsub/도메인 무관 → 단위 테스트 가능).
- * publishEntityData 가 이 목록을 엔티티별 시그니처로 dedup 후 data(tag) 채널로 발행한다.
- *
- * ── 규율: 레퍼런스가 아는 것은 **전부** 내보낸다 ────────────────────────────
- * 트윈에서 사소한 속성은 없다. 소속 구역·소속 팔레트·수량·만료처럼 곁가지로 보이는 값이 실제로는
- * 구역 롤업·적재 표현·로트 추적의 전제다. 그래서 여기서 **필드를 손으로 골라 담지 않는다.**
- *
- * 예전에는 엔티티마다 필요할 것 같은 필드만 열거했고, 그 결과 계약에 있는 것이 조용히 누락됐다
- * (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 {
-  tag: string
-  data: any
-}
-
-/** 집약 고정 태그 — 클라 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__'
-
-/**
- * 통과시키지 않는 필드 — **빼는 데는 이유가 필요하다.**
- *
- * · `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 {
-    overall: Math.round((o.overall ?? 0) * 100),
-    availability: Math.round((o.availability ?? 0) * 100),
-    performance: Math.round((o.performance ?? 0) * 100),
-    quality: Math.round((o.quality ?? 0) * 100),
-    good: o.goodCount ?? 0,
-    scrap: o.scrapCount ?? 0
-  }
-}
-
-/**
- * 엔티티 하나의 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?.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 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: 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) })
-  }
-
-  /* ── 집약 뷰 ──────────────────────────────────────────────────────────────
-   * 런타임에 생기고 사라지는 엔티티(오더·작업·물품)는 보드에 개별 배치할 수 없다 → 한 컴포넌트가
-   * 전체를 추적하는 집약 태그를 항상 방출한다. */
-  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: 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/service/twin-event/backfill-keys.ts

@@ -1,72 +0,0 @@
-import { IsNull } from 'typeorm'
-
-import { getRepository } from '@things-factory/shell'
-
-import { TwinEvent } from './twin-event.js'
-import { twinEventKeys } from './twin-event-keys.js'
-
-/*
- * 승격 검색 키 백필 — 컬럼이 생기기 **전에** 쌓인 저널 행을 채운다.
- *
- * 이게 없으면 검색은 "오늘부터의 이력" 만 찾는다. 사용자에게는 그냥 **과거가 없는 것으로 보이고**,
- * 그건 이번에 고치려던 결함(조용히 빠진 데이터)과 정확히 같은 종류다.
- *
- * 성질:
- *  · 멱등 — 이미 채워진 행은 건드리지 않는다(bizStep IS NULL 인 것만 집는다).
- *  · 재개 가능 — 중간에 죽어도 다음 기동에서 남은 것부터 이어간다.
- *  · 조각내서 — 한 번에 다 읽지 않는다. 저널은 크다는 전제로 만든다.
- *  · payload 는 손대지 않는다 — 정본은 그대로 두고 파생 색인만 채운다.
- *
- * 아주 큰 운영 저널이라면 기동 시 백그라운드보다 **마이그레이션으로 한 번** 도는 편이 낫다.
- * 이 함수를 그대로 부르면 되므로 경로는 하나다.
- */
-
-const CHUNK = 1000
-
-export interface BackfillResult {
-  /** 실제로 갱신한 행 수. */
-  updated: number
-  /** 훑었지만 payload 가 없어 채울 수 없던 행 수 — 0 이 아니면 인제스트 쪽을 봐야 한다. */
-  skipped: number
-}
-
-/**
- * 남은 행을 전부 채운다. 진행 상황을 로그로 남긴다 — 조용히 오래 도는 작업은
- * 멈춘 것과 구분되지 않는다.
- */
-export async function backfillTwinEventKeys(): Promise<BackfillResult> {
-  const repo = getRepository(TwinEvent)
-  let updated = 0
-  let skipped = 0
-  let round = 0
-
-  for (;;) {
-    /* bizStep 은 이벤트 타입에서라도 유추되므로 **정상 인제스트라면 반드시 채워진다** —
-     * 즉 NULL 은 "승격 이전 행" 의 확실한 표식이다. epc 로 판정하면 품목 없는 이벤트를
-     * 매번 다시 집어 무한히 돈다. */
-    const rows = await repo.find({ where: { bizStep: IsNull() }, take: CHUNK, order: { revision: 'ASC' } })
-    if (rows.length === 0) break
-
-    const dirty: TwinEvent[] = []
-    for (const row of rows) {
-      if (!row.payload) {
-        skipped++
-        continue
-      }
-      Object.assign(row, twinEventKeys(row.payload))
-      dirty.push(row)
-    }
-    if (dirty.length) await repo.save(dirty, { chunk: 500 })
-    updated += dirty.length
-
-    /* payload 가 없는 행만 남으면 같은 조각을 영원히 다시 읽는다 — 진도가 없으면 멈춘다. */
-    if (dirty.length === 0) break
-
-    if (++round % 10 === 0) console.log(`[twin-event backfill] ${updated} rows filled…`)
-  }
-
-  if (updated || skipped) {
-    console.log(`[twin-event backfill] done — ${updated} filled, ${skipped} skipped (no payload)`)
-  }
-  return { updated, skipped }
-}