@operato/ops-contract 0.4.0 → 0.5.0

package/dist/contract.d.ts

@@ -1379,17 +1379,43 @@ export interface EquipmentMotion {
  * → OEE=(run/planned)×quality. 세 인자가 손실 위치(셋업·기아·불량)를 분해해 드러낸다.
  */
 export interface OeeMetrics {
-    availability: number;
-    performance: number;
-    quality: number;
-    overall: number;
+    /**
+     * ── 세 비율은 **없을 수 있다** (2026-08-30) ──────────────────────────────
+     *
+     * 예전에는 근거가 없을 때 `1` 을 냈다. 잰 구간이 없는데 「가동률 100%」가 되고, 만든 것이 하나도
+     * 없는데 「양품률 100%」가 된다. **없는 근거로 좋은 숫자를 만드는 것**이고, 사용자는 그것으로
+     * 판단한다.
+     *
+     * 없으면 답하지 않는다. 무엇이 없어서인지는 `missing` 이 말한다.
+     */
+    availability?: number;
+    performance?: number;
+    quality?: number;
+    overall?: number;
+    /** 값이 없는 이유 — 비면 셋 다 나왔다는 뜻이다. */
+    missing?: OeeMissing[];
     runMs: number;
     setupMs: number;
     downMs: number;
-    idleMs: number;
+    delayMs: number;
     goodCount: number;
     scrapCount: number;
 }
+/**
+ * OEE 값이 없는 이유.
+ *
+ * 「모름」과 「0」은 다르다. 계획 조업 시간을 모르면 가동률을 낼 수 없고, 그때 0 을 내면 설비가
+ * 놀고 있는 것처럼 보이고 1 을 내면 완벽한 것처럼 보인다. 둘 다 거짓이다.
+ */
+export type OeeMissing = 
+/** 계획 조업 시간(PBT)을 모른다 — 아직 아무것도 재지 않았거나 근무 캘린더가 없다. */
+'planned-busy-time'
+/** 품목당 표준 시간(PRI)이 선언되지 않았다 — 성능률의 분자를 만들 수 없다. */
+ | 'planned-run-time-per-item'
+/** 만든 것이 없다 — 양품률을 낼 대상이 없다. */
+ | 'produced-quantity'
+/** 실 생산 시간이 0 이다 — 성능률의 분모가 없다. */
+ | 'actual-production-time';
 export interface EquipmentState extends EffectivePeriod {
     id: string;
     kind: string;

package/dist/index.d.ts

@@ -18,3 +18,4 @@ export * from './wms-profile.ts';
 export * from './yms-profile.ts';
 export * from './canonical-record.ts';
 export * from './version.ts';
+export * from './oee.ts';

package/dist/index.js

@@ -39,3 +39,4 @@ export * from "./wms-profile.js";
 export * from "./yms-profile.js";
 export * from "./canonical-record.js";
 export * from "./version.js";
+export * from "./oee.js";

package/dist/oee.d.ts

@@ -0,0 +1,54 @@
+import type { OeeMetrics } from './contract.ts';
+/**
+ * OEE 계측 카운터 — 시뮬은 틱으로, 라이브는 텔레메트리나 사건 누적기가 채운다.
+ *
+ * 이름은 ISO 22400-2 의 시간 항목을 따른다.
+ */
+export interface OeeCounters {
+    /** 실 생산 시간(APT) — 실제로 만들고 있던 시간. 준비·대기·고장은 여기 들어가지 않는다. */
+    runMs: number;
+    /** 준비(AUST). */
+    setupMs: number;
+    /** 고장(ADOT). */
+    downMs: number;
+    goodCount: number;
+    scrapCount: number;
+    /** 계획정지 — 계획 조업 시간에서 뺀다(점심·예방보전·교대). */
+    holdMs?: number;
+    /** 언제부터 쟀나. 없으면 잰 구간이 없는 것이고, 그때는 가동률을 낼 수 없다. */
+    metricsSinceMs?: number;
+    /**
+     * **품목당 표준 시간**(PRI) — 성능률의 분자를 만든다.
+     *
+     * 없으면 성능률을 내지 않는다. 이 값이 없는데 실 가동 시간으로 대신 나누면 「얼마나 빨리
+     * 만들었나」가 아니라 「얼마나 쉬지 않았나」가 되고, 이름만 성능률이 된다.
+     */
+    plannedRunTimePerItemMs?: number;
+}
+/**
+ * **OEE** — ISO 22400-2 의 정의를 따른다.
+ *
+ * ```
+ * PBT           계획 조업 시간 = 잰 구간 − 계획정지
+ * APT           실 생산 시간 = runMs
+ * availability  APT / PBT
+ * effectiveness PRI × PQ / APT          PQ = 양품 + 불량
+ * quality       GQ / PQ
+ * overall       셋의 곱
+ * ```
+ *
+ * ── 예전 식과 무엇이 달랐나 (2026-08-30 대조) ────────────────────────────
+ * 예전에는 가동률의 분자가 `PBT − 준비 − 고장` 이었다. **대기가 분자에 남아 있었다.** 표준은
+ * `AOET = APT + AUST + ADET + ADOT` 로 대기도 실 생산 시간에서 뺀다.
+ *
+ * 총합은 같았다(가동률 × 성능률이 양쪽 다 `runMs / PBT` 로 떨어진다). 다른 것은 두 값을 따로 볼
+ * 때다. 자재를 기다린 시간이 성능률로 넘어가 있어서, **자재 문제를 설비 성능 문제로 읽게 했다.**
+ * 공장이 손 쓰는 방법이 그 둘에서 갈린다 — 가동률이 낮으면 보전·자재를 보고, 성능률이 낮으면
+ * 사이클 타임을 본다.
+ *
+ * 성능률도 달랐다. 표준은 품목당 표준 시간으로 재는데 우리는 실 가동 시간의 비율을 냈다.
+ *
+ * 대조는 원문이 아니라 그 표준을 구현한 규격에서 했다(OPC Foundation MachineTool §C.2). ISO 22400-2
+ * 원문은 유료라 읽지 못했다 — 이 주석이 근거의 한계를 함께 말한다.
+ */
+export declare function computeOee(c: OeeCounters, nowMs: number): OeeMetrics;

package/dist/oee.js

@@ -0,0 +1,62 @@
+/**
+ * **OEE** — ISO 22400-2 의 정의를 따른다.
+ *
+ * ```
+ * PBT           계획 조업 시간 = 잰 구간 − 계획정지
+ * APT           실 생산 시간 = runMs
+ * availability  APT / PBT
+ * effectiveness PRI × PQ / APT          PQ = 양품 + 불량
+ * quality       GQ / PQ
+ * overall       셋의 곱
+ * ```
+ *
+ * ── 예전 식과 무엇이 달랐나 (2026-08-30 대조) ────────────────────────────
+ * 예전에는 가동률의 분자가 `PBT − 준비 − 고장` 이었다. **대기가 분자에 남아 있었다.** 표준은
+ * `AOET = APT + AUST + ADET + ADOT` 로 대기도 실 생산 시간에서 뺀다.
+ *
+ * 총합은 같았다(가동률 × 성능률이 양쪽 다 `runMs / PBT` 로 떨어진다). 다른 것은 두 값을 따로 볼
+ * 때다. 자재를 기다린 시간이 성능률로 넘어가 있어서, **자재 문제를 설비 성능 문제로 읽게 했다.**
+ * 공장이 손 쓰는 방법이 그 둘에서 갈린다 — 가동률이 낮으면 보전·자재를 보고, 성능률이 낮으면
+ * 사이클 타임을 본다.
+ *
+ * 성능률도 달랐다. 표준은 품목당 표준 시간으로 재는데 우리는 실 가동 시간의 비율을 냈다.
+ *
+ * 대조는 원문이 아니라 그 표준을 구현한 규격에서 했다(OPC Foundation MachineTool §C.2). ISO 22400-2
+ * 원문은 유료라 읽지 못했다 — 이 주석이 근거의 한계를 함께 말한다.
+ */
+export function computeOee(c, nowMs) {
+    const missing = [];
+    /* 계획 조업 시간 — 잰 구간을 모르면 없다. 0 으로 메우면 「1970년부터 재고 있었다」가 된다. */
+    const planned = c.metricsSinceMs == null ? 0 : Math.max(0, nowMs - c.metricsSinceMs - (c.holdMs ?? 0));
+    if (planned <= 0)
+        missing.push('planned-busy-time');
+    /* 대기는 남는 시간이다 — 계획 조업에서 생산·준비·고장을 뺀 것. 따로 재지 않아도 나온다. */
+    const delayMs = Math.max(0, planned - c.runMs - c.setupMs - c.downMs);
+    const availability = planned > 0 ? Math.min(1, c.runMs / planned) : undefined;
+    const produced = c.goodCount + c.scrapCount;
+    if (produced <= 0)
+        missing.push('produced-quantity');
+    const quality = produced > 0 ? c.goodCount / produced : undefined;
+    /* 성능률 — 표준 시간이 없으면 내지 않는다. 실 생산 시간이 0 이어도 나눌 수 없다. */
+    if (c.plannedRunTimePerItemMs == null)
+        missing.push('planned-run-time-per-item');
+    else if (c.runMs <= 0)
+        missing.push('actual-production-time');
+    const performance = c.plannedRunTimePerItemMs != null && c.runMs > 0
+        ? Math.min(1, (c.plannedRunTimePerItemMs * produced) / c.runMs)
+        : undefined;
+    const overall = availability != null && performance != null && quality != null ? availability * performance * quality : undefined;
+    return {
+        ...(availability != null ? { availability } : {}),
+        ...(performance != null ? { performance } : {}),
+        ...(quality != null ? { quality } : {}),
+        ...(overall != null ? { overall } : {}),
+        ...(missing.length ? { missing } : {}),
+        runMs: c.runMs,
+        setupMs: c.setupMs,
+        downMs: c.downMs,
+        delayMs,
+        goodCount: c.goodCount,
+        scrapCount: c.scrapCount
+    };
+}

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const CONTRACT_VERSION = "0.4.0";
+export declare const CONTRACT_VERSION = "0.5.0";

package/dist/version.js

@@ -11,4 +11,4 @@
  *
  * **정본은 `package.json` 이다.** 이 값이 그것과 같은지는 시험이 지킨다(§`version-matches`).
  */
-export const CONTRACT_VERSION = '0.4.0';
+export const CONTRACT_VERSION = '0.5.0';

package/dist-cjs/index.cjs

@@ -80,6 +80,7 @@ __export(index_exports, {
   classClosure: () => classClosure,
   classIdentifierViolation: () => classIdentifierViolation,
   commandsOf: () => commandsOf,
+  computeOee: () => computeOee,
   conversionFactorOf: () => conversionFactorOf,
   criterionSaysNothing: () => criterionSaysNothing,
   documentPath: () => documentPath,
@@ -3733,7 +3734,36 @@ function retiredVocabularyIn(line) {
 }
 
 // src/version.ts
-var CONTRACT_VERSION = "0.4.0";
+var CONTRACT_VERSION = "0.5.0";
+
+// src/oee.ts
+function computeOee(c, nowMs) {
+  const missing = [];
+  const planned = c.metricsSinceMs == null ? 0 : Math.max(0, nowMs - c.metricsSinceMs - (c.holdMs ?? 0));
+  if (planned <= 0) missing.push("planned-busy-time");
+  const delayMs = Math.max(0, planned - c.runMs - c.setupMs - c.downMs);
+  const availability = planned > 0 ? Math.min(1, c.runMs / planned) : void 0;
+  const produced = c.goodCount + c.scrapCount;
+  if (produced <= 0) missing.push("produced-quantity");
+  const quality = produced > 0 ? c.goodCount / produced : void 0;
+  if (c.plannedRunTimePerItemMs == null) missing.push("planned-run-time-per-item");
+  else if (c.runMs <= 0) missing.push("actual-production-time");
+  const performance = c.plannedRunTimePerItemMs != null && c.runMs > 0 ? Math.min(1, c.plannedRunTimePerItemMs * produced / c.runMs) : void 0;
+  const overall = availability != null && performance != null && quality != null ? availability * performance * quality : void 0;
+  return {
+    ...availability != null ? { availability } : {},
+    ...performance != null ? { performance } : {},
+    ...quality != null ? { quality } : {},
+    ...overall != null ? { overall } : {},
+    ...missing.length ? { missing } : {},
+    runMs: c.runMs,
+    setupMs: c.setupMs,
+    downMs: c.downMs,
+    delayMs,
+    goodCount: c.goodCount,
+    scrapCount: c.scrapCount
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BIZSTEP,
@@ -3797,6 +3827,7 @@ var CONTRACT_VERSION = "0.4.0";
   classClosure,
   classIdentifierViolation,
   commandsOf,
+  computeOee,
   conversionFactorOf,
   criterionSaysNothing,
   documentPath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@operato/ops-contract",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Operations domain contract — the standard vocabulary that producers and readers agree on (EPCIS 2.0/GS1, ISA-95, IEC 61850/ISO 50001). Types, guards, validation. No state, no engine.",
   "type": "module",
   "main": "./dist-cjs/index.cjs",