@things-factory/headless-twin 10.1.29 → 10.1.32

package/server/service/twin-attention/twin-attention-query.ts

@@ -28,17 +28,24 @@ export class TwinAttentionQuery {
      * 경고는 **합집합이 그대로 뜻이 있는 유일한 렌즈**다. 예측은 합칠 수 없다(P50 두 개를 더할 수 없다) —
      * 그래서 예측은 여전히 인스턴스별로 답하고 화면이 나란히 놓는다.
      */
-    @Arg('spaceId', { nullable: true }) spaceId?: string,
-    /** 상위 몇 건만 — 말하지 않으면 자르지 않는다. 전체 개수는 `twinAttentionDigest` 가 함께 답한다. */
-    @Arg('limit', type => Int, { nullable: true }) limit?: number
+    @Arg('spaceId', { nullable: true }) spaceId?: string
+    /*
+     * ── 자르는 인자는 여기 없다 (2026-09-19, 수석 아키텍트 판정) ──────────────
+     *
+     * `limit` 이 있었다. 자르면서 **몇 건을 잘랐는지는 답에 싣지 못했다** — 답이 맨 목록이라 실을
+     * 자리가 없었기 때문이다. 자를 수 있는 문이 잘린 수를 못 말하면, 스무 건만 받은 화면은 그것이
+     * 전부인지 이백 중 스무 건인지 구별할 수 없다.
+     *
+     * 자르려는 소비자는 `twinAttentionDigest` 를 쓴다 — 그 문은 `attentionTotal` 을 함께 답하고,
+     * 자리별 색을 **전량을 근거로** 계산한다. 이 문은 자르지 않는다.
+     */
   ): Promise<any[]> {
-    if (spaceId) return (await TwinEngine.attentionsOfSpace(context.state.domain.id, spaceId, limit ?? undefined)).attentions
+    if (spaceId) return (await TwinEngine.attentionsOfSpace(context.state.domain.id, spaceId)).attentions
     if (!instanceId || !TwinEngine.owns(context.state.domain.id, instanceId)) return [] // 테넌트 격리
     // 라이브 커널 스냅샷(fresh) 우선 — snapshot()=resync() 는 캐시라 커맨드 델타 지연(recover 와 동일 원천 사용).
     const kernel = TwinEngine.kernel(context.state.domain.id, instanceId)
     const snap = kernel?.getSnapshot?.() ?? TwinEngine.snapshot(context.state.domain.id, instanceId)
-    const list = snap?.attentions ?? []
-    return limit && limit > 0 ? digestAttentions(list, limit).attentions : list
+    return snap?.attentions ?? []
   }
 
   /**

package/server/service/twin-forecast/forecast-metrics.ts

@@ -15,6 +15,8 @@
  * 그래서 지점을 직접 더하지 않고 **구간 값**을 읽는다.
  */
 
+import { isFlowOrder, isOrderTerminal } from '@operato/ops-contract'
+
 /** 스냅샷 → 수 하나. 값이 없으면 0 이 아니라 **그 지표를 그릴 수 없다**는 뜻이지만, 그래프 계약이
  *  수를 요구하므로 0 을 낸다 — 그래서 에너지 지표는 「없음」이 0 과 헷갈리지 않는 것만 골랐다. */
 export type MetricFn = (s: any) => number
@@ -23,10 +25,33 @@ export const FORECAST_METRICS: Record<string, MetricFn> = {
   items: s => (s?.items || []).length,
   occupancy: s => (s?.locations || []).reduce((a: number, n: any) => a + (n.occupancy || 0), 0),
   tasks: s => (s?.tasks || []).length,
-  orders: s => (s?.orders || []).length,
+  /*
+   * ── 세는 것은 **흐름 오더**다 (2026-09-19, ADR-0076 보탬 ⑥) ────────────────
+   *
+   * 받는 오더(입고 · 반품 입고)는 도착이 세우고 도착이 이행한다. 그대로 세면 「나간 것」이 받을 때마다
+   * 한 건씩 늘고 백로그는 영영 안 줄어든다 — 예측 그래프가 있지도 않은 일을 그린다. 무엇이 흐름
+   * 오더인지는 계약의 `isFlowOrder` 한 곳이 정한다(여기서 `kind` 를 다시 적지 않는다).
+   */
+  orders: s => (s?.orders || []).filter(isFlowOrder).length,
   // 이행 지표 — 라이브 예측의 핵심 질문("언제 다 나가나·백로그 언제 풀리나").
-  shipped: s => (s?.orders || []).filter((o: any) => o.status === 'shipped').length,
-  backlog: s => (s?.orders || []).filter((o: any) => o.status !== 'shipped' && o.status !== 'cancelled').length,
+  shipped: s => (s?.orders || []).filter(isFlowOrder).filter((o: any) => o.status === 'shipped').length,
+  /*
+   * ── 백로그는 **「종결인가」**로 묻는다 (2026-09-19) ─────────────────────────
+   *
+   * 낱말 둘(`shipped`·`cancelled`)로 물으면 **원본이 다른 낱말을 쓰는 미러에서 끝난 오더가 영영
+   * 백로그에 남는다.** `status` 는 열린 축이고(표준도 `RequestState` 를 열거하지 않는다) 실 시스템은
+   * `completed`·`FINISHED` 를 쓴다 — 그 트윈의 백로그 곡선은 내려가지 않는다. 종결 판정은 커널이
+   * 한 곳에서 한다(`isOrderTerminal` — 낱말이 아니라 **양**을 1차 근거로 본다).
+   *
+   * `shipped` 한 낱말은 남는다. 그것은 이 커널이 **자기가 쓰는 말**이고(WMS 의 출하 완료), 계약의
+   * 종결 목록(`completed` · `cancelled`)에는 없다. 양을 말하지 않는 스냅샷에서 그 오더가 백로그로
+   * 되돌아오지 않게 둘을 함께 본다 — 빼는 쪽이라 이 셈이 전보다 커지는 일은 없다. 커널의 낱말이
+   * 계약의 종결 목록에 들어오는 날 이 줄이 지워진다(아키텍트에게 올림).
+   */
+  backlog: s =>
+    (s?.orders || [])
+      .filter(isFlowOrder)
+      .filter((o: any) => !isOrderTerminal(o) && o.status !== 'shipped').length,
 
   /*
    * ── 에너지 ────────────────────────────────────────────────────────────────

package/server/service/twin-journal/twin-journal-query.ts

@@ -42,6 +42,22 @@ function toDateValue(v: any): any {
   return Array.isArray(v) ? v.map(one) : one(v)
 }
 
+/**
+ * 자유 검색어가 펼쳐지는 축 — **목록과 건수가 같은 것을 본다**(2026-09-19).
+ *
+ * 전부 인덱스 가능한 승격 컬럼이다(payload JSON 안이 아니라). 프레임워크 질의 빌더는 이 목록에 없는
+ * 컬럼의 LIKE 를 경고 후 무시한다 — 인덱스 없는 전체 스캔을 막기 위해서다.
+ *
+ * ── 왜 상수인가 ────────────────────────────────────────────────────────────
+ * 목록과 건수가 **다른 빌더**로 만들어진다(빠른 갈래의 건수 probe). 두 자리에 배열을 따로 적으면
+ * 한쪽만 늘어나는 날 목록은 걸러지고 건수는 안 걸러진다 — 화면에 「한 건」과 「전체 수」가 나란히 선다.
+ *
+ * 지금은 그 일이 **일어날 수 없다**: 빠른 갈래는 검색어가 있으면 아예 안 탄다
+ * (`event-type-split-shape.ts` — 시험 「자유 검색어」가 그 축을 붙든다). 그래도 같은 상수를 쓴다 —
+ * 그 규칙이 언젠가 느슨해질 때 이 자리가 조용히 갈리지 않게.
+ */
+export const JOURNAL_SEARCHABLES = ['epc', 'orderId', 'locationId', 'moverId', 'bizStep', 'eventType', 'correlationId'] as const
+
 @Resolver()
 export class TwinJournalQuery {
   @Query(returns => [TwinEvent], {
@@ -191,6 +207,7 @@ export class TwinJournalQuery {
    *
    * 정렬 기본값은 revision DESC(최신순) — 저널의 자연 순서이자 ix_twin_event_0 가 그대로 타는 축.
    */
+
   @Query(returns => TwinEventList, {
     description:
       'List twin journal events with the standard list contract (filters, pagination, sortings) plus the total match count. ' +
@@ -286,7 +303,7 @@ export class TwinJournalQuery {
           repository: getRepository(TwinEvent),
           params: { ...effective, pagination: { page: 1, limit: COUNT_CAP + 1 } },
           domain,
-          searchables: [],
+          searchables: [...JOURNAL_SEARCHABLES],
           sortables: ['eventTime', 'revision', 'eventType', 'bizStep'],
           defaultLimit: COUNT_CAP + 1,
           maxLimit: COUNT_CAP + 1
@@ -314,7 +331,7 @@ export class TwinJournalQuery {
       params: effective,
       domain,
       /* 전부 인덱스 가능한 승격 컬럼 — 자유 검색어는 서버가 이 축들로 펼친다. */
-      searchables: ['epc', 'orderId', 'locationId', 'moverId', 'bizStep', 'eventType', 'correlationId'],
+      searchables: [...JOURNAL_SEARCHABLES],
       /* 정렬은 인덱스가 받쳐 주는 축으로만 — 큰 저널에서 임의 컬럼 정렬은 전체 정렬 스캔이다. */
       sortables: ['eventTime', 'revision', 'eventType', 'bizStep'],
       defaultLimit: 100,

package/test/attention-digest.test.ts

@@ -13,6 +13,7 @@
  */
 import { test } from 'node:test'
 import assert from 'node:assert/strict'
+import { readFile } from 'node:fs/promises'
 
 import { digestAttentions, compareAttentions, mergeLensAttentions } from '../server/engine/attention-digest.ts'
 
@@ -133,3 +134,28 @@ test('★ 렌즈가 하나도 없으면 빈 요약 — 공간에 배치된 트
   assert.equal(d.attentionTotal, 0)
   assert.deepEqual(d.severityByLocation, {})
 })
+
+/*
+ * ── 자를 수 있는 문만 자른다 (2026-09-19, 수석 아키텍트 판정) ────────────────
+ *
+ * 목록 문(`twinAttentions`)에 `limit` 이 있었다. 자르면서 **몇 건을 잘랐는지는 답에 실을 자리가
+ * 없었다** — 답이 맨 목록이라서다. 그러면 스무 건을 받은 화면은 그것이 전부인지 이백 중 스물인지
+ * 구별할 수 없고, 그 구별이 없으면 「괜찮아졌다」로 읽힌다(위 ②와 같은 자리).
+ *
+ * 그래서 자르는 일은 **자른 수를 말할 수 있는 문**에만 둔다. 이 검사는 그 규칙을 소스에서 센다 —
+ * 인자를 되돌려 놓으면 빨강이 된다.
+ */
+test('★ 목록 문은 자르지 않는다 — 자르는 인자는 전체 개수를 함께 내는 문에만 있다', async () => {
+  const source = await readFile(new URL('../server/service/twin-attention/twin-attention-query.ts', import.meta.url), 'utf-8')
+
+  const listAt = source.indexOf('async twinAttentions(')
+  const digestAt = source.indexOf('async twinAttentionDigest(')
+  assert.ok(listAt >= 0 && digestAt > listAt, '두 문을 못 찾았다 — 이 검사는 아무것도 지키지 않는다')
+
+  const list = source.slice(listAt, digestAt)
+  const digest = source.slice(digestAt)
+
+  assert.ok(!/@Arg\(\s*'limit'/.test(list), '목록 문에 자르는 인자가 있다 — 자른 수를 답에 실을 자리가 없다')
+  assert.ok(/@Arg\(\s*'limit'/.test(digest), '자르는 문이 없어졌다 — 화면이 상위 N 을 받을 길이 없다')
+  assert.ok(/digestAttentions\(/.test(digest), '자르는 문은 전체 개수를 함께 내는 함수를 지나야 한다')
+})

package/test/event-type-split.test.ts

@@ -153,3 +153,26 @@ test('빈 단계 값은 받지 않는다 — 모든 행을 뜻하는지 없는
   )
   assert.equal(shape, null)
 })
+
+
+/*
+ * ── 목록과 건수가 같은 축을 본다 (2026-09-19) ───────────────────────────────
+ *
+ * 빠른 갈래는 건수를 **다른 빌더**로 센다. 그 빌더가 검색 축을 빈 배열로 선언하고 있었다 — 목록은
+ * 걸러지고 건수는 안 걸러지는 모양이다(UX 레인이 검색 길을 세다 짚었다).
+ *
+ * **지금 그 일은 일어날 수 없다**: 검색어가 있으면 빠른 갈래를 아예 안 탄다(위 「자유 검색어」가 그
+ * 축을 붙든다). 그래서 이것은 산 결함이 아니라 **잠긴 함정**이고, 두 자리가 같은 상수를 보게 해서
+ * 닫는다 — 저 규칙이 언젠가 느슨해지면 그때 조용히 갈릴 자리다.
+ */
+test('★ 건수 probe 와 목록이 같은 검색 축을 쓴다 — 한쪽만 걸러지면 화면이 「한 건 / 전체 수」를 말한다', () => {
+  const uses = [...journal.matchAll(/searchables:\s*([^,\n]+)/g)].map(m => m[1].trim())
+
+  assert.ok(uses.length >= 2, '검색 축을 선언하는 자리가 둘이어야 한다(목록 · 건수 probe)')
+  assert.deepEqual(
+    [...new Set(uses)],
+    ['[...JOURNAL_SEARCHABLES]'],
+    '두 자리가 같은 상수를 봐야 한다 — 배열을 따로 적으면 한쪽만 늘어난다'
+  )
+  assert.doesNotMatch(journal, /searchables:\s*\[\]/, '빈 목록은 「검색어를 조용히 버린다」는 뜻이다')
+})

package/test/forecast-metrics.test.ts

@@ -25,6 +25,49 @@ test('물류 지표 — 기존 여섯은 그대로 센다', () => {
   assert.equal(FORECAST_METRICS.backlog(s), 1)
 })
 
+/*
+ * ── 받는 오더는 흐름 지표에서 빠진다 (2026-09-19, ADR-0076 보탬 ⑥) ──────────
+ *
+ * 입고 · 반품 입고는 도착이 세우고 도착이 이행한다. 세면 「나간 것」이 받을 때마다 늘고 백로그는
+ * 영영 안 줄어든다 — 그래프가 있지도 않은 일을 그린다.
+ */
+test('★ 입고 · 반품 입고는 세지 않는다 — 그 오더는 나가지 않는다', () => {
+  const s = {
+    orders: [
+      { kind: 'outbound', status: 'shipped' },
+      { kind: 'outbound', status: 'picking' },
+      { kind: 'inbound', status: 'received', requested: 10, fulfilled: 10 },
+      { kind: 'return', status: 'received', requested: 3, fulfilled: 3 }
+    ]
+  }
+  assert.equal(FORECAST_METRICS.orders(s), 2, '흐름 오더 둘만 센다')
+  assert.equal(FORECAST_METRICS.shipped(s), 1)
+  assert.equal(FORECAST_METRICS.backlog(s), 1, '받은 오더가 백로그에 남으면 곡선이 안 내려간다')
+})
+
+/*
+ * ── 백로그는 「종결인가」로 묻는다 ──────────────────────────────────────────
+ *
+ * 낱말 둘로 물을 때 원본이 `completed` 를 쓰는 미러에서 끝난 오더가 영영 백로그에 남았다. `status` 는
+ * 열린 축이고 실 시스템은 자기 낱말을 쓴다 — 이 셈은 낱말이 아니라 양을 1차 근거로 본다.
+ */
+test('★ 원본의 낱말로 끝난 오더도 백로그에서 빠진다', () => {
+  const s = {
+    orders: [
+      { kind: 'outbound', status: 'completed', requested: 5, fulfilled: 5 },
+      { kind: 'outbound', status: 'FINISHED', requested: 2, fulfilled: 2 },
+      { kind: 'outbound', status: 'picking', requested: 4, fulfilled: 1 }
+    ]
+  }
+  assert.equal(FORECAST_METRICS.backlog(s), 1, '아직 안 끝난 하나만 백로그다')
+})
+
+test('낱말을 말하지 않은 오더는 그대로 센다 — 지금까지의 거동이다', () => {
+  const s = { orders: [{ status: 'picking' }, { status: 'shipped' }] }
+  assert.equal(FORECAST_METRICS.orders(s), 2)
+  assert.equal(FORECAST_METRICS.shipped(s), 1)
+})
+
 test('에너지 지표 — 커널이 낸 값을 그대로 읽는다(다시 계산하지 않는다)', () => {
   const s = {
     energy: {

package/test/kpi-fold.test.ts

@@ -156,6 +156,34 @@ test('오더 완료: 양이 답한다 — 낱말이 진행 중이라 말해도',
   assert.equal(r.throughput.orders, 1, '10 중 10 은 끝났고 10 중 9 는 아니다')
 })
 
+/*
+ * ── 받는 오더는 처리량이 아니다 (2026-09-19, ADR-0076 보탬 ⑥) ────────────────
+ *
+ * 입고 · 반품 입고는 세우는 순간 `fulfilled >= requested` 다 — 받았다는 사실이 곧 그 오더의 완료이기
+ * 때문이다. 그대로 세면 도착마다 처리량이 한 건씩 부풀고, 그 수는 화면에서 「많이 해냈다」로 읽힌다.
+ */
+test('★ 입고 · 반품 입고는 처리량에서 빠진다 — 받은 것은 해낸 것이 아니다', () => {
+  const kinded = (orderId: string, kind: string, sec: number): KpiEvent => ({
+    eventType: 'order.status',
+    eventTime: at(sec),
+    payload: { data: { orderId, kind, status: 'received', requested: 10, fulfilled: 10 } }
+  })
+  const out = (orderId: string, sec: number): KpiEvent => ({
+    eventType: 'order.status',
+    eventTime: at(sec),
+    payload: { data: { orderId, kind: 'outbound', status: 'completed', requested: 5, fulfilled: 5 } }
+  })
+
+  const r = foldKpi([kinded('i1', 'inbound', 10), kinded('r1', 'return', 20), out('o1', 30)], WINDOW)
+
+  assert.equal(r.throughput.orders, 1, '나간 오더 하나만 센다')
+})
+
+test('낱말을 말하지 않은 오더는 그대로 센다 — 지금까지의 거동이다', () => {
+  const r = foldKpi([order('o1', 'completed', 10)], WINDOW)
+  assert.equal(r.throughput.orders, 1)
+})
+
 test('오더 완료: 같은 오더를 한 번만 센다 — 폴링 원본이 다시 보내도', () => {
   /*
    * 폴링하는 원본은 같은 오더의 종결을 여러 주기에 걸쳐 다시 보낼 수 있다(결함이 아니라 폴링의 성질).