@fmsim/machine 2.0.0 → 3.0.0-beta.1

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

@@ -12,8 +12,7 @@ import * as THREE from 'three'
 import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUtils.js'
 import { RealObjectGroup, registerRealObjectFactory, disposeObject3D, MaterialBank } from '@hatiolab/things-scene'
 import type { Component } from '@hatiolab/things-scene'
-import { LEGEND_CAPACITY, resolveCarrierLegend } from '../features/mcs-status-default'
-import { getValueOnRanges } from '../utils/get-value-on-ranges'
+import { LEGEND_CAPACITY, legendColor, legendRangeEntryOf, resolveCarrierLegend } from '../features/mcs-status-default'
 import { fitGaugeScale } from '../utils/fit-gauge-scale'
 import {
   carrierSegmentsFromData,
@@ -131,21 +130,10 @@ class MCSRealObject3D extends RealObjectGroup {
     if (this._config.defaultZPosFromParent) {
       return TRANSPORT_SURFACE_HEIGHT + halfD
     }
-    // Carrier: 부모 유형에 따라 배치 위치 결정
-    if (this._config.sizeRatio && this._config.sizeRatio < 1) {
-      const parentType = this.component.parent?.state?.type
-      // OHT: 그리퍼 아래에 매달림 — placement = -effectiveDepth(carrier top이 OHT bottom)
-      if (parentType === 'OHT') {
-        return -this.effectiveDepth + halfD
-      }
-      if (parentType === 'Port' || parentType === 'Shelf' || parentType === 'Shuttle') {
-        return halfD
-      }
-      return TRANSPORT_SURFACE_HEIGHT + halfD
-    }
     return halfD
   }
 
+
   // geometric 부분(center origin: depth/2)은 base 기본값 사용 — override 불필요
 
   // 컴포넌트의 상태 색상(statusColor) 또는 fillStyle → Three.js 색상 변환
@@ -799,7 +787,7 @@ class StockerRealObject3D extends MCSRealObject3D {
         const fullup = data.FULLUP === 'T'
         const usage = Math.round((cur / max) * 100)
         const legend = (this.component as any).root?.stockerCapacityLegendTheme || LEGEND_CAPACITY
-        const color = fullup ? 'red' : (getValueOnRanges(usage, legend) || '#44aa44')
+        const color = fullup ? 'red' : (legendColor(legendRangeEntryOf(usage, legend)) || '#44aa44')
         return {
           segments: [{ ratio: usage / 100, color }],
           borderColor: color,
@@ -918,46 +906,35 @@ const CARRIER_CONFIG: MCS3DConfig = {
 }
 
 /**
- * 적층 시 다음 carrier 의 z-position 이 *_이전 carrier 의 effectiveDepth × N*
- * 만큼 위에 놓인다. N=1 이면 carrier 들이 맞붙어 적층 (기존), N<1 이면 부분
- * overlap (3D box 들이 겹쳐서 적층). 사용자 의도 — carrier 두께는 두꺼워도
- * 적층 시 *_compact 하게 보이도록* — N 을 작게.
+ * Carrier 의 3D. 홀더가 자리에 앉힌다 (공통 아이템 계약 3.4): 위치·회전은 홀더의 Anchor 노드 위 안착이고, 크기는 홀더가
+ * 보이는 치수(타입의 선언 치수, 모르면 자리의 표시용 상자)다. 자리 안에 들도록 줄이는 배율도 홀더가 준다.
  */
-const CARRIER_STACK_STEP_RATIO = 0.9
-
 class CarrierRealObject3D extends MCSRealObject3D {
   constructor(component: Component) {
     super(component, CARRIER_CONFIG)
   }
 
-  /**
-   * cz override — *carrier 자기 결정* 의 적층 위치.
-   * parent.components 안 자기 index 까지의 형제 carrier 들의 effectiveDepth
-   * 누적합을 base cz 위에 더한다. holder 측에 별도 layout 책임을 두지 않고,
-   * carrier 가 자기 stack 위치를 알아서 결정.
-   */
-  override get cz(): number {
-    const base = super.cz
-    const parent = this.component.parent as any
-    if (!parent?.components) return base
-    const siblings = parent.components as any[]
-    const idx = siblings.indexOf(this.component)
-    if (idx <= 0) return base
-    let offset = 0
-    for (let i = 0; i < idx; i++) {
-      const ro = siblings[i]?._realObject
-      const eff = Number(ro?.effectiveDepth)
-      const d = Number.isFinite(eff) && eff > 0 ? eff : 1
-      offset += d * CARRIER_STACK_STEP_RATIO
-    }
-    // 적층 방향 — placement (= 부모 holder 타입) 에 따라 결정.
-    // OHT 처럼 그리퍼 아래에 매달리는 holder 는 carrier 가 *_아래로_* 누적,
-    // 그 외 (Port / Shelf / Shuttle / Vehicle) 는 위로 누적.
-    // MCSRealObject3D.syncZPosOffset 의 OHT 분기 (-effectiveDepth + halfD) 와
-    // 같은 방향성 일관 적용.
-    const parentType = parent?.state?.type
-    const dir = parentType === 'OHT' ? -1 : 1
-    return base + dir * offset
+  /** 홀더가 보이는 치수 (도면 단위): 폭(X)·깊이(도면 Z)·높이. 모르면 null */
+  private get shown(): { w: number; d: number; h: number } | null {
+    const holder = this.component.parent as any
+    const dims = holder?.carrierShownDimsOf?.(this.component)
+    const k = holder?.mmPerSceneUnit
+    if (!dims || !(k > 0)) return null
+    return { w: dims.width / k, d: dims.depth / k, h: dims.height / k }
+  }
+
+  /** build 가 sizeRatio 를 곱하므로 미리 나눈다 */
+  protected override get absSize(): { w: number; h: number } {
+    const shown = this.shown
+    if (!shown) return super.absSize
+    const ratio = CARRIER_CONFIG.sizeRatio ?? 1
+    return { w: shown.w / ratio, h: shown.d / ratio }
+  }
+
+  override get effectiveDepth(): number {
+    const shown = this.shown
+    if (!shown) return super.effectiveDepth
+    return shown.h / (CARRIER_CONFIG.sizeRatio ?? 1)
   }
 }
 

package/src/features/capacity-gauge-mixin.ts

@@ -1,8 +1,7 @@
 import { Component, POSITION } from '@hatiolab/things-scene'
 import { themesColorRange } from '@fmsim/api'
-import { LEGEND_CAPACITY, Legend, resolveCarrierLegend } from './mcs-status-default'
+import { LEGEND_CAPACITY, Legend, legendColor, legendRangeEntryOf, resolveCarrierLegend } from './mcs-status-default'
 import { safeRound } from '../utils/safe-round'
-import { getValueOnRanges } from '../utils/get-value-on-ranges'
 import { carrierSegments, abnormalSegments, carrierColorsFromLegend, pickSegmentAt, GaugeSegment } from '../utils/stocker-gauge'
 
 type Constructor<T = {}> = new (...args: any[]) => T
@@ -158,7 +157,7 @@ export function CapacityGaugeMixin<TBase extends Constructor<Component>>(Base: T
 
     get statusColor(): string | undefined {
       const { fullup } = (this as any).state
-      return fullup ? 'red' : getValueOnRanges(this.usage, this.legend)
+      return fullup ? 'red' : legendColor(legendRangeEntryOf(this.usage, this.legend))
     }
 
     get text() {

package/src/features/load-layout-holder.ts

@@ -0,0 +1,83 @@
+/*
+ * 적재 레이아웃 홀더 (설계 02번 3.2.1절, 3.6.1절, 3.7.1절)
+ * 홀더의 실효 레이아웃에서 Carrier 를 주소의 자리에 배정한다.
+ *
+ * 보유·자리·안착·판정은 공통 아이템 계약의 것이다(things-scene Capacity·Holdable, figure-model). 실효 레이아웃은
+ * Capacity.effectiveLayout 이 정한다: 도면 노드의 개별 설정(state.slotLayout)이 있으면 그것, 없으면 홀더의 기본값.
+ * 이 믹스인에 남는 것은 MCS 의 몫이다: 실시간 데이터의 주소 읽기와 점유 배정, 예외를 어느 밖 자리에 둘지.
+ *
+ * 유효한 실효 레이아웃이 있고 도면 축척을 알 때만 자리를 배정한다. 그 밖에는 MCSCarrierHolder 대로 모두 한 무더기(pile)다.
+ */
+
+import { resolveSlot, slotAddresses, slotIdOf, type ItemDims, type ResolvedSlot, type SlotMount } from '@hatiolab/figure-model'
+import { drawingScaleFor, type DrawingScale } from '@hatiolab/things-scene'
+import { LoadLayout, OccupancyResult, incomingFromV2, resolveOccupancy } from '../utils/load-address'
+import { EXCEPTION_SLOT, type CarrierRecord } from '../mcs-carrier-holder'
+
+type Constructor<T = any> = new (...args: any[]) => T
+
+export function LoadLayoutHolder<TBase extends Constructor>(Base: TBase) {
+  return class extends Base {
+    _loadOccupancy?: OccupancyResult
+
+    /** 기본 레이아웃의 Tier 가 서는 방식. 기종별 프리셋 배정은 확정 대기 (3.8절) */
+    get loadMount(): SlotMount {
+      return 'ON'
+    }
+
+    /**
+     * 도면 좌표 1단위당 mm 와 그것을 아는지. things-scene 이 도면 축척을 읽는 한 곳(drawingScaleFor, ADR-0144 2.2)에서
+     * 받는다. 축척이 없는 도면(known: false)에서는 자리를 배정하지 않는다.
+     */
+    get mmPerUnit(): DrawingScale {
+      return drawingScaleFor(this as any)
+    }
+
+    /** 자리를 배정하는 레이아웃. 유효한 실효 레이아웃이 없거나 축척을 모르면 undefined (한 무더기로 쌓는다) */
+    get _validLoadLayout(): LoadLayout | undefined {
+      const sel = (this as any).effectiveLayout
+      return sel.status === 'valid' && this.mmPerUnit.known ? (sel.layout as LoadLayout) : undefined
+    }
+
+    /**
+     * Carrier 마다 자리를 정한 레코드 (설계 02번 3.6.1절). 정상 자리는 자리마다 아래에서 위로, 예외는 그 뒤에 예외 영역에.
+     * 같은 이름이 두 번 오면 데이터 그대로 넘겨 공통 대조가 스냅샷째 거절하게 한다 (계약 Q2).
+     */
+    carrierRecords(data: Record<string, any> | undefined): CarrierRecord[] {
+      const layout = this._validLoadLayout
+      if (!layout) {
+        this._loadOccupancy = undefined
+        return super.carrierRecords(data)
+      }
+      const incoming = incomingFromV2(data)
+      const occupancy = resolveOccupancy(layout, incoming, this._loadOccupancy)
+      this._loadOccupancy = occupancy
+      const stateOf = new Map(incoming.map(c => [c.name, (this as any).carrierStateOf(c.record, c.record === data)] as const))
+      if (stateOf.size !== incoming.length) return incoming.map(c => ({ slotId: EXCEPTION_SLOT, itemId: c.name, itemState: stateOf.get(c.name)! }))
+      const records: CarrierRecord[] = []
+      for (const list of occupancy.slots.values()) for (const c of list) records.push({ slotId: slotIdOf(c.address), itemId: c.name, itemState: stateOf.get(c.name)! })
+      // 예외는 정상 자리와 나눈 예외 영역에 차례로 둔다. 다른 정상 자리를 대신 쓰지 않는다
+      for (const c of [...occupancy.addressUnknown, ...occupancy.addressError]) records.push({ slotId: EXCEPTION_SLOT, itemId: c.name, itemState: stateOf.get(c.name)! })
+      return records
+    }
+
+    /** 예외 영역의 치수 모르는 Carrier 는 첫 자리를 채우는 표시용 상자로 보인다 */
+    itemShownDimsOf(carrier: any, slot: ResolvedSlot, slotId: string): ItemDims | null {
+      if (slotId !== EXCEPTION_SLOT) return super.itemShownDimsOf(carrier, slot, slotId)
+      const first = this._firstSlot
+      return first ? super.itemShownDimsOf(carrier, first, slotIdOf({ tier: first.tier, slot: first.slotNo })) : null
+    }
+
+    /** 예외 영역의 Carrier 는 첫 자리 폭의 절반만큼 더 떨어져 선다 */
+    get exceptionHalfWidth(): number {
+      const first = this._firstSlot
+      return first && Number.isFinite(first.allowed.width) ? first.allowed.width / 2 : 0
+    }
+
+    get _firstSlot(): ResolvedSlot | null {
+      const layout = this._validLoadLayout
+      const address = layout ? [...slotAddresses(layout)][0] : undefined
+      return layout && address ? resolveSlot(layout, address) : null
+    }
+  }
+}

package/src/features/mcs-status-default.ts

@@ -1,5 +1,31 @@
-export interface Legend {
-  [key: string]: string
+import { resolveLegend, resolveLegendEntries, type LegendEntry as RangeEntry } from '@hatiolab/things-scene'
+import { LEGEND_CARRIER, legendColor, type Legend, type LegendEntry } from '@fmsim/figure-capabilities'
+
+/* 범례 항목 모양과 캐리어 기본 범례는 피규어 능력과 한 곳(@fmsim/figure-capabilities, ADR-0167) */
+export { LEGEND_CARRIER, legendColor, type Legend, type LegendEntry }
+
+/**
+ * 코드의 범례 항목: 그 코드의 항목, 없으면 `default` (ADR-0166 판정 6). things-scene 의 한 조회(resolveLegend)로 읽는다 — 피규어의 표와
+ * 보드 매핑이 읽는 것과 같다.
+ */
+export function legendEntryOf(code: unknown, legend: Legend | null | undefined): LegendEntry | undefined {
+  return resolveLegend(code, legend)
+}
+
+/**
+ * 수의 구간 범례 항목: 키 `from~to`(from 이상 to 미만, 한쪽 열림 가능)에서 그 값을 품은 항목, 없으면 `default`. 값이 없거나 수가 아니면
+ * `default` 다(ADR-0166 판정 6 — 0 으로 읽지 않는다). things-scene 의 한 조회(resolveLegendEntries)로 읽는다.
+ */
+export function legendRangeEntryOf(value: unknown, legend: Legend | null | undefined): LegendEntry | undefined {
+  if (!legend) return undefined
+  const entries: RangeEntry<LegendEntry>[] = []
+  for (const [key, entry] of Object.entries(legend)) {
+    if (key === 'default') continue
+    const [from = '', to = ''] = key.split('~')
+    if (!key.includes('~')) continue
+    entries.push({ min: from === '' ? null : from, max: to === '' ? null : to, result: entry })
+  }
+  return resolveLegendEntries(value, entries, legend.default)
 }
 
 export const LEGEND_NULL: Legend = { default: '#F0F0F0' }
@@ -54,13 +80,6 @@ export const LEGEND_CRANE: Legend = {
   default: '#F0F0F0'
 }
 
-export const LEGEND_CARRIER: Legend = {
-  FULL: '#4AA7FE',
-  EMPTY: '#8BDA5B',
-  EMPTYEMPTY: '#019D59',
-  default: '#F0F0F0'
-}
-
 /**
  * carrier legend(테마) 해석 — carrier 컴포넌트(carrier.ts get legend)와 동일 로직 단일 소스.
  * parent 에 carrierLegendName 이 지정되면 그 style 을, 아니면 board 전역 carrierLegendTheme,
@@ -78,7 +97,7 @@ export const LEGEND_CAPACITY: Legend = {
   '0~20': '#5630D0',
   '20~80': '#8BDA5B',
   '80~': '#FD9B00',     // 80% 이상 (= 100% 초과도 포함). 'from~' 형식이라
-                        // getValueOnRanges 가 value >= 80 매칭.
+                        // legendRangeEntryOf 가 value >= 80 매칭.
   default: '#F0F0F0'
 }
 

package/src/features/mcs-status-mixin.ts

@@ -1,13 +1,9 @@
 import { Component } from '@hatiolab/things-scene'
 import { themesColorMap } from '@fmsim/api'
-import { LEGEND_NULL } from './mcs-status-default'
+import { LEGEND_NULL, Legend, legendColor, legendEntryOf } from './mcs-status-default'
 
 type Constructor<T = {}> = new (...args: any[]) => T
 
-interface Legend {
-  [key: string]: string
-}
-
 export const MCSStatusMixinProperties = [
   {
     type: 'select',
@@ -45,14 +41,14 @@ export function MCSStatusMixin<TBase extends Constructor<Component>>(Base: TBase
       const status = this.status
       const legend = this.legend
 
-      return (status && legend && (legend[status] || legend[status!] || legend.default)) || legend?.default || '#F0F0F0'
+      return (status && legend && legendColor(legendEntryOf(status, legend))) || legendColor(legend?.default) || '#F0F0F0'
     }
 
     get auxColor(): string | undefined {
       const status = this.auxStatus
       const legend = this.auxLegend
 
-      return (status && legend && (legend[status] || legend[status!] || legend.default)) || legend?.default
+      return (status && legend && legendColor(legendEntryOf(status, legend))) || legendColor(legend?.default)
     }
 
     /**

package/src/index.ts

@@ -54,6 +54,9 @@ import './clickable-popup'
 // ── groups ──
 export { default as MachineGroups } from './groups'
 
+// ── legends ──
+export { legendColor, legendEntryOf, legendRangeEntryOf, type Legend, type LegendEntry } from './features/mcs-status-default'
+
 // ── base classes ──
 export { default as MCSMachine } from './mcs-machine'
 export { default as MCSUnit } from './mcs-unit'
@@ -89,6 +92,7 @@ export { default as Port } from './port'
 export { default as Crane } from './crane'
 export { default as Shelf } from './shelf'
 export { default as Carrier } from './carrier'
+export { CARRIER_HOLDER_PROPERTIES, CarrierHolder, carrierHolderLegend } from './mcs-carrier-holder'
 
 // ── topology ──
 export { default as Node } from './node'
@@ -98,3 +102,6 @@ export { default as NodePath } from './node-path'
 export { default as FloatingContainer } from './floating-container'
 export { default as StaticContainer } from './static-container'
 export { default as ClickablePopup } from './clickable-popup'
+
+// ── CARRIERTYPE 을 아이템 타입 코드로 맞추는 규칙 (01번 6.8절, ADR-0155) ──
+export { normalizeTypeCode } from './utils/carrier-type-code'