@operato/scene-storage 10.0.0-beta.50 → 10.0.0-beta.54

package/src/stockpile.ts

@@ -19,6 +19,7 @@ import type { State, Material3D } from '@hatiolab/things-scene'
 import {
   CarrierHolder,
   Placeable,
+  RecordStorage,
   SlotTarget,
   type AttachFrame,
   type Alignment,
@@ -103,7 +104,9 @@ const NATURE: ComponentNature = {
 }
 
 @sceneComponent('stockpile')
-export default class Stockpile extends CarrierHolder(Placeable(ContainerAbstract)) {
+export default class Stockpile extends RecordStorage<StockpileRecord>()(
+  CarrierHolder(Placeable(ContainerAbstract))
+) {
   declare state: StockpileState
   declare _realObject?: Stockpile3D
 
@@ -114,15 +117,11 @@ export default class Stockpile extends CarrierHolder(Placeable(ContainerAbstract
   get nature(): ComponentNature { return NATURE }
   get anchors() { return [] }
 
-  // ── records (state.data 의 읽기 전용 뷰, storage-rack 패턴) ─────────────
-  get records(): ReadonlyArray<StockpileRecord> {
-    return (this.state.data as StockpileRecord[]) ?? []
-  }
-  get inventoryCount(): number {
-    return this.records.length
-  }
+  // ── records / inventoryCount: RecordStorage mixin 제공.
 
-  // ── SlottedHolder duck-type — 단일 slot ('pile') ────────────────────────
+  // ── SlottedHolder duck-type override — 단일 slot ('pile') ───────────────
+  // mixin default 는 record 마다 slotId. Stockpile 은 *_단일 슬롯_* 시맨틱이라
+  // 자기 구현 유지.
   slotIds(): ReadonlyArray<string> { return [SLOT_ID] }
 
   hasCarrierAt(slotId: string): boolean {
@@ -260,9 +259,9 @@ export default class Stockpile extends CarrierHolder(Placeable(ContainerAbstract
     return (this as any)._realObject?.getAttachFrame?.(slotId)
   }
 
-  /** state.data 갱신 + 3D 즉시 재배치. */
-  private _setDataSilently(records: StockpileRecord[]): void {
-    ;(this.state as any).data = records
+  // _setDataSilently 는 RecordStorage mixin 제공 — 다만 mixin 은 _rebuildVisual
+  // 호출. Stockpile 의 3D 갱신은 update() 라서 hook override.
+  _rebuildVisual(): void {
     this._realObject?.update?.()
   }
 
@@ -329,38 +328,32 @@ export default class Stockpile extends CarrierHolder(Placeable(ContainerAbstract
     // hit.object 가 carrier mesh 면 userData.recordId 보유 → 그 stock 의 popup.
     // pad / 기타면 stockpile 전체 popup.
     const recordId = hit.object?.userData?.recordId as string | undefined
-    this._invokePopup(typeof recordId === 'string' ? recordId : undefined)
+    this._dispatchStockpilePopup(typeof recordId === 'string' ? recordId : undefined)
   }
 
   /**
    * state.popupRef 가 가리키는 Popup 컴포넌트를 invoke.
    *   - recordId 명시 → 그 record 의 anchor = mesh. payload = 해당 record.
    *   - 미명시 (pad 클릭) → 'pile' anchor (pad). payload = 전체 inventory.
-   * anchor 는 SlotTarget — Popup 이 anchor.holder.getSlotAttachObject3d(anchor.slotId)
-   * 로 tether 위치 잡음 (storage-rack 와 동일 패턴).
+   *
+   * RecordStorage mixin 의 `_invokePopup(slotId, payload)` 를 활용. 단일 slot
+   * 시맨틱이 record/pile 두 모드라 mixin 위 wrapper 로 dispatch.
    */
-  private _invokePopup(recordId?: string): void {
-    const popupRefId = this.state.popupRef
-    if (!popupRefId) return
-    const popupComp: any = (this as any).root?.findById?.(popupRefId)
-    if (!popupComp || typeof popupComp.openPopup !== 'function') {
-      console.warn(`[stockpile] popupRef="${popupRefId}" 가 가리키는 컴포넌트 없거나 openPopup 미지원`)
-      return
-    }
+  private _dispatchStockpilePopup(recordId?: string): void {
+    if (!this.state.popupRef) return
     if (recordId) {
-      const record = this.records.find(r => r.id === recordId) ?? { id: recordId }
-      const anchor = this.slotTargetAt(recordId)
-      popupComp.openPopup(record, { anchor })
+      const record = (this.records as ReadonlyArray<StockpileRecord>)
+        .find(r => r.id === recordId) ?? { id: recordId }
+      this._invokePopup(recordId, record)
     } else {
-      const anchor = this.slotTargetAt(SLOT_ID)
-      popupComp.openPopup({
+      this._invokePopup(SLOT_ID, {
         componentId: (this.state as any).id,
         records: this.records,
         inventoryCount: this.inventoryCount,
         capacity: this.state.capacity,
         carrierPreset: this.state.carrierPreset,
         stackPattern: this.state.stackPattern
-      }, { anchor })
+      })
     }
   }
 
@@ -412,81 +405,7 @@ export default class Stockpile extends CarrierHolder(Placeable(ContainerAbstract
     return undefined
   }
 
-  // ── Legend — record 의 field 값 → 색상 매핑 (StorageRack 동일 패턴) ───────
-  private _legendTarget?: Component
-
-  /**
-   * Legend 컴포넌트 lookup. 우선:
-   *  1) state.legendTarget id 명시
-   *  2) scene 전체에서 type='legend' 첫 번째 (자동 발견)
-   */
-  get legendTarget(): Component | undefined {
-    if (this._legendTarget) return this._legendTarget
-    const id = this.state.legendTarget
-    if (id) {
-      const found = ((this as any).root)?.findById?.(id) as Component | undefined
-      if (found) {
-        this._legendTarget = found
-        ;(found as any).on?.('change', this._onLegendChanged, this)
-        return found
-      }
-    }
-    const visit = (node: any): Component | undefined => {
-      if (!node) return undefined
-      if (node.state?.type === 'legend') return node as Component
-      const children = node.components as Component[] | undefined
-      if (children) for (const c of children) {
-        const r = visit(c)
-        if (r) return r
-      }
-      return undefined
-    }
-    const found = visit((this as any).root)
-    if (found) {
-      this._legendTarget = found
-      ;(found as any).on?.('change', this._onLegendChanged, this)
-    }
-    return found
-  }
-
-  private _onLegendChanged = (): void => {
-    ;(this._realObject as any)?.update?.()
-  }
-
-  /**
-   * record 의 legend.field 값을 ranges 와 매칭해 색상 해석.
-   *  - range.value === recordValue (카테고리)
-   *  - range.min ≤ Number(v) < range.max (수치)
-   *  - 매칭 없으면 defaultColor
-   */
-  resolveLegendColor(record: any): string | undefined {
-    const legend = this.legendTarget
-    if (!legend) return undefined
-    const status: any = (legend as any).getState?.('status') ?? (legend.state as any)?.status
-    if (!status) return undefined
-    const field = status.field as string | undefined
-    const ranges = status.ranges as any[] | undefined
-    if (!field || !Array.isArray(ranges)) return undefined
-
-    const value = record?.[field]
-    if (value === undefined || value === null) return status.defaultColor
-
-    for (const range of ranges) {
-      if (!range) continue
-      if (range.value !== undefined) {
-        if (range.value === value) return range.color
-        continue
-      }
-      const num = Number(value)
-      if (!Number.isFinite(num)) continue
-      const min = range.min !== undefined && range.min !== '' ? Number(range.min) : undefined
-      const max = range.max !== undefined && range.max !== '' ? Number(range.max) : undefined
-      const minOk = min === undefined || num >= min
-      const maxOk = max === undefined || num < max
-      if (minOk && maxOk) return range.color
-    }
-    return status.defaultColor as string | undefined
-  }
+  // legendTarget / _onLegendChanged / resolveLegendColor — RecordStorage mixin 제공.
 
   buildRealObject(): RealObject | undefined {
     return new Stockpile3D(this)

package/src/storage-rack.ts

@@ -9,6 +9,7 @@ import {
   CellMap,
   CarrierHolder,
   Placeable,
+  RecordStorage,
   SlotTarget,
   componentBoundingBox,
   type AttachFrame,
@@ -166,7 +167,9 @@ function _nextCarrierRefid(): number {
  */
 @sceneComponent('storage-rack')
 export default class Rack
-  extends CellContainer(CarrierHolder(Placeable(ContainerAbstract)))
+  extends RecordStorage<{ cellId: string; [key: string]: any }>()(
+    CellContainer(CarrierHolder(Placeable(ContainerAbstract)))
+  )
   implements SlottedHolder
 {
   declare state: StorageRackState
@@ -175,6 +178,16 @@ export default class Rack
   static align: Alignment = 'bottom'
   static defaultDepth = (h: Heights) => h.ceiling - h.floor
 
+  // ── RecordStorage mixin hook overrides ────────────────────────────────
+  // record.cellId 가 slotId (mixin default 의 r.id 가 아닌 r.cellId).
+  _recordToSlotId(record: { cellId: string }): string {
+    return record.cellId ?? ''
+  }
+  // 3D rebuild 가 _realObject.rebuildStockMesh (mixin default 와 동일이지만 명시).
+  _rebuildVisual(): void {
+    ;(this._realObject as any)?.rebuildStockMesh?.()
+  }
+
   // Phase Auto-Nav (AN-PR-2) — Obstacle 자격.
   get isObstacle(): boolean {
     return (this.state as any)?.isObstacle !== false
@@ -322,10 +335,7 @@ export default class Rack
   //   - Place: await crane.place(c, destRack.slotTargetAt('B-0-0'))
   //            SlotTarget.receive → destRack.receiveAt → c dispose + record push
 
-  /** state.data 의 record 목록 (읽기 전용 뷰). */
-  get records(): ReadonlyArray<{ cellId: string; [key: string]: any }> {
-    return (this.state.data as any) ?? []
-  }
+  // `records` getter — RecordStorage mixin 제공.
 
   /**
    * 1-based (bay, row, level) → 0-based cellId 문자열.
@@ -422,7 +432,7 @@ export default class Rack
   /** cellId 에 carrier 가 있는가 — child carrier 또는 state.data record 어느 쪽이든. */
   hasCarrierAt(cellId: string): boolean {
     if (this._carrierChildAt(cellId)) return true
-    return this.records.some(r => r.cellId === cellId)
+    return this.records.some((r: any) => r.cellId === cellId)
   }
 
   /** cellId 매칭되는 rack 의 직접 자식 carrier (operation archetype). */
@@ -520,25 +530,8 @@ export default class Rack
     return carrier
   }
 
-  /**
-   * State.data 의 *internal* 갱신 — Plan A 의 obtainCarrier / receiveAt 가 사용.
-   * `setState` 와 달리 *'change' 이벤트 / onchangeData / mapping cascade 를 우회*.
-   *
-   * 이유: mapping 시스템이 state.data 변경 시 *자동으로 script fire*. Plan A 의
-   * setState 가 그 cascade 를 트리거하면 사용자 script 가 *재귀적으로 자기 자신을 호출*
-   * 하는 회귀 (board 의 의도된 binding 일 수도, 우연일 수도) 발생.
-   *
-   * 대신 *직접 _state 갱신 + rebuildStockMesh 직접 호출* — 시각화는 갱신되지만 외부
-   * mapping 은 fire 안 됨. External (WMS / application setState) 호출은 그대로 setState
-   * 거치므로 그쪽 mapping 은 정상 동작.
-   */
-  private _setDataSilently(newData: any[]): void {
-    const self = this as any
-    if (!self._state) self._state = {}
-    self._state.data = newData
-    self._cachedState = null   // state getter 가 다음 read 때 fresh build
-    ;(this._realObject as any)?.rebuildStockMesh?.()
-  }
+  // _setDataSilently — RecordStorage mixin 제공 (_rebuildVisual hook 통해
+  // rebuildStockMesh 호출). 동등 동작 + cachedState invalidate.
 
   /**
    * cell 이 carrier 를 받을 수 있는가.
@@ -815,88 +808,7 @@ export default class Rack
     ;(this._realObject as any)?.rebuildStockMesh?.()
   }
 
-  // ── Legend — record 의 field 값 → 색상 매핑 ────────────────────────────────
-
-  private _legendTarget?: Component
-
-  /**
-   * Legend 컴포넌트 lookup. 우선순위:
-   *  1) state.legendTarget id 명시
-   *  2) scene 전체에서 `type='legend'` 첫 번째 컴포넌트 (자동 발견)
-   */
-  get legendTarget(): Component | undefined {
-    if (this._legendTarget) return this._legendTarget
-
-    const id = this.state.legendTarget
-    if (id) {
-      const found = (this.root as any)?.findById?.(id) as Component | undefined
-      if (found) {
-        this._legendTarget = found
-        ;(found as any).on?.('change', this._onLegendChanged, this)
-        return found
-      }
-    }
-
-    // scene-wide auto-discovery
-    const visit = (node: any): Component | undefined => {
-      if (!node) return undefined
-      if (node.state?.type === 'legend') return node as Component
-      const children = node.components as Component[] | undefined
-      if (children) {
-        for (const c of children) {
-          const r = visit(c)
-          if (r) return r
-        }
-      }
-      return undefined
-    }
-    const found = visit(this.root)
-    if (found) {
-      this._legendTarget = found
-      ;(found as any).on?.('change', this._onLegendChanged, this)
-    }
-    return found
-  }
-
-  private _onLegendChanged = (): void => {
-    ;(this._realObject as any)?.rebuildStockMesh?.()
-  }
-
-  /**
-   * record 의 legend.field 값을 ranges 와 매칭해 색상 해석.
-   *   - `range.value === recordValue` (카테고리 일치)
-   *   - `range.min ≤ Number(v) < range.max` (수치 범위)
-   *   - 매칭 없으면 `defaultColor` 또는 undefined
-   */
-  resolveLegendColor(record: any): string | undefined {
-    const legend = this.legendTarget
-    if (!legend) return undefined
-    const status: any = (legend as any).getState?.('status') ?? (legend.state as any)?.status
-    if (!status) return undefined
-
-    const field = status.field as string | undefined
-    const ranges = status.ranges as any[] | undefined
-    if (!field || !Array.isArray(ranges)) return undefined
-
-    const value = record?.[field]
-    if (value === undefined || value === null) return status.defaultColor
-
-    for (const range of ranges) {
-      if (!range) continue
-      if (range.value !== undefined) {
-        if (range.value === value) return range.color
-        continue
-      }
-      const num = Number(value)
-      if (!Number.isFinite(num)) continue
-      const min = range.min !== undefined && range.min !== '' ? Number(range.min) : undefined
-      const max = range.max !== undefined && range.max !== '' ? Number(range.max) : undefined
-      const minOk = min === undefined || num >= min
-      const maxOk = max === undefined || num < max
-      if (minOk && maxOk) return range.color
-    }
-    return status.defaultColor as string | undefined
-  }
+  // legendTarget / _onLegendChanged / resolveLegendColor — RecordStorage mixin 제공.
 
   // ── Click event — rack-cell-click 발사 ────────────────────────────────────
   //
@@ -964,30 +876,10 @@ export default class Rack
     this.trigger('rack-cell-click', payload)
 
     // Popup 호출 — 일반 mechanism (Popup 컴포넌트) 활용, anchor 만 클릭된 cell 로 override.
-    this._invokePopup(cellId, record)
+    if (cellId) this._invokePopup(cellId, record ?? { cellId })
   }
 
-  /**
-   * state.popupRef 가 가리키는 Popup 컴포넌트를 invoke. anchor 를 SlotTarget 으로
-   * 지정 — SlotTarget._realObject.object3d 가 cellId 위치의 anchor object3d 를
-   * 가리켜 tether / projectToScreen 정확.
-   *
-   * - popupRef 미설정 → no-op (event 만 발사된 상태로 남음)
-   * - 다른 cell 클릭 시 popup 이 새 anchor 로 "이동" (Popup 의 board 등 설정 유지)
-   * - frame/empty 영역 클릭 시 호출 안 됨 → popup 그대로 유지
-   * - 명시적 close 버튼은 popup 자체의 closable 옵션이 처리
-   */
-  private _invokePopup(cellId: string | undefined, record: any): void {
-    const popupRefId = this.state.popupRef
-    if (!popupRefId || !cellId) return
-    const popupComp: any = (this.root as any)?.findById?.(popupRefId)
-    if (!popupComp || typeof popupComp.openPopup !== 'function') {
-      console.warn(`[storage-rack] popupRef="${popupRefId}" 가 가리키는 컴포넌트 없거나 openPopup 미지원`)
-      return
-    }
-    const anchor = this.slotTargetAt(cellId)
-    popupComp.openPopup(record ?? { cellId }, { anchor })
-  }
+  // _invokePopup — RecordStorage mixin 제공 (cellId=slotId, record=payload).
 
   /**
    * 클릭 시 framework 의 mouse NDC (이미 InteractionManager 가 set 한 상태) 를 재사용해
@@ -1087,6 +979,46 @@ export default class Rack
     return `${bayIdx}-${rowIdx}-${levelIdx}`
   }
 
+  /**
+   * Cell-precise approach point — mover 가 *_cell 정면 외부 stand-off_* 까지만.
+   *
+   * cellId format: `${bay - 1}-${row - 1}-${level - 1}` (0-based).
+   *
+   * **사용자 의도**: rack 은 *_전면_* 만 포크질 가능. front face = state.top 쪽
+   * (작은 z, 3D 의 -Z forward). back face 사용 금지 — forklift 가 rack 후면에
+   * 정차하는 동작은 잘못. navigation 의 obstacle avoidance 가 rack 우회 path 계산.
+   *
+   * forkLen — fork blade tip 부터 mover center 까지 거리. mover 가 그 거리만큼
+   * cell face 앞에서 정차 → 정확히 fork blade 가 cell face 정렬.
+   *
+   * (rotation 지원 V11 — 현재 axis-aligned rack 만, facing default = top.)
+   */
+  slotApproachWorldPosition(
+    slotId: string,
+    _fromPos?: { x: number; y: number; z: number }
+  ): { x: number; y: number; z: number } {
+    const parts = slotId.split('-')
+    const s: any = this.state
+    const left = s?.left ?? 0
+    const top = s?.top ?? 0
+    const width = s?.width ?? 0
+
+    if (parts.length !== 3) {
+      // fallback — front face center
+      return { x: left + width / 2, y: 0, z: top - (s.depth ?? 100) * 0.5 }
+    }
+    const col = Number(parts[0])
+    const bays = Math.max(1, Math.floor((s.bays as number) ?? 5))
+
+    const cellX = left + (col + 0.5) * (width / bays)
+
+    // fork 진입 거리 — rack.depth 의 절반 (mover 정차 점이 fork blade 가 cell 정면에
+    // 정렬되는 거리). _fromPos 무시 — *_항상 front face_* (사용자 의도: 전면만 포크질).
+    const forkLen = (s.depth ?? 100) * 0.5
+
+    return { x: cellX, y: 0, z: top - forkLen }
+  }
+
   // ── 3D ───────────────────────────────────────────────────────────────────
 
   buildRealObject(): RealObject | undefined {

package/translations/en.json

@@ -10,6 +10,7 @@
   "component.mobile-storage-rack": "mobile storage rack",
   "component.spot": "spot",
   "component.generic-container": "container",
+  "label.data": "Data (JSON)",
   "label.tracking-id": "tracking id",
   "label.material": "material",
   "label.depth": "depth",
@@ -76,5 +77,10 @@
   "label.cell-width": "Cell Width",
   "label.cell-height": "Cell Height",
   "component.picking-station": "Picking Station",
-  "label.processing-time-ms": "Processing Time (ms)"
+  "label.processing-time-ms": "Processing Time (ms)",
+  "component.container": "container",
+  "component.wood pallet": "wood pallet",
+  "component.plastic pallet": "plastic pallet",
+  "component.wood box": "wood box",
+  "component.plastic box": "plastic box"
 }

package/translations/ja.json

@@ -10,6 +10,7 @@
   "component.mobile-storage-rack": "移動式ラック",
   "component.spot": "スポット",
   "component.generic-container": "コンテナ",
+  "label.data": "データ (JSON)",
   "label.tracking-id": "追跡ID",
   "label.material": "材質",
   "label.depth": "深さ",
@@ -76,5 +77,10 @@
   "label.cell-width": "セル幅",
   "label.cell-height": "セル高さ",
   "component.picking-station": "ピッキングステーション",
-  "label.processing-time-ms": "処理時間 (ms)"
+  "label.processing-time-ms": "処理時間 (ms)",
+  "component.container": "コンテナ",
+  "component.wood pallet": "木製パレット",
+  "component.plastic pallet": "プラスチックパレット",
+  "component.wood box": "木製ボックス",
+  "component.plastic box": "プラスチックボックス"
 }

package/translations/ko.json

@@ -10,6 +10,7 @@
   "component.mobile-storage-rack": "이동형 저장 랙",
   "component.spot": "스팟",
   "component.generic-container": "컨테이너",
+  "label.data": "데이터 (JSON)",
   "label.tracking-id": "추적 ID",
   "label.material": "재질",
   "label.depth": "깊이",
@@ -76,5 +77,10 @@
   "label.cell-width": "셀 너비",
   "label.cell-height": "셀 높이",
   "component.picking-station": "피킹 스테이션",
-  "label.processing-time-ms": "처리 시간 (ms)"
+  "label.processing-time-ms": "처리 시간 (ms)",
+  "component.container": "컨테이너",
+  "component.wood pallet": "목재 팔레트",
+  "component.plastic pallet": "플라스틱 팔레트",
+  "component.wood box": "목재 박스",
+  "component.plastic box": "플라스틱 박스"
 }

package/translations/ms.json

@@ -10,6 +10,7 @@
   "component.mobile-storage-rack": "rak mudah alih",
   "component.spot": "titik",
   "component.generic-container": "bekas",
+  "label.data": "Data (JSON)",
   "label.tracking-id": "ID penjejakan",
   "label.material": "bahan",
   "label.depth": "kedalaman",
@@ -76,5 +77,10 @@
   "label.cell-width": "Lebar Sel",
   "label.cell-height": "Tinggi Sel",
   "component.picking-station": "Stesen Pengambilan",
-  "label.processing-time-ms": "Masa Proses (ms)"
+  "label.processing-time-ms": "Masa Proses (ms)",
+  "component.container": "kontena",
+  "component.wood pallet": "palet kayu",
+  "component.plastic pallet": "palet plastik",
+  "component.wood box": "kotak kayu",
+  "component.plastic box": "kotak plastik"
 }

package/translations/zh.json

@@ -10,6 +10,7 @@
   "component.mobile-storage-rack": "移动货架",
   "component.spot": "位点",
   "component.generic-container": "容器",
+  "label.data": "数据 (JSON)",
   "label.tracking-id": "追踪ID",
   "label.material": "材质",
   "label.depth": "深度",
@@ -76,5 +77,10 @@
   "label.cell-width": "单元宽度",
   "label.cell-height": "单元高度",
   "component.picking-station": "拣选工作站",
-  "label.processing-time-ms": "处理时间 (ms)"
+  "label.processing-time-ms": "处理时间 (ms)",
+  "component.container": "容器",
+  "component.wood pallet": "木质托盘",
+  "component.plastic pallet": "塑料托盘",
+  "component.wood box": "木质箱",
+  "component.plastic box": "塑料箱"
 }