import { ListParam } from '@things-factory/shell'; import { TwinEvent } from '../twin-event/twin-event.js'; import { TwinEventList } from '../twin-event/twin-event-type.js'; /** * 자유 검색어가 펼쳐지는 축 — **목록과 건수가 같은 것을 본다**(2026-09-19). * * 전부 인덱스 가능한 승격 컬럼이다(payload JSON 안이 아니라). 프레임워크 질의 빌더는 이 목록에 없는 * 컬럼의 LIKE 를 경고 후 무시한다 — 인덱스 없는 전체 스캔을 막기 위해서다. * * ── 왜 상수인가 ──────────────────────────────────────────────────────────── * 목록과 건수가 **다른 빌더**로 만들어진다(빠른 갈래의 건수 probe). 두 자리에 배열을 따로 적으면 * 한쪽만 늘어나는 날 목록은 걸러지고 건수는 안 걸러진다 — 화면에 「한 건」과 「전체 수」가 나란히 선다. * * 지금은 그 일이 **일어날 수 없다**: 빠른 갈래는 검색어가 있으면 아예 안 탄다 * (`event-type-split-shape.ts` — 시험 「자유 검색어」가 그 축을 붙든다). 그래도 같은 상수를 쓴다 — * 그 규칙이 언젠가 느슨해질 때 이 자리가 조용히 갈리지 않게. */ export declare const JOURNAL_SEARCHABLES: readonly ["epc", "orderId", "locationId", "moverId", "bizStep", "eventType", "correlationId"]; export declare class TwinJournalQuery { twinEvents(instanceId: string, fromRevision: number, toRevision: number, eventType: string, limit: number, context: ResolverContext, untilTime?: string, fromTime?: string): Promise; /** * 지난 기록 목록 — things-factory 표준 목록 계약(`ListParam` → `{ items, total }`). * * ── 왜 `twinEvents` 와 따로 두는가 ───────────────────────────────────────── * `twinEvents` 는 배열만 돌려준다. 화면은 자기가 받은 게 전부인지 잘린 건지 알 수 없었고, 그래서 * 리스트가 **알리지 않고 잘린 채 "이게 전부" 처럼** 보였다(원장 limit 120 이 대표적). 총건수를 함께 * 주면 "48 / 12,904" 라고 말할 수 있고, 사용자는 좁혀야 한다는 사실을 안다. * 기존 호출자를 깨지 않으려고 `twinEvents` 는 그대로 두고 목록 계약을 새로 연다. * * ── 검색이 진짜인 이유 ───────────────────────────────────────────────────── * `searchables` 는 전부 **인덱스 가능한 승격 컬럼**이다(payload JSON 안이 아니라). 프레임워크 * 질의 빌더는 `searchables` 에 없는 컬럼의 LIKE 를 경고 후 무시한다 — 인덱스 없는 전체 스캔을 * 막기 위해서다. 그 규율에 맞추려고 검색 축을 컬럼으로 승격했다(`twin-event-keys.ts`). * * 정렬 기본값은 revision DESC(최신순) — 저널의 자연 순서이자 ix_twin_event_0 가 그대로 타는 축. */ twinEventList(params: ListParam, context: ResolverContext, instanceId?: string, spaceId?: string): Promise; /** * 업무 KPI — 시간창 처리량·소요시간·자원 점유. 저널을 **계산해서** 만든다(새 계측을 주입하지 않는다). * * `twinMetrics`(초당 이벤트 수 = 인프라 부하)와 **다른 것**이다: 이건 "지난 한 시간에 몇 건 처리했고 * 한 건에 얼마나 걸렸나" 다. 이름이 비슷해 헷갈리기 쉬우므로 설명에 명시한다. * * 완료된 작업의 **시작 이벤트가 창 앞에 있을 수 있어** 조회 구간을 창보다 앞으로 넓힌다(lookback). * 그래도 못 찾은 것은 결과의 `unpaired` 로 드러난다 — 평균에서 오류 없이 빠지면 지표가 거짓이 된다. */ twinKpi(context: ResolverContext, spaceId?: string, instanceId?: string, /** 창 시작·끝(ISO). 미지정이면 최근 1시간. */ fromTime?: string, toTime?: string, /** 창 길이(분). fromTime 이 있으면 무시. 기본 60. */ windowMinutes?: number, /** 추세를 위해 창을 N 등분(1~48). 미지정이면 쪼개지 않는다. */ buckets?: number, /** 시작 이벤트를 찾기 위해 창보다 앞으로 더 읽는 시간(분). 기본 60. */ lookbackMinutes?: number, /** 관점 축 — 같은 창을 자원별·작업종류별·도착지점별·오더별·구역별로 쪼갠다. */ groupBy?: string, /** 축의 상한(기본 20, 최대 100). 넘치면 잘라내고 잘린 수를 알린다. */ groupLimit?: number, /** 비교 기준 — 같은 길이의 앞 구간(previous)이나 하루 전 같은 시간(yesterday). */ compareTo?: string, /** 여러 구간 동시 비교 — 최근 N 구간의 같은 시간대 분포(1~14). */ baselinePeriods?: number, /** 분포의 간격 — day(같은 시간대) | week(같은 요일·시간대). 기본 day. */ baselineStride?: string): Promise; twinReplay(instanceId: string, untilRevision: number, untilTime: string, context: ResolverContext, axes?: string[], attentionLimit?: number): Promise; twinCapacity(instanceId: string, spaceId: string, /** 하루 몇 대를 낼 것인가 — 화면이 보고 있는 목표에서 나온다(선언된 수요). */ unitsPerDay: number, /** * 가용 시간을 잴 기준 주의 시작(ISO, 월요일). 공휴일이 없는 평상주여야 한다 — * 공휴일은 연간 가용량을 따로 깎지, 이 공장의 평상시 상한을 정하지 않는다. */ sampleWeekStart: string, context: ResolverContext): Promise; twinOperationsCapability(instanceId: string, spaceId: string, unitsPerDay: number, /** 능력을 물을 구간 — **구간 없이 능력은 존재하지 않는다**(표준 StartTime/EndTime). */ fromTime: string, toTime: string, sampleWeekStart: string, context: ResolverContext): Promise; twinStructures(instanceId: string, context: ResolverContext): Promise; twinTimeRange(spaceId: string, context: ResolverContext): Promise<{ minTime: string | null; maxTime: string | null; }>; }