@operato/scene-storage 10.0.0-beta.44 → 10.0.0-beta.46

package/test/test-rack-grid-3d-attach-real.ts

@@ -0,0 +1,375 @@
+/*
+ * RackGrid Plan A 의 *진짜 Three.js* attach/detach 검증.
+ *
+ * 동등 본 test-rack-3d-attach-real.ts 와 *동일한 검증 패턴* — RackGrid 가
+ * StorageRack 의 handoff contract 와 *동일한 3D scene graph 흐름* 을 보이는지.
+ *
+ * 추가 검증 — **handoff follow**:
+ *   crane 의 fork 가 움직이면 carrier 의 world position 이 자동 따라가야 함.
+ *   사용자 보고 *crane 이 carrier 를 못 담음 / fork 빈 포크짓* 의 회귀 방지.
+ *
+ * 시나리오:
+ *   1. obtainCarrier 후 carrier.obj3d.parent === rack-grid-anchor
+ *   2. crane.receive 후 carrier.obj3d.parent === crane fork
+ *   3. fork.position 변경 시 carrier.world 가 fork.world 따라감
+ *   4. receiveAt 후 carrier 완전 detach + record push
+ *   5. ghost 검증 — 반복 pickAndPlace 후 anchor / fork 모두 깨끗
+ */
+
+import 'should'
+import * as THREE from 'three'
+
+// ── Carrier 모사 (Parcel3D 식 Group + mesh) ────────────────────────────────
+
+class RealCarrier {
+  state: any
+  parent: any = null
+  _realObject: { object3d: THREE.Object3D; placement?: any }
+  _disposed = false
+
+  constructor(state: any) {
+    this.state = state
+    const group = new THREE.Group()
+    group.name = `carrier-${state.cellId ?? '?'}-group`
+    const bodyMesh = new THREE.Mesh(
+      new THREE.BoxGeometry(50, 50, 50),
+      new THREE.MeshBasicMaterial({ color: 0xc8a878 })
+    )
+    bodyMesh.name = 'carrier-body'
+    group.add(bodyMesh)
+    const self = this
+    this._realObject = {
+      object3d: group,
+      // setTransientPlacement 모사 — 실제 RealObject 와 동등
+      setTransientPlacement(p: any) { self._realObject.placement = p }
+    } as any
+  }
+
+  applyHolderAttachPoint(): void {
+    const p: any = this.parent
+    if (!p?.attachPointFor) return
+    const point = p.attachPointFor(this)
+    if (!point?.attach) return
+    point.attach.attach(this._realObject.object3d)
+    if (point.localPosition) {
+      this._realObject.object3d.position.set(
+        point.localPosition.x, point.localPosition.y, point.localPosition.z
+      )
+    }
+  }
+
+  dispose(): void {
+    this._disposed = true
+    for (const child of [...this._realObject.object3d.children]) {
+      const mesh = child as THREE.Mesh
+      mesh.geometry?.dispose?.()
+      const mats = Array.isArray(mesh.material) ? mesh.material : (mesh.material ? [mesh.material] : [])
+      for (const m of mats) m?.dispose?.()
+    }
+    this._realObject.object3d.clear()
+  }
+}
+
+// ── RackGrid 모사 — *현재 RackGrid.obtainCarrier 의 실제 코드 흐름* 그대로 ──
+
+class RackGridMock {
+  state: any = { data: [] }
+  components: any[] = []
+  rootObject3d = new THREE.Group()
+  _attachAnchorBySlot = new Map<string, THREE.Object3D>()
+
+  constructor() { this.rootObject3d.name = 'rack-grid-root' }
+
+  // RackGrid.getSlotAttachObject3d 본문 모사 (위치 setting 제외 — anchor 자체만)
+  getSlotAttachObject3d(cellId: string): THREE.Object3D {
+    let obj = this._attachAnchorBySlot.get(cellId)
+    if (!obj) {
+      obj = new THREE.Object3D()
+      obj.name = `rack-grid-anchor:${cellId}`
+      this.rootObject3d.add(obj)
+      this._attachAnchorBySlot.set(cellId, obj)
+    }
+    return obj
+  }
+
+  // RackGrid.attachPointFor (mixin override)
+  attachPointFor(carrier: any) {
+    const cellId = carrier.state?.cellId
+    if (cellId) {
+      const obj = this.getSlotAttachObject3d(cellId)
+      if (obj) return { attach: obj, localPosition: { x: 0, y: 0, z: 0 } }
+    }
+    return { attach: this.rootObject3d, localPosition: { x: 0, y: 0, z: 0 } }
+  }
+
+  addComponent(c: any): void { c.parent = this; this.components.push(c) }
+  removeComponent(c: any): void {
+    const i = this.components.indexOf(c)
+    if (i >= 0) this.components.splice(i, 1)
+    c.parent = null
+  }
+
+  // RackGrid.obtainCarrier 의 *현 코드* 그대로 모사 (manual setTransientPlacement
+  // + manual anchor.add 포함)
+  obtainCarrier(cellId: string): RealCarrier | null {
+    const i = this.state.data.findIndex((r: any) => r.cellId === cellId)
+    if (i === -1) return null
+    const record = this.state.data[i]
+    const c = new RealCarrier({ ...record, cellId })
+    this.addComponent(c)
+    c.applyHolderAttachPoint()
+
+    // 현재 코드의 manual block
+    ;(c._realObject as any).setTransientPlacement?.({ policy: 'carried' })
+    const anchor = this.getSlotAttachObject3d(cellId)
+    const carrierObj3d = c._realObject.object3d
+    if (anchor && carrierObj3d) {
+      anchor.add(carrierObj3d)
+      carrierObj3d.position.set(0, 0, 0)
+      carrierObj3d.updateMatrixWorld(true)
+    }
+
+    this.state.data = this.state.data.filter((_: any, j: number) => j !== i)
+    return c
+  }
+
+  async receiveAt(cellId: string, carrier: RealCarrier): Promise<void> {
+    const p = carrier.parent
+    if (p?.removeComponent) p.removeComponent(carrier)
+    const obj = carrier._realObject?.object3d
+    if (obj?.parent?.remove) obj.parent.remove(obj)
+    carrier.dispose()
+    const rec: any = { cellId, type: carrier.state.type ?? 'parcel' }
+    for (const k of Object.keys(carrier.state)) {
+      if (['id', 'left', 'top', 'zPos', 'cellId'].includes(k)) continue
+      rec[k] = carrier.state[k]
+    }
+    this.state.data.push(rec)
+  }
+}
+
+// ── Crane 모사 — trolley → lift → fork 의 nested group 구조 ────────────────
+// crane-3d.ts 의 getCarriageFrame 의 fallback chain (_forkGroup → _carriageLiftGroup
+// → _trolleyGroup → root) 의 *_forkGroup* 사용 가정.
+
+class CraneMock {
+  components: any[] = []
+  rootObject3d = new THREE.Group()
+  trolleyGroup = new THREE.Group()
+  carriageLiftGroup = new THREE.Group()
+  forkGroup = new THREE.Group()
+
+  constructor() {
+    this.rootObject3d.name = 'crane-root'
+    this.trolleyGroup.name = 'trolley'
+    this.carriageLiftGroup.name = 'lift'
+    this.forkGroup.name = 'fork'
+    this.rootObject3d.add(this.trolleyGroup)
+    this.trolleyGroup.add(this.carriageLiftGroup)
+    this.carriageLiftGroup.add(this.forkGroup)
+  }
+
+  // crane.attachPointFor 본문 모사 — getCarriageFrame 의 _forkGroup
+  attachPointFor(_carrier: any) {
+    return {
+      attach: this.forkGroup,
+      localPosition: { x: 0, y: 0, z: 0 },
+      carryPolicy: 'follow-holder'
+    }
+  }
+
+  addComponent(c: any): void { c.parent = this; this.components.push(c) }
+  removeComponent(c: any): void {
+    const i = this.components.indexOf(c)
+    if (i >= 0) this.components.splice(i, 1)
+    c.parent = null
+  }
+
+  // ContainerCapacity.receive + CarrierHolder.reparent 시뮬 (단순화)
+  receive(carrier: any): void {
+    const op = carrier.parent
+    if (op?.removeComponent) op.removeComponent(carrier)
+    this.addComponent(carrier)
+    const point = this.attachPointFor(carrier)
+    point.attach.attach(carrier._realObject.object3d)
+    carrier._realObject.object3d.position.set(0, 0, 0)
+    // CarrierHolder.reparent 의 post-step: setTransientPlacement('carried')
+    ;(carrier._realObject as any).setTransientPlacement?.({
+      policy: 'carried',
+      meta: { carryPolicy: 'follow-holder' }
+    })
+  }
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+
+describe('RackGrid 3D scene graph: carrier parent transitions', () => {
+  it('obtainCarrier 후 carrier.obj3d.parent.name === rack-grid-anchor:A-0-1', () => {
+    const rack = new RackGridMock()
+    rack.state.data = [{ cellId: 'A-0-1' }]
+    const c = rack.obtainCarrier('A-0-1')!
+    c.should.not.be.null()
+    c._realObject.object3d.parent!.name.should.equal('rack-grid-anchor:A-0-1')
+  })
+
+  it('obtainCarrier 후 carrier 의 placement 가 carried (manual)', () => {
+    const rack = new RackGridMock()
+    rack.state.data = [{ cellId: 'A-0-1' }]
+    const c = rack.obtainCarrier('A-0-1')!
+    ;(c._realObject as any).placement?.policy?.should.equal('carried')
+  })
+
+  it('crane.receive 후 carrier.obj3d.parent === fork', () => {
+    const rack = new RackGridMock()
+    rack.state.data = [{ cellId: 'A-0-1' }]
+    const crane = new CraneMock()
+    const c = rack.obtainCarrier('A-0-1')!
+    crane.receive(c)
+    c._realObject.object3d.parent!.name.should.equal('fork')
+  })
+
+  it('crane.receive 후 carrier.parent (logical) === crane', () => {
+    const rack = new RackGridMock()
+    rack.state.data = [{ cellId: 'A-0-1' }]
+    const crane = new CraneMock()
+    const c = rack.obtainCarrier('A-0-1')!
+    crane.receive(c)
+    c.parent.should.equal(crane)
+  })
+
+  it('receiveAt 후 carrier.obj3d.parent === null', async () => {
+    const rack = new RackGridMock()
+    rack.state.data = [{ cellId: 'A-0-1' }]
+    const crane = new CraneMock()
+    const c = rack.obtainCarrier('A-0-1')!
+    crane.receive(c)
+    await rack.receiveAt('B-0-2', c)
+    ;(c._realObject.object3d.parent === null).should.be.true()
+  })
+})
+
+// **목표 검증** — fork 이동 시 carrier 가 따라가는지. 사용자 보고 *carrier 안
+// 따라옴 / fork 빈 포크짓* 의 회귀 방지 핵심 assertion.
+
+describe('RackGrid handoff follow: fork 이동 시 carrier world 따라감', () => {
+  it('fork 이동만 → carrier world = fork world', () => {
+    const rack = new RackGridMock()
+    rack.state.data = [{ cellId: 'A-0-1' }]
+    const crane = new CraneMock()
+    const c = rack.obtainCarrier('A-0-1')!
+    crane.receive(c)
+
+    crane.forkGroup.position.set(100, 200, 50)
+    crane.rootObject3d.updateMatrixWorld(true)
+
+    const carrierWorld = new THREE.Vector3()
+    c._realObject.object3d.getWorldPosition(carrierWorld)
+    const forkWorld = new THREE.Vector3()
+    crane.forkGroup.getWorldPosition(forkWorld)
+
+    carrierWorld.x.should.be.approximately(forkWorld.x, 1e-9)
+    carrierWorld.y.should.be.approximately(forkWorld.y, 1e-9)
+    carrierWorld.z.should.be.approximately(forkWorld.z, 1e-9)
+  })
+
+  it('lift + trolley + fork extension 복합 — carrier 가 모두 따라감', () => {
+    const rack = new RackGridMock()
+    rack.state.data = [{ cellId: 'A-0-1' }]
+    const crane = new CraneMock()
+    const c = rack.obtainCarrier('A-0-1')!
+    crane.receive(c)
+
+    // trolley (X 이동) + lift (Y 이동) + fork (Z extension) 시뮬
+    crane.trolleyGroup.position.set(500, 0, 0)
+    crane.carriageLiftGroup.position.set(0, 800, 0)
+    crane.forkGroup.position.set(0, 0, 300)
+    crane.rootObject3d.updateMatrixWorld(true)
+
+    const carrierWorld = new THREE.Vector3()
+    c._realObject.object3d.getWorldPosition(carrierWorld)
+    const forkWorld = new THREE.Vector3()
+    crane.forkGroup.getWorldPosition(forkWorld)
+
+    carrierWorld.x.should.be.approximately(forkWorld.x, 1e-9, 'X (trolley + fork) 따라감')
+    carrierWorld.y.should.be.approximately(forkWorld.y, 1e-9, 'Y (lift) 따라감')
+    carrierWorld.z.should.be.approximately(forkWorld.z, 1e-9, 'Z (fork extension) 따라감')
+  })
+
+  it('연속 fork.position 변경 — carrier 가 매 step 따라감', () => {
+    const rack = new RackGridMock()
+    rack.state.data = [{ cellId: 'A-0-1' }]
+    const crane = new CraneMock()
+    const c = rack.obtainCarrier('A-0-1')!
+    crane.receive(c)
+
+    const positions = [[0,0,0], [100,0,0], [100,200,0], [100,200,300], [50,150,250]]
+    for (const [x, y, z] of positions) {
+      crane.forkGroup.position.set(x, y, z)
+      crane.rootObject3d.updateMatrixWorld(true)
+
+      const cw = new THREE.Vector3()
+      c._realObject.object3d.getWorldPosition(cw)
+      cw.x.should.be.approximately(x, 1e-9, `step (${x},${y},${z}) X`)
+      cw.y.should.be.approximately(y, 1e-9, `step (${x},${y},${z}) Y`)
+      cw.z.should.be.approximately(z, 1e-9, `step (${x},${y},${z}) Z`)
+    }
+  })
+})
+
+// 회귀 방지 — ghost / parent 누락 검증.
+
+describe('RackGrid 회귀 방지: ghost 없음', () => {
+  it('receiveAt 후 fork.children 비어있음', async () => {
+    const rack = new RackGridMock()
+    rack.state.data = [{ cellId: 'A' }]
+    const crane = new CraneMock()
+    const c = rack.obtainCarrier('A')!
+    crane.receive(c)
+    crane.forkGroup.children.length.should.equal(1)
+    await rack.receiveAt('B', c)
+    crane.forkGroup.children.length.should.equal(0)
+  })
+
+  it('pick 후 source anchor.children 비어있음', () => {
+    const rack = new RackGridMock()
+    rack.state.data = [{ cellId: 'A-0-1' }]
+    const crane = new CraneMock()
+    const sourceAnchor = rack.getSlotAttachObject3d('A-0-1')
+
+    const c = rack.obtainCarrier('A-0-1')!
+    sourceAnchor.children.length.should.equal(1)
+
+    crane.receive(c)
+    sourceAnchor.children.length.should.equal(0)
+  })
+
+  it('A→B 10번 왕복 — 매 사이클 ghost 0', async () => {
+    const rack = new RackGridMock()
+    rack.state.data = [{ cellId: 'A', sku: 'X' }]
+    const crane = new CraneMock()
+    const anchorA = rack.getSlotAttachObject3d('A')
+    const anchorB = rack.getSlotAttachObject3d('B')
+
+    for (let i = 0; i < 10; i++) {
+      const cAB = rack.obtainCarrier('A')!
+      cAB.should.not.be.null()
+      crane.receive(cAB)
+      await rack.receiveAt('B', cAB)
+      crane.forkGroup.children.length.should.equal(0)
+      anchorA.children.length.should.equal(0)
+      anchorB.children.length.should.equal(0)
+
+      const cBA = rack.obtainCarrier('B')!
+      cBA.should.not.be.null()
+      crane.receive(cBA)
+      await rack.receiveAt('A', cBA)
+      crane.forkGroup.children.length.should.equal(0)
+      anchorA.children.length.should.equal(0)
+      anchorB.children.length.should.equal(0)
+    }
+
+    rack.state.data.length.should.equal(1)
+    rack.state.data[0].cellId.should.equal('A')
+    rack.state.data[0].sku.should.equal('X')
+  })
+})

package/test/test-rack-grid-cell.ts

@@ -93,7 +93,7 @@ class MiniGridWithCells {
     return this.cellAt(parts[0], parts[1])
   }
 
-  parseCellId(cellId: string) {
+  parseSlotId(cellId: string) {
     const parts = cellId.split('-').map(Number)
     if (parts.length !== 3 || parts.some(n => !Number.isFinite(n))) return null
     return { col: parts[0], row: parts[1], shelf: parts[2] }
@@ -118,7 +118,7 @@ class MiniGridWithCells {
   }
 
   locationOf(cellId: string): string | null {
-    const parsed = this.parseCellId(cellId)
+    const parsed = this.parseSlotId(cellId)
     if (!parsed) return null
     const posKey = `${parsed.col}-${parsed.row}`
 

package/test/test-rack-grid-location.ts

@@ -73,7 +73,7 @@ class MiniGrid {
     return out
   }
 
-  parseCellId(cellId: string): { col: number; row: number; shelf: number } | null {
+  parseSlotId(cellId: string): { col: number; row: number; shelf: number } | null {
     const parts = cellId.split('-')
     if (parts.length !== 3) return null
     const [c, r, s] = parts.map(Number)
@@ -90,7 +90,7 @@ class MiniGrid {
   }
 
   locationOf(cellId: string): string | null {
-    const parsed = this.parseCellId(cellId)
+    const parsed = this.parseSlotId(cellId)
     if (!parsed) return null
     const posKey = `${parsed.col}-${parsed.row}`
     const override = this.cellOverrides[posKey]

package/test/test-rack-grid-occupied-slots.ts

@@ -0,0 +1,165 @@
+/*
+ * RackGrid.occupiedSlotIds — 셀 리스트 정보의 정확성 검증.
+ *
+ * 버그 시나리오 (이전): RackGridCell (rack-grid-cell type 의 시각 proxy 자식) 의
+ * state.cellId 가 bayKey ("col-row") 형식. carrier 의 state.cellId 는 full slot
+ * id ("col-row-shelf") 형식. occupiedSlotIds 가 모든 children sweep 시 bayKey
+ * 도 set 에 추가 → semantic 불일치 + crane simulate 의 reach filter 통과 안 됨.
+ *
+ * fix: occupiedSlotIds 가 *carriable child* 만 sweep — RackGridCell 의 bayKey
+ * 는 set 에 안 들어감. record + carrier 만.
+ */
+
+import 'should'
+
+// Mock RackGrid 의 occupiedSlotIds 본문 로직만 격리해 검증.
+// (real RackGrid 인스턴스 build 는 things-scene env 의존 — test 환경 부담.)
+
+function mockOccupiedSlotIds(opts: {
+  records: Array<{ cellId?: string }>
+  components: Array<{ isCarriable?: boolean; state?: { cellId?: string } }>
+  filter?: (id: string) => boolean
+}): string[] {
+  const { records, components, filter } = opts
+  const set = new Set<string>()
+  for (const r of records) {
+    const cid = r?.cellId
+    if (typeof cid === 'string' && (!filter || filter(cid))) set.add(cid)
+  }
+  for (const c of components) {
+    if (!c?.isCarriable) continue
+    const cid = c?.state?.cellId
+    if (typeof cid === 'string' && (!filter || filter(cid))) set.add(cid)
+  }
+  return Array.from(set)
+}
+
+describe('RackGrid.occupiedSlotIds — carriable 만, RackGridCell bayKey 제외', () => {
+  it('records 의 cellId 가 모두 포함', () => {
+    const ids = mockOccupiedSlotIds({
+      records: [
+        { cellId: '0-0-0' },
+        { cellId: '0-0-1' },
+        { cellId: '2-1-3' }
+      ],
+      components: []
+    })
+    ids.length.should.equal(3)
+    ids.should.containEql('0-0-0')
+    ids.should.containEql('0-0-1')
+    ids.should.containEql('2-1-3')
+  })
+
+  it('carriable child 의 cellId 가 포함', () => {
+    const ids = mockOccupiedSlotIds({
+      records: [],
+      components: [
+        { isCarriable: true, state: { cellId: '1-0-2' } },
+        { isCarriable: true, state: { cellId: '3-1-5' } }
+      ]
+    })
+    ids.length.should.equal(2)
+    ids.should.containEql('1-0-2')
+    ids.should.containEql('3-1-5')
+  })
+
+  it('RackGridCell (= isCarriable: false) 의 bayKey 는 *제외*', () => {
+    const ids = mockOccupiedSlotIds({
+      records: [{ cellId: '0-0-0' }],
+      components: [
+        // RackGridCell — 시각 proxy. state.cellId = bayKey "col-row" 형식.
+        { isCarriable: false, state: { cellId: '0-0' } },
+        { isCarriable: false, state: { cellId: '1-0' } },
+        { isCarriable: false, state: { cellId: '2-0' } }
+      ]
+    })
+    ids.length.should.equal(1)   // record 1 개만
+    ids.should.containEql('0-0-0')
+    // bayKey 절대 포함 X
+    ids.should.not.containEql('0-0')
+    ids.should.not.containEql('1-0')
+    ids.should.not.containEql('2-0')
+  })
+
+  it('record + carrier + RackGridCell 혼합 — carrier 의 full slotId 만, bayKey 제외', () => {
+    const ids = mockOccupiedSlotIds({
+      records: [
+        { cellId: '0-0-0' }
+      ],
+      components: [
+        { isCarriable: false, state: { cellId: '1-0' } },   // RackGridCell
+        { isCarriable: true, state: { cellId: '1-0-2' } },  // 실 carrier
+        { isCarriable: false, state: { cellId: '2-0' } }    // RackGridCell
+      ]
+    })
+    ids.length.should.equal(2)
+    ids.should.containEql('0-0-0')
+    ids.should.containEql('1-0-2')
+    ids.should.not.containEql('1-0')
+    ids.should.not.containEql('2-0')
+  })
+
+  it('filter predicate — adjSet 매칭 안 의 id 만', () => {
+    const adjSet = new Set(['0-0-0', '1-0-0'])
+    const ids = mockOccupiedSlotIds({
+      records: [
+        { cellId: '0-0-0' },   // adjSet 안 — pass
+        { cellId: '0-0-1' },   // adjSet 밖 — reject
+        { cellId: '1-0-0' }    // adjSet 안 — pass
+      ],
+      components: [],
+      filter: id => adjSet.has(id)
+    })
+    ids.length.should.equal(2)
+    ids.should.containEql('0-0-0')
+    ids.should.containEql('1-0-0')
+    ids.should.not.containEql('0-0-1')
+  })
+
+  it('동일 cellId 가 record + carrier 둘 다 있을 경우 — set dedupe', () => {
+    const ids = mockOccupiedSlotIds({
+      records: [{ cellId: '0-0-0' }],
+      components: [
+        { isCarriable: true, state: { cellId: '0-0-0' } }
+      ]
+    })
+    ids.length.should.equal(1)
+    ids.should.containEql('0-0-0')
+  })
+})
+
+describe('emptySlotIds — slotIds - occupiedSlotIds, RackGridCell bayKey 영향 X', () => {
+  function mockEmptySlotIds(opts: {
+    allSlotIds: string[]
+    records: Array<{ cellId?: string }>
+    components: Array<{ isCarriable?: boolean; state?: { cellId?: string } }>
+  }): string[] {
+    const occ = new Set(mockOccupiedSlotIds(opts))
+    return opts.allSlotIds.filter(id => !occ.has(id))
+  }
+
+  it('record 점유 외 모두 빈 slot', () => {
+    const all = ['0-0-0', '0-0-1', '1-0-0', '1-0-1']
+    const empty = mockEmptySlotIds({
+      allSlotIds: all,
+      records: [{ cellId: '0-0-0' }],
+      components: []
+    })
+    empty.length.should.equal(3)
+    empty.should.not.containEql('0-0-0')
+  })
+
+  it('RackGridCell bayKey 가 *_empty 결과에 *_노이즈* 안 함', () => {
+    const all = ['0-0-0', '0-0-1', '1-0-0', '1-0-1']
+    const empty = mockEmptySlotIds({
+      allSlotIds: all,
+      records: [],
+      components: [
+        // bayKey 가 occupiedSlotIds 에 들어가지 않으므로 empty 결과 영향 X
+        { isCarriable: false, state: { cellId: '0-0' } },
+        { isCarriable: false, state: { cellId: '1-0' } }
+      ]
+    })
+    empty.length.should.equal(4)   // 모든 slot 이 empty (carrier 0)
+  })
+})