@things-factory/headless-twin 10.1.278 → 10.1.280

package/server/service/twin-subject/subject-query-shape.ts

@@ -1,84 +0,0 @@
-import type { SubjectKind } from './event-subjects.js'
-
-/*
- * **이 물음을 파생 테이블로 답할 수 있나** — 순수 판단만 여기 둔다.
- *
- * 데이터베이스도 커널도 부르지 않는다. 그래서 시험이 이 파일을 그대로 부를 수 있다(데코레이터가 없다).
- * 판단이 조회 코드 안에 섞여 있으면 그 판단만 확인할 방법이 없고, 그러면 「어떤 물음이 빠른 경로로
- * 가는가」가 아무도 읽지 못하는 규칙이 된다.
- *
- * 좁게 잡는다. 파생 테이블은 「대상 하나를 시각순으로」에 맞춰 생겼고, 그 모양이 아닌 물음에 억지로
- * 답하면 목록이 알리지 않고 달라진다. 맞지 않으면 `null` 이고, 부르는 쪽은 저널로 간다.
- */
-
-/** 화면이 저널에 묻던 축 → 파생 테이블의 대상 종류. */
-export const AXIS_KIND: Record<string, SubjectKind> = {
-  epc: 'item',
-  orderId: 'order',
-  locationId: 'location',
-  moverId: 'equipment' // vocabulary-guard: allow — 저널의 승격 컬럼 이름(저장된 계약)
-}
-
-/** 이 경로가 다룰 수 있는 필터 이름 — 이 밖의 필터가 하나라도 있으면 저널로 보낸다. */
-const ALLOWED_FILTERS = new Set(Object.keys(AXIS_KIND).concat('eventTime'))
-
-export interface SubjectQueryShape {
-  kind: SubjectKind
-  /** 화면이 건넨 축 값 — 짧게 줄어 있을 수 있다(되돌리는 일은 조회하는 쪽이 한다). */
-  value: string
-  untilTime?: Date
-  fromTime?: Date
-}
-
-/**
- * 목록 계약의 조건을 읽어 「대상 하나의 시각순 이력」인지 가린다 — 아니면 `null`.
- *
- * 받는 모양
- *   축 하나(품목·오더·자리·설비)를 `eq` 또는 `search` 로 · 시각 상한이나 구간 · 시각 내림차순 정렬
- *
- * 보내는 모양(저널로)
- *   자유 검색어 · 종류 필터 · 상관 식별자 · 축 둘 이상 · 그 밖의 정렬이나 연산자
- */
-export function readModelShape(params: any, sortings: any[]): SubjectQueryShape | null {
-  const filters: any[] = Array.isArray(params?.filters) ? params.filters : []
-  if (typeof params?.search === 'string' && params.search.trim()) return null
-  for (const f of filters) if (!ALLOWED_FILTERS.has(f?.name)) return null
-
-  /* 정렬은 시각 내림차순 하나일 때만 — 파생 테이블의 목차가 그 축이다. */
-  if (sortings.length !== 1 || sortings[0]?.name !== 'eventTime' || sortings[0]?.desc !== true) return null
-
-  const axisFilters = filters.filter(f => f.name !== 'eventTime')
-  if (axisFilters.length !== 1) return null
-  const axis = axisFilters[0]
-  const kind = AXIS_KIND[axis.name]
-  if (!kind) return null
-  /* 축은 값 하나여야 한다 — 여러 값(`in`)이면 목차를 한 번에 타지 못한다. */
-  if (axis.operator !== 'eq' && axis.operator !== 'search') return null
-  const value = typeof axis.value === 'string' ? axis.value.trim() : ''
-  if (!value) return null
-
-  /* 시각은 상한·구간만 받는다(시간여행). 그 밖의 연산자는 뜻이 달라지므로 저널로 보낸다. */
-  let untilTime: Date | undefined
-  let fromTime: Date | undefined
-  for (const f of filters) {
-    if (f.name !== 'eventTime') continue
-    if (f.operator === 'lte' || f.operator === 'lt') {
-      untilTime = toDate(f.value)
-      if (!untilTime) return null
-    } else if (f.operator === 'between' && Array.isArray(f.value)) {
-      fromTime = toDate(f.value[0])
-      untilTime = toDate(f.value[1])
-      if (!fromTime || !untilTime) return null
-    } else return null
-  }
-
-  return { kind, value, untilTime, fromTime }
-}
-
-/** 값을 날짜로 — 못 읽으면 `undefined`(지어내지 않는다). */
-export function toDate(v: unknown): Date | undefined {
-  if (v instanceof Date) return Number.isNaN(v.getTime()) ? undefined : v
-  if (typeof v !== 'string' && typeof v !== 'number') return undefined
-  const d = new Date(v as any)
-  return Number.isNaN(d.getTime()) ? undefined : d
-}

package/server/service/twin-subject/twin-subject-backfill.ts

@@ -1,196 +0,0 @@
-import { getRepository } from '@things-factory/shell'
-
-import { twinLog, twinWarn } from '../../engine/log.js'
-import { TwinEvent } from '../twin-event/twin-event.js'
-import { TwinInstance } from '../twin-instance/twin-instance.js'
-import { TwinSubjectEvent } from './twin-subject-event.js'
-import { writeSubjectRows } from './twin-subject-writer.js'
-import { itemResolverFor } from './item-resolver.js'
-
-/*
- * **이미 저장된 사건을 이 표로 옮긴다** — 요청받은 트윈만.
- *
- * ── 왜 기본이 아닌가 ────────────────────────────────────────────────────────
- * 이 표의 규칙은 「앞으로만 채운다」다. 그래야 새 조회 축이 필요할 때마다 3,128만 줄을 다시 만드는
- * 구조가 되지 않는다(설계: read-models.md §4).
- *
- * 그런데 이미 쌓인 트윈에서 이력을 보려면 그 구간이 있어야 한다. 그래서 **부르면 채우는 도구**로 둔다 —
- * 마이그레이션이 아니고, 부팅에 자동으로 돌지도 않는다. 트윈을 지정해 부른다.
- *
- * ── 어디까지 옮겼는지 적어 둔다 (2026-08-27 · 세 번 틀린 뒤) ─────────────────
- * 저장하지 않고 표의 내용으로 진행 지점을 알아내려 했고 세 번 틀렸다.
- *
- *   ① 표의 최대 리비전 뒤부터    앞으로 채워진 줄의 최댓값이 곧 저널의 끝이라 소급을 다 건너뛴다
- *   ② 표의 최소 리비전 앞까지    소급이 1부터 적으면 최솟값이 1이 되어 구간이 0으로 접힌다
- *   ③ 표의 최소 시각 아래로      사건이 시각순으로 오지 않는 트윈에서 곧바로 끝난다
- *
- * ③이 결정적이었다. 승화푸드 커넥터는 과거 기록을 되읽으므로 방금 들어온 사건의 시각이 2024년 10월이다.
- * 그래서 표의 가장 오래된 시각이 이미 저널의 시작과 같아진다.
- *
- * 원인은 하나다. **채워진 것은 구간이 아니라 집합이다.** 리비전으로 보든 시각으로 보든 「어디까지」를
- * 하나의 경계로 말할 수 없다. 그래서 알아내려 하지 않고 **이 프로세스가 든다**(§`inFlight`).
- *
- * 리비전 1부터 순서대로 올라간다. 목표는 **채우기를 시작한 순간의 저널 끝**이다 — 그보다 뒤는 앞으로
- * 채우는 쪽이 이미 적고 있다.
- *
- * ── 규율 ────────────────────────────────────────────────────────────────────
- * **나눠서 옮긴다.** 한 번에 통째로 읽으면 그동안 호스트가 아무 일도 못 한다(sqlite 는 쓰기가 하나다).
- * 배치 사이에 루프를 비워 준다.
- *
- * **같은 시각의 줄을 반쪽만 적지 않는다.** 한 배치의 가장 오래된 시각에 걸친 줄들은 다음 배치로 넘긴다 —
- * 반쪽만 적으면 그 시각이 「채워진 것」으로 보이면서 일부가 빠진다.
- *
- * **몇 줄을 옮겼고 어디까지 왔는지 말한다.** 알리지 않고 절반만 채우면 화면이 「그 앞에는 사건이 없다」고
- * 말하게 된다.
- */
-
-/** 한 번에 읽는 저널 행 수 — 저널 정리와 같은 규율. */
-const READ_BATCH = 5_000
-
-export interface BackfillResult {
-  instanceId: string
-  /** 읽은 저널 행 수. */
-  read: number
-  /** 이 표에 적은 줄 수. */
-  written: number
-  /** 여기까지 옮겼다(저널 리비전). */
-  upToRevision: number
-  /** 목표 — 채우기를 시작한 순간의 저널 끝. */
-  targetRevision: number
-  /** 다 옮겼나. */
-  complete: boolean
-  /** 예산을 다 써서 멈췄나. */
-  paused: boolean
-}
-
-/**
- * 옮기는 중인 트윈의 목표와 지점 — **이 프로세스 안에서만** 든다.
- *
- * 테이블에 적지 않는다(사용자 판단, 2026-08-27). 서버가 내려가면 사라지고, 다음에 부르면 처음부터
- * 다시 읽는다. 그 대가를 아는 채로 두는 것이다.
- */
-const inFlight = new Map<string, { upToRevision: number; targetRevision: number }>()
-
-/**
- * 한 트윈의 저장된 사건을 이 표로 옮긴다 — 예산 안에서.
- *
- * 되풀어 부르면 이어서 한다. 넘길 인자가 없다 — 진행 지점을 적어 두기 때문이다.
- */
-export async function backfillSubjects(
-  domainId: string,
-  instanceId: string,
-  opts: { budgetMs?: number } = {}
-): Promise<BackfillResult> {
-  const budgetMs = opts.budgetMs ?? 30_000
-  const startedMs = Date.now()
-
-  const reg = await getRepository(TwinInstance)
-    .findOne({ where: { domain: { id: domainId }, instanceId } })
-    .catch(() => null)
-  if (!reg?.model) {
-    throw new Error(`twin "${instanceId}" is not registered — no model to resolve declared items with`)
-  }
-  const itemOf = itemResolverFor(domainId, instanceId, reg.model)
-  if (!itemOf) {
-    twinWarn(
-      `[twin-subject] "${instanceId}" 선언된 품목이 없어 품목 줄은 만들지 않는다 — 개체·자리·설비 줄만 옮긴다.`
-    )
-  }
-
-  /*
-   * ── 진행 지점을 **회차 안에서만** 든다 (2026-08-27 · 사용자 판단) ────────────────
-   *
-   * 처음에는 테이블에 적었다. 사용자 판단으로 없앴다 — 사건이 들어올 때 파생 테이블도 같이 적히므로,
-   * 옛 사건을 옮기는 일은 새 파생 테이블을 만들 때와 계산 규칙을 고쳐 다시 만들 때뿐이다. 그 두 경우가
-   * 흔하지 않다.
-   *
-   * 대가는 이것이다. 옮기는 중에 서버가 내려가면 그 몫을 다시 읽는다. 335만 건이면 20분쯤이다.
-   *
-   * 그래서 **목표와 지점을 이 프로세스가 든다.** 트윈마다 한 줄이고, 서버가 내려가면 사라진다.
-   */
-  const events = getRepository(TwinEvent)
-  const key = `${domainId}:${instanceId}`
-  let held = inFlight.get(key)
-  if (!held) {
-    /*
-     * 목표는 **처음 부를 때의 저널 끝**이다. 매번 다시 재면 그 사이에 새 사건이 들어와 끝나지 않는다.
-     * 그 뒤의 사건은 저널을 쓸 때 파생 테이블에도 같이 적히므로 이 작업의 몫이 아니다.
-     */
-    const tip = await events
-      .createQueryBuilder('e')
-      .select('MAX(e.revision)', 'max')
-      .where('e.domain = :domainId', { domainId })
-      .andWhere('e.instanceId = :instanceId', { instanceId })
-      .getRawOne<{ max: unknown }>()
-    held = { upToRevision: 0, targetRevision: Number(tip?.max ?? 0) }
-    inFlight.set(key, held)
-  }
-
-  let read = 0
-  let written = 0
-  let paused = false
-  let cursor = held.upToRevision
-  const target = held.targetRevision
-
-  for (;;) {
-    if (cursor >= target) break
-    if (Date.now() - startedMs >= budgetMs) {
-      paused = true
-      break
-    }
-    const rows = await events
-      .createQueryBuilder('e')
-      .where('e.domain = :domainId', { domainId })
-      .andWhere('e.instanceId = :instanceId', { instanceId })
-      .andWhere('e.revision > :cursor', { cursor })
-      .andWhere('e.revision <= :target', { target })
-      .orderBy('e.revision', 'ASC')
-      .take(READ_BATCH)
-      .getMany()
-    if (!rows.length) {
-      cursor = target
-      break
-    }
-
-    read += rows.length
-    written += await writeRows(domainId, instanceId, rows, itemOf)
-    cursor = Number(rows[rows.length - 1].revision)
-    /* 진행 지점을 그때그때 든다 — 중간에 멈춰도 다음 호출이 여기서 잇는다(같은 프로세스 안에서). */
-    held.upToRevision = cursor
-    /* 배치 사이에 루프를 비워 준다 — 이 한 줄이 없으면 나눈 뜻이 없다. */
-    await new Promise(resolve => setImmediate(resolve))
-  }
-
-  held.upToRevision = cursor
-  const complete = cursor >= target
-  /* 다 옮겼으면 들고 있을 이유가 없다 — 다시 부르면 목표를 새로 잡는다(그때는 옮길 것이 없다). */
-  if (complete) inFlight.delete(key)
-  twinLog(
-    `[twin-subject] backfill "${instanceId}" — 저널 ${read}행을 읽어 ${written}줄 적었다 · ` +
-      `리비전 ${cursor}/${target}` +
-      `${complete ? ' · 다 옮겼다' : paused ? ' · 예산을 다 써서 멈췄다 — 다시 부르면 이어서 한다' : ''}`
-  )
-
-  return { instanceId, read, written, upToRevision: cursor, targetRevision: target, complete, paused }
-}
-
-/** 저널 행들을 봉투로 되돌려 적는다 — `payload` 가 봉투 전체다. */
-async function writeRows(domainId: string, instanceId: string, rows: TwinEvent[], itemOf?: any): Promise<number> {
-  return await writeSubjectRows(
-    domainId,
-    instanceId,
-    rows.map(r => ({
-      /*
-       * `payload` 가 봉투 전체다(`{ eventId, eventType, eventTime, tenantId, data: {…} }`). 한 겹 더
-       * 감싸면 키가 묻혀 아무것도 찾지 못한다 — 실측으로 825,000행을 읽어 0줄을 적었다.
-       *
-       * 시각과 종류는 승격 컬럼을 믿는다. payload 안의 값과 컬럼이 어긋난 옛 행이 있을 수 있고,
-       * 이 표의 정렬 축은 컬럼이 정본이다.
-       */
-      envelope: { ...((r as any).payload ?? {}), eventType: r.eventType, eventTime: r.eventTime },
-      revision: Number(r.revision),
-      eventId: r.id
-    })),
-    itemOf
-  )
-}

package/server/service/twin-subject/twin-subject-event.ts

@@ -1,101 +0,0 @@
-import { Field, Int, ObjectType } from 'type-graphql'
-import { Column, CreateDateColumn, Entity, Index, ManyToOne, PrimaryGeneratedColumn, RelationId } from 'typeorm'
-import { Domain } from '@things-factory/shell'
-
-/*
- * **대상별 사건 목록** — 조회용 파생 표. 사실의 원본은 `twin_events` 다.
- *
- * ── 왜 만드나 (2026-08-27 실측) ─────────────────────────────────────────────
- * 360 화면이 「이 대상의 이력」을 묻고, 그 조회가 64초다. 원인은 「무엇으로 걸러 시각순으로 정렬해
- * 앞에서 30개」라는 모양에 맞는 목차가 없다는 것이다. 그리고 목차를 얹는 방식으로는 풀리지 않는다.
- *
- *   정렬이 목차를 무력화한다      여러 값으로 거르면(IN) 합칠 때 다시 정렬해야 한다
- *   축이 늘 때마다 목차가 늘어난다  360 의 축 넷을 다 빠르게 하면 `twin_events` 목차가 13개가 된다
- *   소급 채우기가 매번 든다       목차 하나 만드는 데 3분 36초 · 파일 +2.4GB
- *   품목 축은 그래도 안 풀린다     저장된 식별자에 품목과 로트가 한 문자열로 붙어 있다
- *
- * ── 이 표가 무엇을 담나 ─────────────────────────────────────────────────────
- * 사건 하나가 가리키는 **대상마다 한 줄**이다. 품목 이동 사건이면 품목·로트·자리로 세 줄이다.
- * 종류(`subjectKind`)를 값으로 밝히므로 읽는 쪽이 사건 종류표를 들고 있지 않아도 된다. 뜻이
- * 달라지는 키 칸을 쓰지 않는 이유이고, 그 방식이 틀렸다는 뜻은 아니다 — 정의가 함께 있는
- * 프레임워크에서는 합리적이다. 이 표는 볼 정의가 없다.
- *
- * ── 규칙 넷 (설계: read-models.md §4) ───────────────────────────────────────
- *   ① 조회는 이 표가 답한다. `twin_events` 에 목차를 얹어 답하지 않는다
- *   ② **앞으로만 채운다.** 소급하지 않는다 — 새 키가 필요할 때 3,128만 줄을 다시 만들지 않는다
- *   ③ 준비되지 않은 구간을 화면이 말한다. 비어 있는 것을 「없다」로 그리지 않는다
- *   ④ 언제든 버릴 수 있다. 사건에서 파생된 값이므로 지워도 사실이 사라지지 않는다
- *
- * ── 왜 사건 본문을 베끼지 않나 ──────────────────────────────────────────────
- * `eventId` 로 원본을 가리키고, 목록을 그리는 데 필요한 값만 함께 둔다(종류·시각·리비전). 본문까지
- * 베끼면 이 표가 원본만큼 커지고, 원본을 고칠 때 두 곳이 어긋난다.
- */
-@Entity()
-/*
- * 이 표의 유일한 목차 — 이 순서가 곧 이 표의 존재 이유다.
- *
- * 「이 트윈의 이 대상의 것을 최신순으로 30개」가 목차를 위에서 30줄 읽고 끝난다. 정렬이 없다 —
- * 거르는 값이 하나이고 그 다음이 시각이기 때문이다.
- */
-@Index(
-  'ix_twin_subject_event_0',
-  (e: TwinSubjectEvent) => [e.domain, e.instanceId, e.subjectKind, e.subjectId, e.eventTime],
-  { unique: false }
-)
-/* 보관 상한을 지우는 축 — 「이 트윈에서 오래된 줄」을 찾는다(§`twin-subject-writer` 의 정리). */
-@Index('ix_twin_subject_event_1', (e: TwinSubjectEvent) => [e.domain, e.instanceId, e.eventTime], {
-  unique: false
-})
-@ObjectType({ description: 'One row per subject an event refers to — the read model behind entity history.' })
-export class TwinSubjectEvent {
-  @PrimaryGeneratedColumn('uuid')
-  @Field(type => String, { description: 'Row id.' })
-  readonly id: string
-
-  @ManyToOne(type => Domain)
-  domain: Domain
-
-  @RelationId((e: TwinSubjectEvent) => e.domain)
-  domainId?: string
-
-  @Column()
-  @Field({ description: 'The twin instance this row belongs to.' })
-  instanceId: string
-
-  @Column()
-  @Field({
-    description:
-      'What kind of thing this row points at: item, lot, order, location, equipment or task. The kind is stored as a value so a reader never has to know which event types put what where.'
-  })
-  subjectKind: string
-
-  @Column()
-  @Field({ description: 'Identifier of that thing, within its kind.' })
-  subjectId: string
-
-  /*
-   * **타입 이름을 적지 않는다** — `twin-event.ts` 의 `eventTime` 과 같은 이유다.
-   *
-   * `datetime` 은 sqlite·MySQL 의 이름이고 Postgres 는 `timestamp` 만 안다. 다섯 드라이버에 다
-   * 통하는 이름이 없어서, 이름을 고르는 일을 TypeORM 에 맡긴다(TS 타입 `Date` 에서 고른다).
-   */
-  @Column()
-  @Field({ description: 'When the event happened, by the twin clock. This is the axis the history list is ordered by.' })
-  eventTime: Date
-
-  @Column({ type: 'int' })
-  @Field(type => Int, { description: 'Journal revision of the event — ties this row to its place in the record.' })
-  revision: number
-
-  @Column()
-  @Field({ description: 'Event type, so the list can be drawn without reading the journal row.' })
-  eventType: string
-
-  @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Journal row this points at. Null when the journal row has been pruned.' })
-  eventId?: string
-
-  @CreateDateColumn()
-  @Field({ description: 'When this row was written.' })
-  createdAt?: Date
-}