@operato/scene-storage 10.0.0-beta.41 → 10.0.0-beta.43

package/test/test-real-3d-positioning.ts

@@ -0,0 +1,158 @@
+/*
+ * 실제 THREE.js scene graph 에서 anchor 와 stock 의 *world position 일치* 검증.
+ *
+ * 단순 공식 비교 (test-coord-alignment.ts) 가 통과해도, 실제 Three.js 환경에선 rack 의
+ * matrixWorld / 부모 chain 변환에 따라 어긋날 수 있음. 이 테스트는:
+ *   1. 실 THREE.Group (rack.object3d) 만들기
+ *   2. anchor 와 stock 을 각각 그 자식으로 추가
+ *   3. 위치 set 후 *matrixWorld 비교*
+ * 둘이 동일 world 위치라면 framework 통과 시도 정확. 어긋나면 framework 측 추가 변환 의심.
+ */
+
+import 'should'
+import * as THREE from 'three'
+
+function computeAnchorPos(
+  cell: { localPosition: { x: number; y: number; z: number } },
+  rp: { width: number; depth: number; height: number; bays: number; levels: number; shelfBase: number }
+) {
+  const sz = rp.depth - rp.shelfBase
+  const bw = rp.width / rp.bays
+  const lh = sz / rp.levels
+  const sd = lh * 0.7
+  return {
+    x: cell.localPosition.x + bw / 2 - rp.width / 2,
+    y: cell.localPosition.y - rp.depth / 2 + sd / 2,
+    z: cell.localPosition.z + rp.height / 2 - rp.height / 2
+  }
+}
+
+function computeStockPos(
+  cell: { localPosition: { x: number; y: number; z: number } },
+  rp: { width: number; depth: number; height: number; bays: number; levels: number; shelfBase: number }
+) {
+  const sz = rp.depth - rp.shelfBase
+  const bw = rp.width / rp.bays
+  const lh = sz / rp.levels
+  const sd = lh * 0.7
+  const cellCenterY = cell.localPosition.y + lh / 2 - rp.depth / 2
+  return {
+    x: cell.localPosition.x + bw / 2 - rp.width / 2,
+    y: cellCenterY - lh / 2 + sd / 2,
+    z: cell.localPosition.z + rp.height / 2 - rp.height / 2
+  }
+}
+
+function makeCell(bay: number, row: number, level: number, p: any) {
+  return {
+    localPosition: {
+      x: (bay - 1) * p.bayWidth,
+      y: p.shelfBase + (level - 1) * p.levelHeight,
+      z: (row - 1) * p.rowDepth
+    }
+  }
+}
+
+describe('Real Three.js: anchor / stock world position 일치', () => {
+  const rp = { width: 1000, depth: 3000, height: 600, bays: 5, levels: 4, shelfBase: 0 }
+  const bw = rp.width / rp.bays
+  const lh = (rp.depth - rp.shelfBase) / rp.levels
+  const rd = rp.height
+
+  it('rack 가 origin 에 있을 때 — anchor.matrixWorld === stock.matrixWorld', () => {
+    const rackObj = new THREE.Group()
+    rackObj.position.set(0, 0, 0)
+    rackObj.updateMatrixWorld(true)
+
+    const cell = makeCell(2, 1, 2, { bayWidth: bw, rowDepth: rd, levelHeight: lh, shelfBase: 0 })
+    const anchorPos = computeAnchorPos(cell, rp)
+    const stockPos = computeStockPos(cell, rp)
+
+    const anchor = new THREE.Object3D()
+    anchor.position.set(anchorPos.x, anchorPos.y, anchorPos.z)
+    rackObj.add(anchor)
+    anchor.updateMatrixWorld(true)
+
+    const stock = new THREE.Object3D()
+    stock.position.set(stockPos.x, stockPos.y, stockPos.z)
+    rackObj.add(stock)
+    stock.updateMatrixWorld(true)
+
+    const anchorWorld = new THREE.Vector3()
+    anchor.getWorldPosition(anchorWorld)
+    const stockWorld = new THREE.Vector3()
+    stock.getWorldPosition(stockWorld)
+
+    anchorWorld.x.should.be.approximately(stockWorld.x, 0.0001)
+    anchorWorld.y.should.be.approximately(stockWorld.y, 0.0001)
+    anchorWorld.z.should.be.approximately(stockWorld.z, 0.0001)
+  })
+
+  it('rack 가 translated (1000, 500, 200) 일 때 — anchor === stock', () => {
+    const rackObj = new THREE.Group()
+    rackObj.position.set(1000, 500, 200)
+    rackObj.updateMatrixWorld(true)
+
+    const cell = makeCell(3, 1, 3, { bayWidth: bw, rowDepth: rd, levelHeight: lh, shelfBase: 0 })
+    const anchorPos = computeAnchorPos(cell, rp)
+    const stockPos = computeStockPos(cell, rp)
+
+    const anchor = new THREE.Object3D(); anchor.position.set(anchorPos.x, anchorPos.y, anchorPos.z)
+    rackObj.add(anchor); anchor.updateMatrixWorld(true)
+    const stock = new THREE.Object3D(); stock.position.set(stockPos.x, stockPos.y, stockPos.z)
+    rackObj.add(stock); stock.updateMatrixWorld(true)
+
+    const aw = new THREE.Vector3(); anchor.getWorldPosition(aw)
+    const sw = new THREE.Vector3(); stock.getWorldPosition(sw)
+    aw.x.should.be.approximately(sw.x, 0.0001)
+    aw.y.should.be.approximately(sw.y, 0.0001)
+    aw.z.should.be.approximately(sw.z, 0.0001)
+    // 또한 rack 의 translation 이 정확히 반영되어야 함
+    aw.x.should.be.approximately(anchorPos.x + 1000, 0.0001)
+    aw.y.should.be.approximately(anchorPos.y + 500, 0.0001)
+    aw.z.should.be.approximately(anchorPos.z + 200, 0.0001)
+  })
+
+  it('rack 가 회전 (Y 축 45°) 일 때 — anchor === stock', () => {
+    const rackObj = new THREE.Group()
+    rackObj.rotation.y = Math.PI / 4
+    rackObj.updateMatrixWorld(true)
+
+    const cell = makeCell(1, 1, 1, { bayWidth: bw, rowDepth: rd, levelHeight: lh, shelfBase: 0 })
+    const anchorPos = computeAnchorPos(cell, rp)
+    const stockPos = computeStockPos(cell, rp)
+
+    const anchor = new THREE.Object3D(); anchor.position.set(anchorPos.x, anchorPos.y, anchorPos.z)
+    rackObj.add(anchor); anchor.updateMatrixWorld(true)
+    const stock = new THREE.Object3D(); stock.position.set(stockPos.x, stockPos.y, stockPos.z)
+    rackObj.add(stock); stock.updateMatrixWorld(true)
+
+    const aw = new THREE.Vector3(); anchor.getWorldPosition(aw)
+    const sw = new THREE.Vector3(); stock.getWorldPosition(sw)
+    aw.x.should.be.approximately(sw.x, 0.0001)
+    aw.y.should.be.approximately(sw.y, 0.0001)
+    aw.z.should.be.approximately(sw.z, 0.0001)
+  })
+
+  it('5×4 grid 모든 cell — anchor === stock', () => {
+    const rackObj = new THREE.Group()
+    rackObj.position.set(100, 200, 300)
+    rackObj.rotation.set(0, Math.PI / 6, 0)
+    rackObj.updateMatrixWorld(true)
+
+    for (let b = 1; b <= 5; b++) {
+      for (let l = 1; l <= 4; l++) {
+        const cell = makeCell(b, 1, l, { bayWidth: bw, rowDepth: rd, levelHeight: lh, shelfBase: 0 })
+        const aPos = computeAnchorPos(cell, rp)
+        const sPos = computeStockPos(cell, rp)
+        const a = new THREE.Object3D(); a.position.set(aPos.x, aPos.y, aPos.z); rackObj.add(a); a.updateMatrixWorld(true)
+        const s = new THREE.Object3D(); s.position.set(sPos.x, sPos.y, sPos.z); rackObj.add(s); s.updateMatrixWorld(true)
+        const aw = new THREE.Vector3(); a.getWorldPosition(aw)
+        const sw = new THREE.Vector3(); s.getWorldPosition(sw)
+        aw.x.should.be.approximately(sw.x, 0.0001)
+        aw.y.should.be.approximately(sw.y, 0.0001)
+        aw.z.should.be.approximately(sw.z, 0.0001)
+      }
+    }
+  })
+})

package/test/test-slot-center-convention.ts

@@ -0,0 +1,116 @@
+/*
+ * SlotTarget.center 의 좌표 컨벤션 검증.
+ *
+ * 핵심 가설: things-scene 의 모든 컴포넌트의 `.center` 는 *parent 좌표계 의 center*
+ *  (= `bounds.left + width/2`). Crane.moveTo 가 *target.center → target.toScene* 으로
+ *  X 도달 위치를 결정. 이때 *pick target (예: parcel)* 와 *place target (SlotTarget)*
+ *  의 .center 가 *같은 좌표계 의 값* 이어야 동일한 변환 체인이 정확히 작동.
+ *
+ * 결함 시나리오: SlotTarget.center 가 *rack-local-inner 좌표* (rack.left/top 미포함)
+ *  를 반환하면, rack.toScene 이 같은 컨벤션 하에 처리해도 *layer 좌표* 의 점과 어긋남.
+ *  → place 만 X 위치 어긋남, pick 은 정상 (parcel.center 는 layer 좌표).
+ *
+ * 이 테스트가 *pickup vs place 의 좌표 일관성* 을 검증. 사용자가 본 결함:
+ *  "pick 은 비교적 잘 위치를 잡는데, place 는 완전히 bay 위치를 못 잡는다" — 의 직접 원인.
+ */
+import 'should'
+
+// ── things-scene 의 get_center 시뮬 — Component 의 .center 는 parent 좌표 의 center
+function componentCenter(bounds: { left: number; top: number; width: number; height: number }) {
+  return {
+    x: bounds.left + bounds.width / 2,
+    y: bounds.top + bounds.height / 2
+  }
+}
+
+// ── 새 cellCenter2D 공식 (수정 후) — rack.left + bayCenter
+function cellCenter2D_NEW(
+  cellId: string,
+  rack: { left: number; top: number; width: number; height: number; bays: number }
+) {
+  const bayIdx = Number(cellId.split('-')[0] ?? 0)
+  const bayWidth = rack.width / rack.bays
+  return {
+    x: rack.left + bayIdx * bayWidth + bayWidth / 2,
+    y: rack.top + rack.height / 2
+  }
+}
+
+// ── 이전 (결함) cellCenter2D 공식 — rack.left/top 미포함
+function cellCenter2D_OLD(
+  cellId: string,
+  rack: { left: number; top: number; width: number; height: number; bays: number }
+) {
+  const bayIdx = Number(cellId.split('-')[0] ?? 0)
+  const bayWidth = rack.width / rack.bays
+  return {
+    x: bayIdx * bayWidth + bayWidth / 2,
+    y: rack.height / 2
+  }
+}
+
+describe('SlotTarget.center 의 좌표 컨벤션 — pickup vs place 의 일관성', () => {
+
+  // 사용자의 실 환경 값 — rackState left=365.17 top=478.6 W=800 D=800 H=50 bays=20
+  const rack = { left: 365.17, top: 478.6, width: 800, height: 50, bays: 20 }
+
+  it('parcel.center === bay 0 의 hypothetical "real cell" .center (둘 다 layer 좌표)', () => {
+    // 가상의 *진짜 cell 컴포넌트* 가 있다고 가정 — 그 bounds 는 rack.left + bayLeft, rack.top
+    // bay 0 의 bounds = { left: rack.left + 0*bayWidth, top: rack.top, width: bayWidth, height: rack.height }
+    const bayWidth = rack.width / rack.bays
+    const realCellBounds = { left: rack.left + 0 * bayWidth, top: rack.top, width: bayWidth, height: rack.height }
+    const realCellCenter = componentCenter(realCellBounds)
+
+    // 이게 SlotTarget.center 가 *반환해야 할 값* — 진짜 cell 컴포넌트 와 동일.
+    realCellCenter.x.should.equal(rack.left + bayWidth / 2)  // = 365.17 + 20 = 385.17
+    realCellCenter.y.should.equal(rack.top + rack.height / 2)  // = 478.6 + 25 = 503.6
+  })
+
+  it('NEW cellCenter2D === hypothetical real cell .center (일관성)', () => {
+    const bayWidth = rack.width / rack.bays
+    const realCellCenter = componentCenter({
+      left: rack.left + 0 * bayWidth, top: rack.top, width: bayWidth, height: rack.height
+    })
+    const slotCenter = cellCenter2D_NEW('0-0-0', rack)
+
+    slotCenter.x.should.equal(realCellCenter.x)
+    slotCenter.y.should.equal(realCellCenter.y)
+  })
+
+  it('OLD cellCenter2D ≠ hypothetical real cell .center (결함 재현)', () => {
+    const bayWidth = rack.width / rack.bays
+    const realCellCenter = componentCenter({
+      left: rack.left + 0 * bayWidth, top: rack.top, width: bayWidth, height: rack.height
+    })
+    const slotCenter = cellCenter2D_OLD('0-0-0', rack)
+
+    // OLD 는 rack.left, rack.top 미포함이므로 *rack.left, rack.top 만큼* 차이.
+    slotCenter.x.should.not.equal(realCellCenter.x)
+    slotCenter.y.should.not.equal(realCellCenter.y)
+    Math.abs(slotCenter.x - realCellCenter.x).should.be.approximately(rack.left, 0.001)
+    Math.abs(slotCenter.y - realCellCenter.y).should.be.approximately(rack.top, 0.001)
+    // 차이가 *정확히 rack 의 left/top* — 이것이 사용자가 본 "완전히 어긋남" 의 크기 (≈ 365)
+  })
+
+  it('NEW cellCenter2D: 다양한 bay/level 에 대해 layer 좌표 일관성', () => {
+    for (let b = 0; b < rack.bays; b++) {
+      const bayWidth = rack.width / rack.bays
+      const realCenter = componentCenter({
+        left: rack.left + b * bayWidth, top: rack.top, width: bayWidth, height: rack.height
+      })
+      const slotCenter = cellCenter2D_NEW(`${b}-0-0`, rack)
+      slotCenter.x.should.equal(realCenter.x)
+      slotCenter.y.should.equal(realCenter.y)
+    }
+  })
+
+  it('어긋남의 크기 = rack.left (= 365.17) — pickup 정확, place ≈ -365 X 어긋남', () => {
+    // 사용자 환경에서 OLD 가 만든 어긋남 크기.
+    const oldCenter = cellCenter2D_OLD('0-0-0', rack)
+    const newCenter = cellCenter2D_NEW('0-0-0', rack)
+    const xShift = newCenter.x - oldCenter.x  // 365.17
+    xShift.should.be.approximately(rack.left, 0.001)
+    // 즉 OLD 는 *bay 0 의 시각 위치 (= 385.17)* 가 아닌 *(20, 25) — rack 의 왼쪽 위쪽 가까운 점*
+    // 으로 Crane 을 보냄. fork 가 rack 자체에서 벗어남.
+  })
+})

package/test/test-slot-target.ts

@@ -0,0 +1,189 @@
+/*
+ * Plan A — SlotTarget 의 Mover/Crane 인터페이스 호환성 검증.
+ *
+ * SlotTarget 은 Mover.pickAndPlace 의 dest 로 들어가며, framework 가 다음 surface 를
+ * 호출함:
+ *   - target.state       — Crane.engage (cellId 식별)
+ *   - target.center      — Mover.moveTo 의 2D path
+ *   - target._realObject.object3d   — getWorldPose / projectToScreen
+ *   - target.parent      — legacy 경로
+ *   - target.canReceive  — Mover.place dispatch
+ *   - target.receive     — Mover.place dispatch
+ *   - target.attachPointFor — Carriable.applyHolderAttachPoint
+ *
+ * SlotTarget 이 holder 의 SlottedHolder API 에 정확히 위임하는지를 격리 검증.
+ */
+
+import 'should'
+import * as THREE from 'three'
+import { SlotTarget } from '../../scene-base/src/slotted-holder.js'
+
+// ── Mock holder — SlottedHolder 컨트랙 구현 ─────────────────────────────────
+
+class MockHolder {
+  parent: any = { tag: 'parent-scene' }
+  center = { x: 100, y: 200 }
+  state: any = { type: 'mock-holder' }
+
+  _slotAnchors = new Map<string, THREE.Object3D>()
+  _receivedCalls: any[] = []
+  _canReceiveResult = true
+  _attachCenters = new Map<string, { x: number; y: number }>()
+
+  hasCarrierAt(_slotId: string): boolean { return false }
+  obtainCarrier(_slotId: string): any { return null }
+  canReceiveAt(_slotId: string, _carrier?: any): boolean { return this._canReceiveResult }
+  async receiveAt(slotId: string, carrier: any, options?: any): Promise<void> {
+    this._receivedCalls.push({ slotId, carrier, options })
+  }
+  recordFromCarrier(_carrier: any, slotId: string): any {
+    return { cellId: slotId }
+  }
+  getSlotAttachObject3d(slotId: string): THREE.Object3D | undefined {
+    let obj = this._slotAnchors.get(slotId)
+    if (!obj) {
+      obj = new THREE.Object3D()
+      obj.name = `mock-slot:${slotId}`
+      this._slotAnchors.set(slotId, obj)
+    }
+    return obj
+  }
+
+  cellCenter2D(slotId: string): { x: number; y: number } | null {
+    return this._attachCenters.get(slotId) ?? null
+  }
+
+  slotTargetAt(slotId: string): SlotTarget {
+    return new SlotTarget(this as any, slotId)
+  }
+}
+
+// ── Group 1: state ───────────────────────────────────────────────────────────
+
+describe('SlotTarget: state — cellId/slotId 노출', () => {
+  it('state.cellId 와 state.slotId 둘 다 slotId 와 일치', () => {
+    const h = new MockHolder()
+    const st = h.slotTargetAt('5-0-7')
+    st.state.cellId.should.equal('5-0-7')
+    st.state.slotId.should.equal('5-0-7')
+  })
+
+  it('state.type 은 slot-target — 다른 컴포넌트 type 과 구분', () => {
+    const h = new MockHolder()
+    const st = h.slotTargetAt('A')
+    st.state.type.should.equal('slot-target')
+  })
+})
+
+// ── Group 2: center — 2D path planning ──────────────────────────────────────
+
+describe('SlotTarget: center — holder.cellCenter2D 로 위임', () => {
+  it('holder.cellCenter2D 가 값 반환 → SlotTarget.center 가 그걸 그대로 반환', () => {
+    const h = new MockHolder()
+    h._attachCenters.set('A', { x: 555, y: 777 })
+    const st = h.slotTargetAt('A')
+    st.center.should.deepEqual({ x: 555, y: 777 })
+  })
+
+  it('cellCenter2D 가 null → holder.center 로 fallback', () => {
+    const h = new MockHolder()
+    h.center = { x: 42, y: 84 }
+    // cellCenter2D 에 등록 안 함 → null 반환
+    const st = h.slotTargetAt('未-등록')
+    st.center.should.deepEqual({ x: 42, y: 84 })
+  })
+})
+
+// ── Group 3: _realObject.object3d — getWorldPose 호환 ───────────────────────
+
+describe('SlotTarget: _realObject.object3d — getSlotAttachObject3d 위임', () => {
+  it('object3d 반환은 holder.getSlotAttachObject3d 와 동일 인스턴스', () => {
+    const h = new MockHolder()
+    const st = h.slotTargetAt('A')
+    const obj = st._realObject.object3d
+    obj!.should.equal(h.getSlotAttachObject3d('A'))
+  })
+
+  it('singleton — 같은 slotId 두 번 호출도 같은 object3d', () => {
+    const h = new MockHolder()
+    const st1 = h.slotTargetAt('A')
+    const st2 = h.slotTargetAt('A')
+    st1._realObject.object3d!.should.equal(st2._realObject.object3d!)
+  })
+
+  it('서로 다른 slotId → 서로 다른 object3d', () => {
+    const h = new MockHolder()
+    const a = h.slotTargetAt('A')._realObject.object3d
+    const b = h.slotTargetAt('B')._realObject.object3d
+    ;(a !== b).should.be.true()
+  })
+})
+
+// ── Group 4: canReceive / receive — Transferable 인터페이스 ──────────────────
+
+describe('SlotTarget: canReceive / receive — holder 에 위임', () => {
+  it('canReceive 가 holder.canReceiveAt 그대로 반환', () => {
+    const h = new MockHolder()
+    h._canReceiveResult = true
+    h.slotTargetAt('A').canReceive({} as any).should.be.true()
+    h._canReceiveResult = false
+    h.slotTargetAt('A').canReceive({} as any).should.be.false()
+  })
+
+  it('receive 가 holder.receiveAt 으로 위임 (slotId 와 carrier 전달)', async () => {
+    const h = new MockHolder()
+    const carrier = { tag: 'carrier-X' }
+    await h.slotTargetAt('C-0-0').receive(carrier as any, { dur: 200 })
+    h._receivedCalls.length.should.equal(1)
+    h._receivedCalls[0].slotId.should.equal('C-0-0')
+    h._receivedCalls[0].carrier.should.equal(carrier)
+    h._receivedCalls[0].options.dur.should.equal(200)
+  })
+})
+
+// ── Group 5: attachPointFor — Carriable.applyHolderAttachPoint 호환 ───────────
+
+describe('SlotTarget: attachPointFor — slot anchor object3d 가 attach frame', () => {
+  it('attachPointFor 반환의 .attach 가 _realObject.object3d 와 동일', () => {
+    const h = new MockHolder()
+    const st = h.slotTargetAt('A')
+    const frame = st.attachPointFor({} as any)
+    frame!.attach.should.equal(st._realObject.object3d)
+  })
+
+  it('holder 의 getSlotAttachObject3d 가 undefined → attachPointFor null', () => {
+    const h: any = new MockHolder()
+    h.getSlotAttachObject3d = () => undefined
+    const st = (h as MockHolder).slotTargetAt('?')
+    ;(st.attachPointFor({} as any) === null).should.be.true()
+  })
+})
+
+// ── Group 6: parent — legacy 경로 ────────────────────────────────────────────
+
+describe('SlotTarget: parent — holder.parent 그대로 노출', () => {
+  it('parent 는 holder.parent 와 동일', () => {
+    const h = new MockHolder()
+    const st = h.slotTargetAt('A')
+    st.parent.should.equal(h.parent)
+  })
+})
+
+// ── Group 7: 동일 holder 의 여러 SlotTarget 끼리 독립성 ─────────────────────
+
+describe('SlotTarget: 여러 인스턴스 사이의 독립성', () => {
+  it('서로 다른 slotId → 서로 다른 state/center/object3d', () => {
+    const h = new MockHolder()
+    h._attachCenters.set('A', { x: 1, y: 1 })
+    h._attachCenters.set('B', { x: 99, y: 99 })
+
+    const sA = h.slotTargetAt('A')
+    const sB = h.slotTargetAt('B')
+
+    sA.state.cellId.should.equal('A')
+    sB.state.cellId.should.equal('B')
+    sA.center.should.deepEqual({ x: 1, y: 1 })
+    sB.center.should.deepEqual({ x: 99, y: 99 })
+    ;(sA._realObject.object3d !== sB._realObject.object3d).should.be.true()
+  })
+})