@operato/scene-storage 10.0.0-beta.48 → 10.0.0-beta.53

package/src/picking-station.ts

@@ -0,0 +1,220 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ *
+ * PickingStation — 사람(또는 자동화) 작업 위치. carrier 가 도착하면 *_processingTimeMs_*
+ * 동안 머문 뒤 status='idle' 로 자동 전환되어 다음 mover 가 가져갈 수 있다.
+ *
+ * 단일 slot SlottedHolder (Spot 비슷) + 처리 시간/상태 + popupRef + click raycast.
+ * 3D 는 pad(영역) + 작업대(가운데 box) — picking/QC 작업 자리의 인지성을 위해.
+ */
+
+import * as THREE from 'three'
+import { Component, ComponentNature, ContainerAbstract, RealObject, sceneComponent } from '@hatiolab/things-scene'
+import type { State, Material3D } from '@hatiolab/things-scene'
+import {
+  CarrierHolder,
+  Placeable,
+  SingleSlotHolder,
+  type AttachFrame,
+  type Alignment,
+  type Heights,
+  type PlacementArchetype,
+  type ProcessStep
+} from '@operato/scene-base'
+
+import { PickingStation3D } from './picking-station-3d.js'
+
+export type PickingStationStatus = 'idle' | 'processing' | 'busy'
+
+export interface PickingStationState extends State {
+  /** carrier 가 머무는 처리 시간 (ms). 0/미설정이면 즉시 idle 유지. */
+  processingTimeMs?: number
+  /** 현재 상태 (자동). */
+  status?: PickingStationStatus
+  /** click 시 invoke 할 Popup 컴포넌트 id. */
+  popupRef?: string
+  material3d?: Material3D
+}
+
+const SLOT_ID = 'station'
+
+const NATURE: ComponentNature = {
+  mutable: false,
+  resizable: true,
+  rotatable: true,
+  properties: [
+    { type: 'number', label: 'processing-time-ms', name: 'processingTimeMs' },
+    { type: 'select', label: 'status', name: 'status',
+      property: { options: ['idle', 'processing', 'busy'] } },
+    { type: 'id-input', label: 'popup-ref', name: 'popupRef',
+      property: { component: 'popup' } }
+  ],
+  help: 'scene/component/picking-station'
+}
+
+@sceneComponent('picking-station')
+export default class PickingStation
+  extends SingleSlotHolder()(CarrierHolder(Placeable(ContainerAbstract)))
+  implements ProcessStep
+{
+  declare state: PickingStationState
+  declare _realObject?: PickingStation3D
+
+  static placement: PlacementArchetype = 'floor'
+  static align: Alignment = 'bottom'
+  static defaultDepth = (h: Heights) => h.operation - h.floor
+
+  get nature(): ComponentNature { return NATURE }
+  get anchors() { return [] }
+
+  // SingleSlotHolder hook overrides ───────────────────────────────────────────
+  _singleSlotId() { return SLOT_ID }
+
+  /**
+   * SlottedHolder duck (slotIds / hasCarrierAt / canReceiveAt / occupiedSlotIds
+   * / emptySlotIds / obtainCarrier / receiveAt / accept / receive / slotTargetAt
+   * / getSlotAttachObject3d) — SingleSlotHolder mixin 제공.
+   *
+   * receiveAt 후 부가 dwell 동작은 `_onCarrierReceived` hook 으로 위임.
+   */
+  _onCarrierReceived(_carrier: Component, _options?: any) {
+    const procMs = this.state.processingTimeMs ?? 0
+    if (procMs <= 0) return
+    this.setState({ status: 'processing' as PickingStationStatus })
+    setTimeout(() => {
+      if ((this.state.status as PickingStationStatus) === 'processing') {
+        this.setState({ status: 'idle' as PickingStationStatus })
+      }
+    }, procMs)
+  }
+
+  // Phase ZT-V PR-6 ProcessStep ─────────────────────────────────────────────
+  readonly isProcessStep = true as const
+  get processingTimeMs() { return this.state.processingTimeMs ?? 0 }
+
+  /** carrier 를 작업대(table) 상단에 안착. */
+  attachPointFor(carrier: Component): AttachFrame | null {
+    const ro = this._realObject
+    const frame = ro?.getAttachFrame?.()
+    if (!frame) return null
+    const carrierDepth = resolveDepth(carrier)
+    return { attach: frame, localPosition: { x: 0, y: carrierDepth / 2, z: 0 } }
+  }
+
+  // ── 2D render ───────────────────────────────────────────────
+  render(ctx: CanvasRenderingContext2D) {
+    const { left = 0, top = 0, width = 100, height = 100 } = this.state
+    const fillStyle = (this.state.fillStyle as string) || '#5a8ab8'
+    const strokeStyle = (this.state.strokeStyle as string) || '#3d6a8f'
+    const status = (this.state.status ?? 'idle') as PickingStationStatus
+
+    // pad
+    ctx.save()
+    ctx.fillStyle = fillStyle
+    ctx.globalAlpha = 0.15
+    ctx.fillRect(left, top, width, height)
+    ctx.restore()
+
+    // outline
+    ctx.save()
+    ctx.strokeStyle = strokeStyle
+    ctx.lineWidth = 1.5
+    ctx.strokeRect(left + 0.75, top + 0.75, width - 1.5, height - 1.5)
+    ctx.restore()
+
+    // 작업대 (가운데 작은 사각)
+    const tw = width * 0.55, th = height * 0.45
+    const tx = left + (width - tw) / 2
+    const ty = top + (height - th) / 2
+    ctx.save()
+    ctx.fillStyle = strokeStyle
+    ctx.globalAlpha = 0.35
+    ctx.fillRect(tx, ty, tw, th)
+    ctx.restore()
+
+    // 상태
+    ctx.save()
+    const fontSize = Math.min(width, height) * 0.16
+    ctx.fillStyle = '#222'
+    ctx.font = `bold ${fontSize}px sans-serif`
+    ctx.textAlign = 'center'
+    ctx.textBaseline = 'middle'
+    ctx.fillText(status.toUpperCase(), left + width / 2, top + height / 2)
+    ctx.restore()
+  }
+
+  // ── Popup + click ────────────────────────────────────────────
+  get eventMap() {
+    return { '(self)': { '(self)': { click: this._onStationClick } } }
+  }
+
+  private _onStationClick = (mouseEvent: MouseEvent) => {
+    if (!(this as any).app?.isViewMode) return
+    const hit = this._raycastStationHit(mouseEvent)
+    if (!hit) return
+    this._invokePopup()
+  }
+
+  private _invokePopup(): void {
+    const popupRefId = this.state.popupRef
+    if (!popupRefId) return
+    const popupComp: any = (this as any).root?.findById?.(popupRefId)
+    if (!popupComp || typeof popupComp.openPopup !== 'function') return
+    const anchor = this.slotTargetAt(SLOT_ID)
+    const carrier = this.obtainCarrier(SLOT_ID)
+    popupComp.openPopup({
+      componentId: (this.state as any).id,
+      status: this.state.status ?? 'idle',
+      processingTimeMs: this.state.processingTimeMs,
+      currentCarrierId: (carrier as any)?.state?.id ?? null
+    }, { anchor })
+  }
+
+  private _raycastStationHit(mouseEvent: MouseEvent): THREE.Intersection | undefined {
+    const ro: any = (this as any)._realObject
+    if (!ro?.object3d) return undefined
+    const tc: any = ro.threeContainer
+    if (!tc) return undefined
+    const cap: any = tc._threeCapability ?? tc._capability
+    let intersects: THREE.Intersection[] | undefined
+    if (cap?.getObjectsByRaycast) intersects = cap.getObjectsByRaycast() as THREE.Intersection[] | undefined
+    if (!intersects || intersects.length === 0) {
+      const scene = tc.scene3d as THREE.Scene | undefined
+      const renderer = tc.renderer3d as THREE.WebGLRenderer | undefined
+      const camera =
+        (tc.activeCamera3d as THREE.Camera | undefined) ??
+        (cap?.activeCamera as THREE.Camera | undefined) ??
+        (cap?.camera as THREE.Camera | undefined)
+      const canvas = renderer?.domElement
+      if (!scene || !canvas || !camera) return undefined
+      const rect = canvas.getBoundingClientRect()
+      if (rect.width === 0 || rect.height === 0) return undefined
+      const ndc = new THREE.Vector2(
+        ((mouseEvent.clientX - rect.left) / rect.width) * 2 - 1,
+        -((mouseEvent.clientY - rect.top) / rect.height) * 2 + 1
+      )
+      const raycaster = new THREE.Raycaster()
+      raycaster.setFromCamera(ndc, camera)
+      intersects = raycaster.intersectObjects(scene.children, true)
+    }
+    if (!intersects || intersects.length === 0) return undefined
+    const closest = intersects[0]
+    let obj: THREE.Object3D | null = closest.object
+    while (obj) {
+      if (obj.userData?.context === ro) return closest
+      obj = obj.parent
+    }
+    return undefined
+  }
+
+  buildRealObject(): RealObject | undefined {
+    return new PickingStation3D(this)
+  }
+}
+
+function resolveDepth(c: Component): number {
+  const eff = (c as any)._realObject?.effectiveDepth
+  if (typeof eff === 'number' && Number.isFinite(eff)) return eff
+  const d = (c as any)?.state?.depth
+  return typeof d === 'number' && Number.isFinite(d) ? d : 0
+}

package/src/rack-capability.ts

@@ -0,0 +1,26 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ *
+ * Rack 적재 mover 능력 판정 — *_순수 로직_* (things-scene 무관). storage-rack 의
+ * canAcceptFromMover 가 위임. mocha 환경에서 StorageRack 직접 import 불가하므로
+ * 판정 로직만 분리해 단위 검증.
+ */
+
+/**
+ * rack 이 *_이 mover 의 toolType_* 을 선반 적재용으로 수용하는가.
+ *
+ * rack 선반 적재는 높이 도달 mover (crane / stacker / forklift) 의 몫. 평탄 데크
+ * 차량(agv-deck)은 바닥 운반 전용 — 선반 직접 적재 불가 → 거부. 거부된 mover 는
+ * transfer planner 가 자동으로 in-port 경유(환승)를 택하게 만든다.
+ *
+ * @param moverToolType  적재하려는 mover 의 toolType (undefined 면 능력 미상 → 허용)
+ * @param blockedTools   거부 toolType 목록 (default ['agv-deck'])
+ */
+export function rackAcceptsMoverTool(
+  moverToolType: string | undefined | null,
+  blockedTools: readonly string[] = ['agv-deck']
+): boolean {
+  if (moverToolType == null) return true
+  if (!Array.isArray(blockedTools)) return true
+  return !blockedTools.includes(moverToolType)
+}

package/src/rack-grid.ts

@@ -38,7 +38,9 @@ import * as THREE from 'three'
 import {
   CarrierHolder,
   Placeable,
+  RecordStorage,
   SlotTarget,
+  componentBoundingBox,
   type AttachFrame,
   type Alignment,
   type Heights,
@@ -267,25 +269,33 @@ export interface RackGridState extends State {
 
 @sceneComponent('rack-grid')
 export default class RackGrid
-  extends CarrierHolder(Placeable(ContainerAbstract))
+  extends RecordStorage<{ cellId: string; [key: string]: any }>()(
+    CarrierHolder(Placeable(ContainerAbstract))
+  )
   implements SlottedHolder
 {
   declare state: RackGridState
 
+  // RecordStorage mixin hook overrides.
+  // record.cellId 가 slotId (3-segment '{col}-{row}-{shelf}' format).
+  _recordToSlotId(record: { cellId: string }): string {
+    return record.cellId ?? ''
+  }
+  // 3D rebuild — rebuildStockMesh 우선, 없으면 mixin default.
+  _rebuildVisual(): void {
+    const ro = (this as any)._realObject
+    if (ro?.rebuildStockMesh) ro.rebuildStockMesh()
+    else if (ro?.update) ro.update()
+  }
+
   // Phase Auto-Nav (AN-PR-2) — Obstacle 자격. AMR / mover 의 자동 path planning
   // 시 회피 대상. `state.isObstacle` 명시 false 시 override (예외 처리).
   get isObstacle(): boolean {
     return (this.state as any)?.isObstacle !== false
   }
   obstacleBoundingBox(): { left: number; top: number; width: number; height: number; y?: number; zHeight?: number } | null {
-    const s: any = this.state
-    if (typeof s?.left !== 'number') return null
-    return {
-      left: s.left, top: s.top,
-      width: s.width, height: s.height,
-      y: typeof s.zPos === 'number' ? s.zPos : 0,
-      zHeight: typeof s.depth === 'number' ? s.depth : 0
-    }
+    // scene-base 의 componentBoundingBox 위임 — rotation 적용된 AABB.
+    return componentBoundingBox(this)
   }
 
   static placement: PlacementArchetype = 'floor'
@@ -422,63 +432,8 @@ export default class RackGrid
     ;(this._realObject as any)?.rebuildStockMesh?.()
   }
 
-  /** state.data 의 records — Plan A 의 stock 보관소. */
-  get records(): Array<{ cellId: string; [key: string]: any }> {
-    return (this.state.data as any) ?? []
-  }
-
-  // ── Legend integration ──────────────────────────────────
-
-  private _legendTarget?: Component
+  // records / legendTarget / _onLegendChanged / resolveLegendColor — RecordStorage mixin 제공.
 
-  /**
-   * 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
-      }
-    }
-
-    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
-   */
   // ── View-mode click → rack-grid-cell-click event + popup ──
 
   get eventMap() {
@@ -521,24 +476,13 @@ export default class RackGrid
 
     const payload = { cellId, record, hitPoint: hit.point, instanceId, isStock }
     this.trigger('rack-grid-cell-click', payload)
-    this._invokePopup(cellId, record)
+    if (cellId) this._invokePopup(cellId, record ?? { cellId })
 
     // popup 외부 click 으로 인식되어 자동 close 되는 회귀 차단
     mouseEvent.stopPropagation?.()
   }
 
-  /** state.popupRef Popup 컴포넌트 invoke. anchor = 클릭된 cell 의 SlotTarget. */
-  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(`[rack-grid] popupRef="${popupRefId}" 가 가리키는 컴포넌트 없거나 openPopup 미지원`)
-      return
-    }
-    const anchor = this.slotTargetAt(cellId)
-    popupComp.openPopup(record ?? { cellId }, { anchor })
-  }
+  // _invokePopup — RecordStorage mixin 제공 (signature 동일: slotId=cellId, payload=record).
 
   /** raycast → 우리 RackGrid 의 어떤 mesh 가 closest hit 인지. */
   private _raycastHit(mouseEvent: MouseEvent): THREE.Intersection | undefined {
@@ -617,35 +561,7 @@ export default class RackGrid
     return `${col}-${row}-${shelf}`
   }
 
-  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
-  }
+  // resolveLegendColor — RecordStorage mixin 제공.
 
   /**
    * 새 (rows × columns) 에 맞춰 children 재구성. rack-table.buildCells 정확 클론.
@@ -1256,7 +1172,7 @@ export default class RackGrid
     const cellId = this._resolveToCellId(slotIdOrLocation)
     if (!cellId) return false
     if (this._carrierChildAt(cellId)) return true
-    return this.records.some(r => r.cellId === cellId)
+    return this.records.some((r: any) => r.cellId === cellId)
   }
 
   /**

package/src/spot.ts

@@ -34,6 +34,7 @@ import type { State, Material3D } from '@hatiolab/things-scene'
 import {
   CarrierHolder,
   Placeable,
+  SingleSlotHolder,
   type AttachFrame,
   type Alignment,
   type Heights,
@@ -68,7 +69,11 @@ const NATURE: ComponentNature = {
 // which forces `isHTMLElement(): true` and trips the 3D pipeline's
 // addObject DOM-skip gate. Spot is purely 3D.
 @sceneComponent('spot')
-export default class Spot extends CarrierHolder(Placeable(ContainerAbstract)) {
+export default class Spot extends SingleSlotHolder()(
+  CarrierHolder(Placeable(ContainerAbstract))
+) {
+  // SingleSlotHolder hook override — Spot 의 slot id 'pad'.
+  _singleSlotId() { return SPOT_SLOT_ID }
   declare state: SpotState
   declare _realObject?: Spot3D
 
@@ -167,8 +172,17 @@ export default class Spot extends CarrierHolder(Placeable(ContainerAbstract)) {
       localPosition: { x: 0, y: carrierDepth / 2, z: 0 }
     }
   }
+
+  // SlottedHolder duck (slotIds / hasCarrierAt / canReceiveAt / occupiedSlotIds /
+  // emptySlotIds / obtainCarrier / receiveAt / accept / receive / slotTargetAt /
+  // getSlotAttachObject3d) — SingleSlotHolder mixin 제공.
+  // virtual location handoff buffer 동작: receiveAt 가 reparent (components +
+  // 3D) 로 carrier 를 자식으로 유지 → 다음 mover 가 obtainCarrier 로 승계.
 }
 
+/** Spot 의 유일 virtual slot id. */
+const SPOT_SLOT_ID = 'pad'
+
 function resolveDepth(c: Component): number {
   const eff = (c as any)._realObject?.effectiveDepth
   if (typeof eff === 'number' && Number.isFinite(eff)) return eff