@fmsim/machine 2.0.0-beta.95 → 2.0.0-beta.97

package/dist/utils/stocker-gauge.js

@@ -0,0 +1,62 @@
+/*
+ * 스토커 게이지 세그먼트 계산 (2D/3D 공통 단일 소스).
+ *
+ * 2D(StockerCapacityBar) 와 3D(machine-3d buildGauge) 가 각자 세그먼트 비율/색상을
+ * 중복 계산하면 필드/색상 drift 가 발생한다(실제로 carrier 필드명이 어긋난 전례).
+ * 이 모듈이 carrier/abnormal 세그먼트 계산의 단일 소스이며 순수 함수라 단위 테스트가
+ * 용이하다. 표현(라벨 포맷·watermark·테두리색)은 렌더러별로 다르므로 여기서 다루지 않는다.
+ *
+ * canonical 데이터 필드(2D 기준):
+ *  - carrier  : CARRIER_FULL / CARRIER_EMPTY / CARRIER_EMPTY_EMPTY
+ *  - abnormal : CARRIER_NORMAL / CARRIER_ABNORMAL
+ */
+/** carrier 세그먼트 색상 (2D/3D 공통). */
+export const CARRIER_COLORS = {
+    full: '#4AA7FE',
+    empty: '#8BDA5B',
+    emptyEmpty: '#019D59'
+};
+/** abnormal 세그먼트 색상 (2D/3D 공통). */
+export const ABNORMAL_COLORS = {
+    normal: '#8BDA5B',
+    abnormal: '#F4B4B4'
+};
+function num(v) {
+    const n = Number(v);
+    return Number.isFinite(n) && n > 0 ? n : 0;
+}
+/** 캐리어 상태 세그먼트 (Full / Empty / EmptyEmpty). total 0 이면 모든 ratio 0. */
+export function carrierSegments(full, empty, emptyEmpty) {
+    const f = num(full);
+    const e = num(empty);
+    const ee = num(emptyEmpty);
+    const total = f + e + ee;
+    const r = (c) => (total > 0 ? c / total : 0);
+    return [
+        { label: 'Full', count: f, ratio: r(f), color: CARRIER_COLORS.full },
+        { label: 'Empty', count: e, ratio: r(e), color: CARRIER_COLORS.empty },
+        { label: 'Empty\nEmpty', count: ee, ratio: r(ee), color: CARRIER_COLORS.emptyEmpty }
+    ];
+}
+/** 캐리어 정상/비정상 세그먼트 (Normal / Abnormal). total 0 이면 모든 ratio 0. */
+export function abnormalSegments(normal, abnormal) {
+    const n = num(normal);
+    const a = num(abnormal);
+    const total = n + a;
+    const r = (c) => (total > 0 ? c / total : 0);
+    return [
+        { label: 'Normal', count: n, ratio: r(n), color: ABNORMAL_COLORS.normal },
+        { label: 'Abnormal', count: a, ratio: r(a), color: ABNORMAL_COLORS.abnormal }
+    ];
+}
+/** 캐리어 세그먼트 — canonical raw data(CARRIER_*) 에서 직접. 3D 처럼 raw data 소스용. */
+export function carrierSegmentsFromData(data) {
+    const d = data && typeof data === 'object' ? data : {};
+    return carrierSegments(d.CARRIER_FULL, d.CARRIER_EMPTY, d.CARRIER_EMPTY_EMPTY);
+}
+/** 비정상 세그먼트 — canonical raw data(CARRIER_*) 에서 직접. */
+export function abnormalSegmentsFromData(data) {
+    const d = data && typeof data === 'object' ? data : {};
+    return abnormalSegments(d.CARRIER_NORMAL, d.CARRIER_ABNORMAL);
+}
+//# sourceMappingURL=stocker-gauge.js.map

package/dist/utils/stocker-gauge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stocker-gauge.js","sourceRoot":"","sources":["../../src/utils/stocker-gauge.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * 스토커 게이지 세그먼트 계산 (2D/3D 공통 단일 소스).\n *\n * 2D(StockerCapacityBar) 와 3D(machine-3d buildGauge) 가 각자 세그먼트 비율/색상을\n * 중복 계산하면 필드/색상 drift 가 발생한다(실제로 carrier 필드명이 어긋난 전례).\n * 이 모듈이 carrier/abnormal 세그먼트 계산의 단일 소스이며 순수 함수라 단위 테스트가\n * 용이하다. 표현(라벨 포맷·watermark·테두리색)은 렌더러별로 다르므로 여기서 다루지 않는다.\n *\n * canonical 데이터 필드(2D 기준):\n *  - carrier  : CARRIER_FULL / CARRIER_EMPTY / CARRIER_EMPTY_EMPTY\n *  - abnormal : CARRIER_NORMAL / CARRIER_ABNORMAL\n */\n\nexport type StockerGaugeMode = 'capacity' | 'carrier' | 'abnormal'\n\nexport interface GaugeSegment {\n  /** 세그먼트 라벨(2D per-segment 표시용, '\\n' 은 줄바꿈). */\n  label: string\n  /** 카운트 원본값. */\n  count: number\n  /** 전체 대비 비율 (0~1). total 이 0 이면 0. */\n  ratio: number\n  /** 채움 색상. */\n  color: string\n}\n\n/** carrier 세그먼트 색상 (2D/3D 공통). */\nexport const CARRIER_COLORS = {\n  full: '#4AA7FE',\n  empty: '#8BDA5B',\n  emptyEmpty: '#019D59'\n}\n\n/** abnormal 세그먼트 색상 (2D/3D 공통). */\nexport const ABNORMAL_COLORS = {\n  normal: '#8BDA5B',\n  abnormal: '#F4B4B4'\n}\n\nfunction num(v: unknown): number {\n  const n = Number(v)\n  return Number.isFinite(n) && n > 0 ? n : 0\n}\n\n/** 캐리어 상태 세그먼트 (Full / Empty / EmptyEmpty). total 0 이면 모든 ratio 0. */\nexport function carrierSegments(full: unknown, empty: unknown, emptyEmpty: unknown): GaugeSegment[] {\n  const f = num(full)\n  const e = num(empty)\n  const ee = num(emptyEmpty)\n  const total = f + e + ee\n  const r = (c: number) => (total > 0 ? c / total : 0)\n  return [\n    { label: 'Full', count: f, ratio: r(f), color: CARRIER_COLORS.full },\n    { label: 'Empty', count: e, ratio: r(e), color: CARRIER_COLORS.empty },\n    { label: 'Empty\\nEmpty', count: ee, ratio: r(ee), color: CARRIER_COLORS.emptyEmpty }\n  ]\n}\n\n/** 캐리어 정상/비정상 세그먼트 (Normal / Abnormal). total 0 이면 모든 ratio 0. */\nexport function abnormalSegments(normal: unknown, abnormal: unknown): GaugeSegment[] {\n  const n = num(normal)\n  const a = num(abnormal)\n  const total = n + a\n  const r = (c: number) => (total > 0 ? c / total : 0)\n  return [\n    { label: 'Normal', count: n, ratio: r(n), color: ABNORMAL_COLORS.normal },\n    { label: 'Abnormal', count: a, ratio: r(a), color: ABNORMAL_COLORS.abnormal }\n  ]\n}\n\n/** 캐리어 세그먼트 — canonical raw data(CARRIER_*) 에서 직접. 3D 처럼 raw data 소스용. */\nexport function carrierSegmentsFromData(data: any): GaugeSegment[] {\n  const d = data && typeof data === 'object' ? data : {}\n  return carrierSegments(d.CARRIER_FULL, d.CARRIER_EMPTY, d.CARRIER_EMPTY_EMPTY)\n}\n\n/** 비정상 세그먼트 — canonical raw data(CARRIER_*) 에서 직접. */\nexport function abnormalSegmentsFromData(data: any): GaugeSegment[] {\n  const d = data && typeof data === 'object' ? data : {}\n  return abnormalSegments(d.CARRIER_NORMAL, d.CARRIER_ABNORMAL)\n}\n"]}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@fmsim/machine",
   "description": "Layout View를 구성하는 설비(machine)들과 유닛을 구현한 모듈입니다.",
   "author": "heartyoh",
-  "version": "2.0.0-beta.95",
+  "version": "2.0.0-beta.97",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "things-scene": true,
@@ -55,5 +55,5 @@
       "prettier --write"
     ]
   },
-  "gitHead": "9281405a837f538acf8fc2955f2c2f79964cd360"
+  "gitHead": "f994681c569562e248ea20178a7749af6c4e050d"
 }

package/src/factories/machine-3d.ts

@@ -15,6 +15,12 @@ import type { Component } from '@hatiolab/things-scene'
 import { LEGEND_CAPACITY } from '../features/mcs-status-default'
 import { getValueOnRanges } from '../utils/get-value-on-ranges'
 import { fitGaugeScale } from '../utils/fit-gauge-scale'
+import {
+  carrierSegmentsFromData,
+  abnormalSegmentsFromData,
+  CARRIER_COLORS,
+  ABNORMAL_COLORS
+} from '../utils/stocker-gauge'
 import { Z_FMSIM } from './z-priority'
 
 // ── 설정 타입 ────────────────────────────────────────────
@@ -654,7 +660,7 @@ class StockerRealObject3D extends MCSRealObject3D {
   private buildGauge() {
     const comp = this.component as any
     const data = comp.data || {}
-    const gaugeMode = comp.root?.style?.stockerGaugeMode || 'capacity'
+    const gaugeMode = comp.root?.stockerGaugeMode || 'capacity'
 
     const gauge = this.resolveGauge(data, gaugeMode)
 
@@ -741,37 +747,28 @@ class StockerRealObject3D extends MCSRealObject3D {
   private resolveGauge(data: any, mode: string) {
     switch (mode) {
       case 'carrier': {
-        const full = Number(data.FULL_CNT) || 0
-        const empty = Number(data.EMPTY_CNT) || 0
-        const emptyEmpty = Number(data.EMPTYEMPTY_CNT) || 0
-        const total = full + empty + emptyEmpty
+        // 세그먼트 비율/색상은 2D 와 공유되는 단일 소스에서 계산 (필드/색상 drift 방지)
+        const [f, e, ee] = carrierSegmentsFromData(data)
+        const total = f.count + e.count + ee.count
         const segments = total > 0
-          ? [
-              { ratio: full / total, color: '#4AA7FE' },
-              { ratio: empty / total, color: '#8BDA5B' },
-              { ratio: emptyEmpty / total, color: '#019D59' },
-            ]
+          ? [f, e, ee].map(s => ({ ratio: s.ratio, color: s.color }))
           : [{ ratio: 1, color: '#dddddd' }]
         return {
           segments,
-          borderColor: '#4AA7FE',
-          label: total > 0 ? `F${full} E${empty} EE${emptyEmpty}` : '',
+          borderColor: CARRIER_COLORS.full,
+          label: total > 0 ? `F${f.count} E${e.count} EE${ee.count}` : '',
         }
       }
       case 'abnormal': {
-        const normal = Number(data.CARRIER_NORMAL) || 0
-        const abnormal = Number(data.CARRIER_ABNORMAL) || 0
-        const total = normal + abnormal
+        const [n, a] = abnormalSegmentsFromData(data)
+        const total = n.count + a.count
         const segments = total > 0
-          ? [
-              { ratio: normal / total, color: '#8BDA5B' },
-              { ratio: abnormal / total, color: '#F4B4B4' },
-            ]
+          ? [n, a].map(s => ({ ratio: s.ratio, color: s.color }))
           : [{ ratio: 1, color: '#dddddd' }]
         return {
           segments,
-          borderColor: abnormal > 0 ? '#F4B4B4' : '#8BDA5B',
-          label: total > 0 ? `N${normal} A${abnormal}` : '',
+          borderColor: a.count > 0 ? ABNORMAL_COLORS.abnormal : ABNORMAL_COLORS.normal,
+          label: total > 0 ? `N${n.count} A${a.count}` : '',
         }
       }
       default: { // capacity

package/src/scene/root-container-override.ts

@@ -25,6 +25,10 @@ declare module '@hatiolab/things-scene' {
     equipmentLegendTheme?: any
     style: any
     vehicleAnimation?: boolean
+    // 스토커 게이지 표시 모드 — 런타임 전용 transient (모델 비저장, 항상 'capacity' 시작)
+    stockerGaugeMode: string
+    _stockerGaugeMode?: string
+    _refreshStockerGauges(): void
     // 캐시 관련 속성 추가
     _animationConfigCache?: Map<string, any>
     _carrierManager?: CarrierManager
@@ -32,6 +36,17 @@ declare module '@hatiolab/things-scene' {
   }
 }
 
+/**
+ * 스토커 적재율 게이지 표시 모드 — 런타임 선택지.
+ * value 는 엔진 canonical(2D StockerCapacityBar / 3D buildGauge 공통), label 은 표시명.
+ * 런타임 UI(뷰어 컨트롤)가 이 목록으로 selector 를 구성한다.
+ */
+export const STOCKER_GAUGE_MODES: { value: string; label: string }[] = [
+  { value: 'capacity', label: 'Capacity' },
+  { value: 'carrier', label: 'Carrier Status' },
+  { value: 'abnormal', label: 'Abnormal Carrier' }
+]
+
 const ModelLayer = (Component as any).register('model-layer') as any
 
 Object.defineProperty(ModelLayer.prototype, 'nature', {
@@ -318,3 +333,45 @@ Object.defineProperty(RootContainer.prototype, 'carrierManager', {
     return this._carrierManager
   }
 })
+
+// === 스토커 게이지 표시 모드 (런타임 전용 transient) ===
+//
+// 모델(state)에 저장하지 않는다 — nature 속성이 아니므로 보드 직렬화에 포함되지 않고,
+// 보드를 다시 열면 항상 기본값 'capacity' 로 시작한다. 실행 중 뷰어 컨트롤 등이
+// `scene.root.stockerGaugeMode = 'carrier'` 로 동적 변경한다.
+//
+// 2D(StockerCapacityBar.gaugeMode) 와 3D(machine-3d buildGauge) 가 모두 이 값을 읽어
+// 게이지 표현이 항상 일치한다. 값이 바뀌면 setter 가 2D 리드로우 + 3D 게이지 재빌드를
+// 즉시 트리거한다.
+Object.defineProperty(RootContainer.prototype, 'stockerGaugeMode', {
+  get: function () {
+    return this._stockerGaugeMode || 'capacity'
+  },
+  set: function (mode: string) {
+    const next = mode || 'capacity'
+    if (this._stockerGaugeMode === next) return
+    this._stockerGaugeMode = next
+    this._refreshStockerGauges()
+  }
+})
+
+/** scene 하위 STOCKER(3D 게이지) + StockerCapacityBar(2D 게이지) 를 새 모드로 갱신. */
+RootContainer.prototype._refreshStockerGauges = function () {
+  const walk = (container: any) => {
+    const kids = container?.components
+    if (!Array.isArray(kids)) return
+    for (const c of kids) {
+      const type = c?.state?.type
+      if (type === 'STOCKER') {
+        // 3D 게이지는 스토커 자신의 real-object 가 그린다 → 재빌드 (2D 모드면 _realObject 없음)
+        c._realObject?.update?.()
+      } else if (type === 'StockerCapacityBar' || type === 'MCSGaugeCapacityBar') {
+        // 2D 게이지는 자식 컴포넌트가 그린다 → 리드로우
+        c.invalidate?.()
+      }
+      walk(c)
+    }
+  }
+  walk(this)
+  this.invalidate?.()
+}

package/src/stocker-capacity-bar.ts

@@ -13,6 +13,26 @@ import { LEGEND_CAPACITY, Legend } from './features/mcs-status-default'
 import { safeRound } from './utils/safe-round'
 import { getValueOnRanges } from './utils/get-value-on-ranges'
 import { ParentObjectMixin, ParentObjectMixinProperties } from './features/parent-object-mixin'
+import { carrierSegments, abnormalSegments, GaugeSegment } from './utils/stocker-gauge'
+
+/**
+ * 스토커 게이지 (통합).
+ *
+ * 하나의 컴포넌트가 mode 에 따라 3가지 게이지를 표현한다:
+ *  - 'capacity'  : 용량 사용률(usage%) 채움 게이지 + high/low watermark (기본)
+ *  - 'carrier'   : 캐리어 상태비율 세그먼트 (Full / Empty / EmptyEmpty)
+ *  - 'abnormal'  : 캐리어 정상/비정상 비율 세그먼트 (Normal / Abnormal)
+ *
+ * mode 소스: root.stockerGaugeMode (기본 'capacity').
+ * RootContainer 의 **런타임 전용 transient 속성** — 모델에 저장하지 않고 항상 'capacity'
+ * 로 시작하며 실행 중 동적으로만 변경된다(root-container-override.ts 정의). 3D 표현
+ * (machine-3d.ts buildGauge)과 동일 소스라 2D/3D 게이지가 항상 일치한다.
+ *
+ * 데이터 필드(2D 기준, canonical):
+ *  - capacity : CURRENTCAPACITY / MAXCAPACITY / HIGHWATERMARK / LOWWATERMARK / FULLUP
+ *  - carrier  : CARRIER_FULL / CARRIER_EMPTY / CARRIER_EMPTY_EMPTY
+ *  - abnormal : CARRIER_NORMAL / CARRIER_ABNORMAL
+ */
 
 const NATURE: ComponentNature = {
   mutable: false,
@@ -53,6 +73,31 @@ const NATURE: ComponentNature = {
       name: 'fullup',
       label: 'fullup'
     },
+    {
+      type: 'number',
+      name: 'carrierFull',
+      label: 'carrier-full'
+    },
+    {
+      type: 'number',
+      name: 'carrierEmpty',
+      label: 'carrier-empty'
+    },
+    {
+      type: 'number',
+      name: 'carrierEmptyEmpty',
+      label: 'carrier-empty-empty'
+    },
+    {
+      type: 'number',
+      name: 'carrierNormal',
+      label: 'carrier-normal'
+    },
+    {
+      type: 'number',
+      name: 'carrierAbnormal',
+      label: 'carrier-abnormal'
+    },
     {
       type: 'number',
       label: 'round',
@@ -97,6 +142,11 @@ export default class StockerCapacityBar extends ParentObjectMixin(MCSStatusMixin
     return ['STOCKER']
   }
 
+  /** 게이지 모드: RootContainer 런타임 transient 속성. 3D(machine-3d) 와 동일 소스. */
+  get gaugeMode(): string {
+    return (this.root as any)?.stockerGaugeMode || 'capacity'
+  }
+
   get controls() {
     var { left, top, width, round, height } = this.state
     round = round == undefined ? 0 : safeRound(round, width, height)
@@ -140,8 +190,15 @@ export default class StockerCapacityBar extends ParentObjectMixin(MCSStatusMixin
   }
 
   render(context: CanvasRenderingContext2D) {
-    const { left, top, width, height } = this.bounds
+    const mode = this.gaugeMode
 
+    if (mode === 'carrier' || mode === 'abnormal') {
+      this.renderSegmentGauge(context, this.segments(mode))
+      return
+    }
+
+    // capacity (기본)
+    const { width, height } = this.bounds
     if (width >= height) {
       this.renderLandscape(context)
     } else {
@@ -149,6 +206,107 @@ export default class StockerCapacityBar extends ParentObjectMixin(MCSStatusMixin
     }
   }
 
+  /**
+   * carrier/abnormal mode 의 세그먼트 목록 (공유 유틸 = 3D 와 동일 계산).
+   * 배열 순서 = portrait 아래→위 / landscape 왼→오.
+   */
+  segments(mode: string): GaugeSegment[] {
+    if (mode === 'abnormal') {
+      const { carrierNormal = 0, carrierAbnormal = 0 } = this.state
+      return abnormalSegments(carrierNormal, carrierAbnormal)
+    }
+    const { carrierFull = 0, carrierEmpty = 0, carrierEmptyEmpty = 0 } = this.state
+    return carrierSegments(carrierFull, carrierEmpty, carrierEmptyEmpty)
+  }
+
+  /** 세그먼트 게이지 렌더 (carrier/abnormal 공통). bounds 방향으로 landscape/portrait 자동. */
+  renderSegmentGauge(context: CanvasRenderingContext2D, segments: GaugeSegment[]) {
+    const { left, top, width, height } = this.bounds
+    const { lineWidth, strokeStyle, round, fillStyle = 'white' } = this.state
+    const landscape = width >= height
+
+    context.save()
+    context.translate(left, top)
+
+    // background
+    context.beginPath()
+    context.fillStyle = fillStyle
+    context.roundRect(0, 0, width, height, round)
+    context.fill()
+    context.clip()
+
+    if (landscape) {
+      // 왼→오
+      let x = 0
+      for (const seg of segments) {
+        const segWidth = width * seg.ratio
+        if (segWidth <= 0) continue
+
+        context.beginPath()
+        context.fillStyle = seg.color
+        context.rect(x, 0, segWidth, height)
+        context.fill()
+
+        this._drawSegmentLabel(context, seg, x, 0, segWidth, height)
+        x += segWidth
+      }
+    } else {
+      // 아래→위 (배열 첫 세그먼트가 바닥)
+      let y = height
+      for (const seg of segments) {
+        const segHeight = height * seg.ratio
+        if (segHeight <= 0) continue
+
+        y -= segHeight
+
+        context.beginPath()
+        context.fillStyle = seg.color
+        context.rect(0, y, width, segHeight)
+        context.fill()
+
+        this._drawSegmentLabel(context, seg, 0, y, width, segHeight)
+      }
+    }
+
+    // outline
+    context.beginPath()
+    context.setLineDash([])
+    context.strokeStyle = strokeStyle
+    context.lineWidth = lineWidth
+    context.roundRect(0, 0, width, height, round)
+    context.stroke()
+
+    context.translate(-left, -top)
+    context.restore()
+  }
+
+  private _drawSegmentLabel(
+    context: CanvasRenderingContext2D,
+    seg: GaugeSegment,
+    x: number,
+    y: number,
+    w: number,
+    h: number
+  ) {
+    const percent = Math.round(seg.ratio * 100)
+    const lines = seg.label.split('\n')
+    lines.push(`${percent}%`)
+
+    const fontSize = Math.max(9, Math.min(14, Math.min(w, h) * 0.22))
+    context.font = `bold ${fontSize}px sans-serif`
+    context.fillStyle = '#333'
+    context.textAlign = 'center'
+    context.textBaseline = 'middle'
+
+    const lineHeight = fontSize * 1.2
+    const totalHeight = lines.length * lineHeight
+    const startY = y + (h - totalHeight) / 2 + lineHeight / 2
+
+    for (let i = 0; i < lines.length; i++) {
+      context.fillText(lines[i], x + w / 2, startY + i * lineHeight)
+    }
+  }
+
   renderLandscape(context: CanvasRenderingContext2D) {
     const { left, top, width, height } = this.bounds
     const { highWatermark, lowWatermark, lineWidth, strokeStyle, round, fillStyle = 'white' } = this.state
@@ -303,13 +461,19 @@ export default class StockerCapacityBar extends ParentObjectMixin(MCSStatusMixin
   }
 
   onchangeData(after: Record<string, any>, before: Record<string, any>): void {
+    const data = this.data && typeof this.data == 'object' ? this.data : {}
     const {
       CURRENTCAPACITY = 0,
       MAXCAPACITY = 100,
       HIGHWATERMARK = 100,
       LOWWATERMARK = 0,
-      FULLUP = 'F'
-    } = this.data && typeof this.data == 'object' ? this.data : {}
+      FULLUP = 'F',
+      CARRIER_FULL = 0,
+      CARRIER_EMPTY = 0,
+      CARRIER_EMPTY_EMPTY = 0,
+      CARRIER_NORMAL = 0,
+      CARRIER_ABNORMAL = 0
+    } = data
 
     const currentUsage = Number(CURRENTCAPACITY) || 0
     const maxCapacity = Number(MAXCAPACITY) || 100
@@ -322,7 +486,12 @@ export default class StockerCapacityBar extends ParentObjectMixin(MCSStatusMixin
       highWatermark,
       lowWatermark,
       fullup: FULLUP == 'T',
-      usage: Math.round((currentUsage / maxCapacity) * 100)
+      usage: Math.round((currentUsage / maxCapacity) * 100),
+      carrierFull: Number(CARRIER_FULL) || 0,
+      carrierEmpty: Number(CARRIER_EMPTY) || 0,
+      carrierEmptyEmpty: Number(CARRIER_EMPTY_EMPTY) || 0,
+      carrierNormal: Number(CARRIER_NORMAL) || 0,
+      carrierAbnormal: Number(CARRIER_ABNORMAL) || 0
     })
   }
 }

package/src/utils/stocker-gauge.ts

@@ -0,0 +1,81 @@
+/*
+ * 스토커 게이지 세그먼트 계산 (2D/3D 공통 단일 소스).
+ *
+ * 2D(StockerCapacityBar) 와 3D(machine-3d buildGauge) 가 각자 세그먼트 비율/색상을
+ * 중복 계산하면 필드/색상 drift 가 발생한다(실제로 carrier 필드명이 어긋난 전례).
+ * 이 모듈이 carrier/abnormal 세그먼트 계산의 단일 소스이며 순수 함수라 단위 테스트가
+ * 용이하다. 표현(라벨 포맷·watermark·테두리색)은 렌더러별로 다르므로 여기서 다루지 않는다.
+ *
+ * canonical 데이터 필드(2D 기준):
+ *  - carrier  : CARRIER_FULL / CARRIER_EMPTY / CARRIER_EMPTY_EMPTY
+ *  - abnormal : CARRIER_NORMAL / CARRIER_ABNORMAL
+ */
+
+export type StockerGaugeMode = 'capacity' | 'carrier' | 'abnormal'
+
+export interface GaugeSegment {
+  /** 세그먼트 라벨(2D per-segment 표시용, '\n' 은 줄바꿈). */
+  label: string
+  /** 카운트 원본값. */
+  count: number
+  /** 전체 대비 비율 (0~1). total 이 0 이면 0. */
+  ratio: number
+  /** 채움 색상. */
+  color: string
+}
+
+/** carrier 세그먼트 색상 (2D/3D 공통). */
+export const CARRIER_COLORS = {
+  full: '#4AA7FE',
+  empty: '#8BDA5B',
+  emptyEmpty: '#019D59'
+}
+
+/** abnormal 세그먼트 색상 (2D/3D 공통). */
+export const ABNORMAL_COLORS = {
+  normal: '#8BDA5B',
+  abnormal: '#F4B4B4'
+}
+
+function num(v: unknown): number {
+  const n = Number(v)
+  return Number.isFinite(n) && n > 0 ? n : 0
+}
+
+/** 캐리어 상태 세그먼트 (Full / Empty / EmptyEmpty). total 0 이면 모든 ratio 0. */
+export function carrierSegments(full: unknown, empty: unknown, emptyEmpty: unknown): GaugeSegment[] {
+  const f = num(full)
+  const e = num(empty)
+  const ee = num(emptyEmpty)
+  const total = f + e + ee
+  const r = (c: number) => (total > 0 ? c / total : 0)
+  return [
+    { label: 'Full', count: f, ratio: r(f), color: CARRIER_COLORS.full },
+    { label: 'Empty', count: e, ratio: r(e), color: CARRIER_COLORS.empty },
+    { label: 'Empty\nEmpty', count: ee, ratio: r(ee), color: CARRIER_COLORS.emptyEmpty }
+  ]
+}
+
+/** 캐리어 정상/비정상 세그먼트 (Normal / Abnormal). total 0 이면 모든 ratio 0. */
+export function abnormalSegments(normal: unknown, abnormal: unknown): GaugeSegment[] {
+  const n = num(normal)
+  const a = num(abnormal)
+  const total = n + a
+  const r = (c: number) => (total > 0 ? c / total : 0)
+  return [
+    { label: 'Normal', count: n, ratio: r(n), color: ABNORMAL_COLORS.normal },
+    { label: 'Abnormal', count: a, ratio: r(a), color: ABNORMAL_COLORS.abnormal }
+  ]
+}
+
+/** 캐리어 세그먼트 — canonical raw data(CARRIER_*) 에서 직접. 3D 처럼 raw data 소스용. */
+export function carrierSegmentsFromData(data: any): GaugeSegment[] {
+  const d = data && typeof data === 'object' ? data : {}
+  return carrierSegments(d.CARRIER_FULL, d.CARRIER_EMPTY, d.CARRIER_EMPTY_EMPTY)
+}
+
+/** 비정상 세그먼트 — canonical raw data(CARRIER_*) 에서 직접. */
+export function abnormalSegmentsFromData(data: any): GaugeSegment[] {
+  const d = data && typeof data === 'object' ? data : {}
+  return abnormalSegments(d.CARRIER_NORMAL, d.CARRIER_ABNORMAL)
+}