@things-factory/headless-twin 10.0.8 → 10.0.10

package/dist-server/service/reference/reference-master.d.ts

@@ -1,10 +1,18 @@
-import type { EquipmentLevel, WorkCalendarEntry } from '@operato/twin-kernel';
+import type { DomainSystem, EquipmentLevel, WorkCalendarEntry } from '@operato/twin-kernel';
 export interface RefLocation {
     id: string;
     type: string;
     name?: string;
+    description?: string;
     role: 'location' | 'area' | 'both';
     parentId?: string;
+    /**
+     * **전기적으로 어디서 받는가** — 이 자리에 전기를 주는 상류 자리(커널 계약의 `upstreamId`).
+     *
+     * `parentId`(공간 포함)와 따로 두는 이유는 커널 계약에 적혀 있다. 여기서 빠뜨리면 마스터가 말한 계통이
+     * 모델까지 오지 못하고, 뿌리 계량 판정이 분기 계량기까지 뿌리로 세어 **부하가 두 배로** 보인다.
+     */
+    upstreamId?: string;
     /** 저장 용량 — 이 자리에 동시에 놓일 수 있는 물품 수. */
     capacity?: number;
     /**
@@ -20,6 +28,14 @@ export interface RefLocation {
      * 짐작해 채우지 않는다.
      */
     level?: EquipmentLevel;
+    /**
+     * 자리의 **열린 속성** — 표준 `OperationalLocationProperty`(설비·사람·자산과 같은 모양).
+     *
+     * 무엇이 여기 실리나: **자리의 물리량**이다. 에너지의 계약전력(`contract.kW`)이 첫 사례다 —
+     * 그 값이 앉을 자리가 없어서 EMS 커널은 계약 대비 판정을 할 수 없었다(자리가 없으면 사실이
+     * 들어오지 못한다). 커널은 자기가 **읽는** 속성 id 만 선언하고(`EMS_PROPERTY`) 나머지는 나른다.
+     */
+    properties?: RefResourceProperty[];
     footprint?: {
         x: number;
         y: number;
@@ -76,9 +92,40 @@ export interface RefResourceClass {
     effectiveStart?: string;
     effectiveEnd?: string;
 }
+/**
+ * 검사 명세 — **자원이 가리키는 대상**(ISA-95 `TestSpecification`).
+ *
+ * 표준 필드는 셋만 담는다(`ID`·`Description`·`Version`) — 재는 속성과 합격 기준은 아직 1차 출처와
+ * 대조하지 않았다(커널 계약의 머리말이 그 사실을 적어 두었다).
+ */
+/**
+ * 시험 결과 — **"이 개체가 그 시험을 통과했다"** 는 기록(ISA-95 결과).
+ *
+ * 결과를 낳는 곳은 트윈이 아니다(인사·정비 시스템이 기록한다) — 그래서 관측이면서 **선언 경로로** 온다.
+ * 커널은 이 값이 있을 때만 자격을 판정한다: 없으면 제약이 아니고(라인이 굶지 않는다), 있으면 만료·
+ * 불합격이 배정을 막는다.
+ */
+export interface RefTestResult {
+    specId: string;
+    result: 'pass' | 'fail';
+    at?: string;
+    /** 없으면 무기한 — 짐작으로 기한을 만들면 멀쩡한 자격자가 조용히 사라진다. */
+    expiresAt?: string;
+}
+export interface RefTestSpecification {
+    id: string;
+    /** 표시명 — i18n 키일 수 있다. 읽는 어휘를 하나로 맞추려고 인제스트가 `name` 으로 옮긴다. */
+    description?: string;
+    version?: string;
+}
 export interface RefEquipment {
     id: string;
     kind: string;
+    /** 사람이 부르는 이름 — 없으면 화면이 id 를 보인다(id 를 이름으로 베끼지 않는다). */
+    name?: string;
+    /** 시험 결과 — 자격이 성립하는지는 이것이 말한다(§RefTestResult). */
+    testResults?: RefTestResult[];
+    description?: string;
     homeLocationId: string;
     mtbfMs?: number;
     mttrMs?: number;
@@ -155,7 +202,7 @@ export interface RefOperationVariability {
 /**
  * 오퍼레이션 명세 — ISA-95 `OperationsSegment`. 커널 `OperationDef` 와 필드 이름이 1:1이다.
  *
- * **이것이 없으면 시뮬레이션의 시간은 우리가 코드에 박아 둔 상수다.** 원 시스템(또는 가상 레퍼런스)이
+ * **이것이 없으면 시뮬레이션의 시간은 우리가 코드에 고정한 상수다.** 원 시스템(또는 가상 레퍼런스)이
  * 공정별 소요·변동·수율을 말해 줘야 예측이 그 현장의 예측이 된다. 주지 않으면 커널 기본값으로
  * 굴러가고, **기본값을 썼다는 사실은 커널 `specCoverage()` 가 밝힌다**(조용히 넘어가지 않는다).
  */
@@ -198,6 +245,8 @@ export interface RefOperation {
 export interface RefPerson {
     id: string;
     name?: string;
+    /** 시험 결과 — 자격이 성립하는지는 이것이 말한다(§RefTestResult). */
+    testResults?: RefTestResult[];
     /**
      * 속한 등급들 — **표준 `Person.PersonnelClassID`, `maxOccurs="unbounded"`**.
      * 복수인 것이 표준이고 그것이 자격 표현이다: 한 사람이 용접 자격과 지게차 자격을 함께 갖는다.
@@ -237,6 +286,8 @@ export interface RefPerson {
 export interface RefAsset {
     id: string;
     name?: string;
+    /** 시험 결과 — 자격이 성립하는지는 이것이 말한다(§RefTestResult). */
+    testResults?: RefTestResult[];
     /**
      * 속한 등급들 — 표준 `PhysicalAssetClassID`(복수). 팔레트가 'euro-pallet' 이면서 'food-grade' 일 수 있다.
      * 공정의 요구는 등급 하나 + 수량이다(표준 `PhysicalAssetSpecification`).
@@ -275,10 +326,61 @@ export interface RefMaterialDefinition {
     effectiveStart?: string;
     effectiveEnd?: string;
 }
+/**
+ * **이 마스터를 다시 만들 수 있는 방법** — 트윈이 자기 원본을 기억하는 자리.
+ *
+ * 트윈은 원본을 비출 뿐이므로(ADR-0028), 원본이 달라지면 **다시 읽어야** 합니다. 그런데 지금까지
+ * 트윈은 "내가 무엇에서 나왔나" 를 남기지 않았다 — 어댑터로 들어온 트윈은 `TwinReference` 행이
+ * 있었지만 템플릿으로 세운 트윈에는 아무것도 없었고, 그래서 **다시 읽을 대상이 없는 트윈**이
+ * 만들어졌다. 원본을 잃은 트윈은 첫날의 모습에 영원히 머문다.
+ *
+ * 그래서 원천이 무엇이든 여기 한 자리에 남긴다. 다시 읽기는 이 값 하나만 보면 된다.
+ */
+export type MasterOrigin = 
+/**
+ * 등록된 레퍼런스(어댑터)에서 왔다 — 다시 읽기 = 그 어댑터로 마스터를 다시 가져온다.
+ *
+ * `source` 는 **레퍼런스 등록 이름**이고 그 참조가 보고하는 사이트 전부에 같다. 그래서 어느 사이트에서
+ * 온 트윈인지는 `siteId` 가 있어야 안다 — 없으면 다시 읽기가 사이트를 찾지 못한다(2026-08-18 실측:
+ * 사이트가 여러 개인 참조에서 온 트윈은 재동기가 전부 거절됐다. 참조 이름을 사이트별 마스터의
+ * `source`(=인스턴스 id)와 견주고 있었다 — 서로 다른 것을 비교한 것이다).
+ */
+{
+    kind: 'reference';
+    source: string;
+    siteId?: string;
+    spaceId?: string;
+}
+/**
+ * 템플릿 + 노브로 합성했다 — 다시 읽기 = 같은 노브로 다시 짓는다(합성은 결정적이다).
+ *
+ * `spaceId` 는 **만들 때 고른 현장**이다(합쳐 넣기). 기억하지 않으면 다시 읽을 때 트윈이 조용히 자기
+ * 현장을 떠난다 — 템플릿이 낸 기본 공간으로 돌아가기 때문이다. 그러면 그 현장의 값(요금 등)도 함께
+ * 잃는다(2026-08-18 실측: 한 현장에 합쳐 둔 EMS 트윈 여덟이 재동기 뒤 각자 공간으로 흩어졌다).
+ */
+ | {
+    kind: 'template';
+    templateId: string;
+    params: Record<string, unknown>;
+    spaceId?: string;
+};
 export interface ReferenceMaster {
     source: string;
-    system: 'wms' | 'yms' | 'mes';
+    /**
+     * 어느 종류의 트윈인가 — **커널 카탈로그가 정본**이다(`DomainSystem`).
+     *
+     * 예전에는 `'wms' | 'yms' | 'mes'` 를 여기 적어 뒀다. 커널에 종류가 하나 늘 때(에너지) 이 줄이
+     * 함께 움직여야 하는데, 손으로 적힌 목록은 그것을 알려 주지 않는다 — 어휘의 집은 한 곳이어야 한다.
+     */
+    system: DomainSystem;
     siteName: string;
+    /** 검사 명세 — 자원·등급의 `testSpecificationIds` 가 가리키는 대상. */
+    testSpecifications?: RefTestSpecification[];
+    /**
+     * 이 마스터가 어디서 나왔나 — **다시 읽기의 유일한 근거.** 없으면 그 트윈은 다시 읽을 수 없고,
+     * 조회 화면이 그 사실을 그대로 말한다(없는 것을 있는 척하지 않는다).
+     */
+    origin?: MasterOrigin;
     /**
      * 현장(공간). **시각 기준(`timezone`)이 여기 있는 이유**: 한 테넌트가 Rosarito(태평양)와 한국
      * 공장을 함께 가질 수 있다. 테넌트 단위(`Domain.timezone`)로 두면 **둘 중 하나는 반드시 틀린다.**
@@ -308,12 +410,19 @@ export interface ReferenceMaster {
     /**
      * **생산 정의**(레시피·라우트·자재 바인딩) — 커널의 정의-구동 MES 모드 입구.
      *
-     * 없으면 커널은 레거시(하드코딩) 흐름으로 돈다. 즉 **현장 레시피를 적어도 이 자리에 실리지 않으면
-     * 커널은 그것을 보지 못한다** — 선언과 실행이 갈라지는 지점이라 자리를 연다.
+     * 없으면 커널은 레거시(하드코딩) 흐름으로 동작한다. 즉 **현장 레시피를 적어도 이 자리에 실리지 않으면
+     * 커널은 그것을 보지 못한다** — 선언과 실행이 어긋나는 지점이라 자리를 연다.
+     */
+    /**
+     * 생산 선언 — `TwinModelDef.productionSpec` 으로 통과한다(ISA-95 OperationsSegment + BOM).
+     *
+     * 예전 이름은 `mesSpec` 이었다. 담긴 것은 MES 만의 것이 아니라 "자재를 소비해 자재를 산출하는
+     * 공정" 이고, 이름이 MES 였기 때문에 창고 트윈은 이 자리를 쓸 생각조차 하지 못했다(유통가공 창고가
+     * BOM 을 설명 문서에만 적어 둔 채 키트를 못 만드는 트윈을 만든 원인). 근거는 커널 계약 주석에.
      */
-    mesSpec?: unknown;
+    productionSpec?: unknown;
     /**
-     * 사람 — 선언하지 않으면 **인원 제약이 없는 트윈**이 된다(설비만 있으면 언제나 돌아가는 공장).
+     * 사람 — 선언하지 않으면 **인원 제약이 없는 트윈**이 된다(설비만 있으면 언제나 가동되는 공장).
      * 공정이 인원을 요구하는데 사람이 없으면 그 작업은 시작되지 않는다 — 그것이 사실이므로 그대로 둔다.
      */
     persons?: RefPerson[];
@@ -324,7 +433,7 @@ export interface ReferenceMaster {
     assets?: RefAsset[];
     /**
      * 등급 정의 — 표준 `PersonnelClass`·`EquipmentClass`·`PhysicalAssetClass`.
-     * 안 실어도 트윈은 돈다(소속 문자열 그대로 판정). 실으면 상속·유효기간이 살아난다.
+     * 안 실어도 트윈은 동작한다(소속 문자열 그대로 판정). 실으면 상속·유효기간이 살아난다.
      */
     personnelClasses?: RefResourceClass[];
     equipmentClasses?: RefResourceClass[];
@@ -332,11 +441,19 @@ export interface ReferenceMaster {
     /** 품목 정의·등급 — 표준 `MaterialDefinition` / `MaterialClass`. 없으면 단위 환산을 할 수 없다. */
     materialDefinitions?: RefMaterialDefinition[];
     materialClasses?: RefResourceClass[];
+    /**
+     * 커넥터가 **옮기는 동안 알게 된 것.** 외부 시스템의 값을 우리 어휘로 못 옮겨 기본값을 넣었다면
+     * 여기에 담아 보낸다 — 그러면 `masterToTwin` 의 경고와 한 줄기로 합쳐져 화면까지 간다.
+     *
+     * 이 자리가 없던 동안 커넥터는 할 말이 있어도 **말할 곳이 없었다.** 그래서 도크를 랙으로 바꿔
+     * 놓고도 조용히 성공했다. 옮기는 사람만 아는 사실은 옮기는 자리에서 실어야 한다.
+     */
+    warnings?: IngestWarning[];
 }
 export interface IngestedTwin {
-    board: any;
+    model: any;
     spaceContent: any;
-    warnings: string[];
+    warnings: IngestWarning[];
 }
 /**
  * 마스터 → 트윈 구조 매핑(순수). 노드타입을 카탈로그로 검증(모르는 타입은 warning, 버리진 않음 — 반영 우선).
@@ -349,11 +466,110 @@ export interface IngestedTwin {
  * 값이다. 그래서 8월의 `America/Tijuana` 는 −420(PDT), 1월은 −480(PST)이 된다.
  *
  * **한계를 밝힌다**: 여기서 나오는 것은 **한 시점의** 오프셋이다. 커널은 고정 오프셋으로 하루 중 분을
- * 읽으므로, 보드를 만든 계절과 다른 계절을 길게 예측하면 한 시간 어긋난다. 표준에 충실한 끝 모습은
+ * 읽으므로, 모델을 만든 계절과 다른 계절을 길게 예측하면 한 시간 어긋난다. 표준에 충실한 끝 모습은
  * 호스트가 절대 구간(`StartDateTime`/`FinishDateTime`)을 계산해 넣는 것이고, 그때 이 함수는 사라진다.
  *
  * 모르는 이름에는 **0 을 답하지 않는다**(`undefined`) — 0 은 "UTC 라고 선언했다" 는 뜻이고, 모르는 것을
  * 그렇게 바꾸면 판정이 조용히 틀린다.
  */
 export declare function utcOffsetOf(timezone?: string, at?: Date): number | undefined;
+/** 인제스트가 알리는 한 가지. */
+export interface IngestWarning {
+    /** 언어 중립 코드. 화면은 `twin.ingest.<code>` 로 렌더한다. */
+    code: string;
+    /** 문장에 끼울 값. 번역이 어순을 바꿀 수 있게 이름으로 넘긴다. */
+    params?: Record<string, string | number>;
+    /** 영어 canonical 문장 — 로그·폴백용. 번역이 없어도 읽을 수 있어야 한다. */
+    message: string;
+}
+/**
+ * **시각을 모르는 채 시각으로 판정하려 한다** — 발전 형상은 하루의 시각을 읽는데 이 트윈의 공간이
+ * 시간대를 말하지 않았다.
+ *
+ * ── 왜 경고인가 (2026-08-18) ────────────────────────────────────────────────
+ * 커널은 시간대를 모르면 UTC 로 읽는다(계약에 밝혀 둔 규율 — 모르는 값을 지어내지 않는다). 그런데 발전
+ * 형상은 **시각별 비율**이라, 시간대가 없으면 현장 정오가 아니라 UTC 정오에 피크가 선다(KST 현장이면
+ * 밤 9시). 값이 그럴듯하게 나오므로 아무도 알아채지 못한다.
+ *
+ * 그래서 시간대를 **지어내지 않고**(서버 로컬이나 임의 기본값을 넣으면 그 트윈의 모든 시각 판정이 조용히
+ * 그 가정 위에 선다) 대신 **그 조합을 말한다** — 공간에 시간대를 선언하면 사라지는 경고다.
+ */
+export declare const generationWithoutTimeZone: (spaceId: string, equipmentId: string) => IngestWarning;
+/** 커널 카탈로그가 모르는 자리 타입 — 그 자리는 흐름에 참여하지 못할 수 있다. */
+export declare const unknownLocationType: (system: string, type: string, id: string) => IngestWarning;
+/** 시간대 문자열을 못 읽었다 — 시각 해석이 UTC 로 떨어진다(조용히 현지 시각으로 가정하지 않는다). */
+export declare const unknownTimezone: (timezone: string) => IngestWarning;
+/** 작업 정의에 소요시간·파라미터가 없다 — 커널 기본값으로 동작한다. */
+export declare const operationWithoutDuration: (operation: string) => IngestWarning;
+/** 볼 수 있는 표현이 없다 — 현장이 화면에 뜨지 않는다. */
+export declare const noViewableRepresentation: () => IngestWarning;
+/**
+ * 구조 투영에서 **가리키는 대상을 못 찾았다.**
+ *
+ * 예전에는 이런 참조가 model JSON 안의 맨 문자열이라 화면만 경고할 수 있었고, 다른 경로로 들어온
+ * 데이터는 아무도 안 봤다. 이제 행으로 풀면서 **인제스트가 직접 안다** — 그러니 인제스트가 말한다.
+ * 막지는 않는다(트윈은 model 로 이미 동작한다). 다만 조용히 넘기지 않는다.
+ */
+export declare const unresolvedReference: (field: string, ref: string) => IngestWarning;
+/**
+ * 구조 투영 자체가 실패했다 — 조회는 못 하지만 **트윈은 동작한다**(커널은 model 를 이미 받았다).
+ * 행은 원본에서 다시 그릴 수 있으므로 인제스트를 실패로 만들지 않되, 침묵하지도 않는다.
+ */
+export declare const projectionFailed: (reason: string) => IngestWarning;
+/**
+ * **동작 중에 공장을 전환했다** — 미러는 멈추지 않으므로, 무엇이 사라졌는지 여기서 말한다.
+ *
+ * 멈췄다 세우는 구조 전환이라면 사용자가 "다시 세웠다" 는 것을 안다. 미러는 그 마디가 없어서
+ * 자리 하나·설비 한 대가 조용히 없어질 수 있다 — 자리가 수천인 현장에서 화면의 수를 세어
+ * 눈치채기를 기대할 수는 없다. 늘어난 것도 함께 말한다(무엇이 반영되었나가 곧 인제스트의 답이다).
+ */
+export declare const structureAdopted: (rev: number, shift: {
+    locationsAdded: number;
+    locationsDropped: number;
+    equipmentDropped: number;
+    personsDropped: number;
+    assetsDropped: number;
+}) => IngestWarning;
+/**
+ * 커넥터가 외부 시스템의 값을 **우리 어휘로 옮기지 못해 기본값을 넣었다.**
+ *
+ * 예: Oracle WMS 가 우리 표에 없는 `locn_type` 을 주면 그 자리는 `storage` 가 된다 — 도크가 랙으로
+ * 모델링되는 것이다. 인제스트를 통째로 실패시킬 일은 아니지만(로케이션 하나 때문에 현장 전체가
+ * 안 들어오는 편이 더 나쁘다), **조용히 넘어가면 안 된다.** 트윈이 실물과 다르게 생겼는데
+ * 아무도 그 사실을 모른 채 그 위에서 흐름을 논하게 된다.
+ *
+ * 값을 나열하는 이유: "3건" 만으로는 커넥터 매핑에 무엇을 더해야 하는지 알 수 없다.
+ */
+export declare const connectorMappingFallback: (field: string, fallback: string, values: readonly string[], count: number) => IngestWarning;
+/** 로그 한 줄 — 개발자가 읽는 것이므로 영어 canonical 문장을 쓴다. */
+export declare const describeWarnings: (warnings: readonly IngestWarning[]) => string;
+/**
+ * 서버가 기본값으로 채운 노브들 — 사용자가 준 적 없는 값으로 트윈이 만들어졌음을 알린다.
+ *
+ * 조용히 채우면 나중에 "왜 이 수치인가" 를 아무도 답할 수 없다. 막을 일은 아니다(기본값은 템플릿이
+ * 확신을 갖고 선언한 값이다) — 다만 밝힌다.
+ */
+export declare const knobDefaultsFilled: (keys: readonly string[]) => IngestWarning;
+/**
+ * 이 현장의 설비를 노브 값으로 채웠다 — **조용히 채우지 않는다.**
+ *
+ * 에너지 트윈의 부하를 이웃 설비 id 로 선언할 때 쓴다. 몇 개를 가져왔는지 말해 주지 않으면, 사용자는
+ * 자기가 고르지 않은 설비들이 부하로 잡힌 것을 나중에 화면에서야 알게 된다.
+ */
+export declare const siteEquipmentAdopted: (key: string, count: number) => IngestWarning;
 export declare function masterToTwin(master: ReferenceMaster, catalog?: any): IngestedTwin;
+/**
+ * 다시 읽을 사이트를 고른다 — **기억해 둔 사이트 하나만**.
+ *
+ * 못 찾으면 **첫 사이트로 때우지 않는다**: 다른 현장의 구조를 이 트윈에 덮어쓰는 일이고, 그것은 오류가
+ * 아니라 **조용히 틀린 공장**으로 나타난다. 기억이 없는 옛 트윈은 `undefined` 를 돌려주고, 부르는 쪽이
+ * 마스터의 정체(`source` = 인스턴스 id)로 찾는 길을 택한다.
+ */
+export declare function pickOriginSite<T extends {
+    siteId: string;
+}>(sites: readonly T[], origin: {
+    siteId?: string;
+} | undefined | null): {
+    site?: T;
+    reason?: 'no-remembered-site' | 'site-gone';
+};