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

package/test/test-storage-rack-click.ts

@@ -0,0 +1,329 @@
+/*
+ * Click routing — InstancedMesh-based + empty-cell fallback.
+ *
+ * 검증 대상:
+ *  - _raycastRackHit: closest hit 이 *우리 rack* descendant 인지 walk-up 으로 판별
+ *  - stockMesh hit → records[instanceId] 로 record 추출
+ *  - shelf/frame hit → world point 로 cellId 역산
+ *  - 다른 rack 또는 무관 mesh 가 더 가까우면 무시
+ *
+ * 실제 Three.js raycaster 와 InstancedMesh 를 *진짜* 만들어서 검증한다.
+ */
+
+import 'should'
+import * as THREE from 'three'
+
+// ── 클래스 contract 검증 fixture ────────────────────────────────────────────────
+//
+// 실제 Rack 클래스는 things-scene Component / RealObject / 3D 파이프라인을 요구해 단위
+// 테스트에서 인스턴스화 비현실적. 이 테스트는 *click routing* 의 정확한 로직 (closest hit
+// 판단 + records 매핑) 을 isolate 해 검증.
+
+function buildStockInstancedMesh(records: any[]): THREE.InstancedMesh {
+  const geo = new THREE.BoxGeometry(10, 10, 10)
+  const mat = new THREE.MeshBasicMaterial()
+  const inst = new THREE.InstancedMesh(geo, mat, records.length)
+  inst.userData.context = { tag: 'storage-rack-3d' }
+  inst.userData._records = records
+
+  const m = new THREE.Matrix4()
+  for (let i = 0; i < records.length; i++) {
+    // 각 instance 를 (i * 20, 0, 0) 에 배치 (간격 20)
+    m.makeTranslation(i * 20, 0, 0)
+    inst.setMatrixAt(i, m)
+  }
+  inst.instanceMatrix.needsUpdate = true
+  inst.computeBoundingSphere()
+  inst.computeBoundingBox()
+  return inst
+}
+
+/**
+ * Rack._raycastRackHit 의 *순수 로직* 부분만 추출해 검증한다.
+ * (실 구현은 `tc._threeCapability.getObjectsByRaycast()` 호출 + walk-up check + return)
+ */
+function raycastRackHit(
+  intersects: THREE.Intersection[] | undefined,
+  ourRealObject: any
+): THREE.Intersection | undefined {
+  if (!intersects || intersects.length === 0) return undefined
+  const closest = intersects[0]
+  let obj: THREE.Object3D | null = closest.object
+  while (obj) {
+    if (obj.userData?.context === ourRealObject) return closest
+    obj = obj.parent
+  }
+  return undefined
+}
+
+/** Rack 의 stockMesh hit 인지 (= isStock 분기) */
+function isStockHit(
+  hit: THREE.Intersection | undefined,
+  stockMesh: THREE.InstancedMesh | undefined
+): boolean {
+  return !!hit && !!stockMesh && hit.object === stockMesh
+}
+
+/** world point → cellId 역산 (rack matrixWorld = identity 가정) */
+function cellIdFromWorldPoint(
+  worldPoint: { x: number; y: number },
+  state: { bays: number; levels: number; width: number; depth: number; shelfBaseHeight?: number }
+): string | null {
+  const bays = state.bays
+  const levels = state.levels
+  const width = state.width
+  const depth = state.depth
+  const shelfBase = state.shelfBaseHeight || 0
+  const shelfZone = depth - shelfBase
+  const bayWidth = width / bays
+  const levelHeight = shelfZone / levels
+  const bayIdx = Math.floor((worldPoint.x + width / 2) / bayWidth)
+  const yFromBottom = worldPoint.y + depth / 2 - shelfBase
+  const levelIdx = Math.floor(yFromBottom / levelHeight)
+  if (bayIdx < 0 || bayIdx >= bays || levelIdx < 0 || levelIdx >= levels) {
+    return `out-of-bounds(bay=${bayIdx}, level=${levelIdx})`
+  }
+  return `${bayIdx}-0-${levelIdx}`
+}
+
+function resolveRecord(hit: THREE.Intersection | undefined): any | undefined {
+  if (!hit) return undefined
+  const inst: any = hit.object
+  const records: any[] | undefined = inst?.userData?._records
+  return records?.[hit.instanceId ?? -1]
+}
+
+// ── Group 1: 실 Three.js raycaster 로 InstancedMesh hit-test 검증 ────────────
+
+describe('Click: real Three.js InstancedMesh raycast', () => {
+  const records = [
+    { cellId: '0-0-0', sku: 'A', qty: 1 },
+    { cellId: '1-0-0', sku: 'B', qty: 2 },
+    { cellId: '2-0-0', sku: 'C', qty: 3 }
+  ]
+  const stockMesh = buildStockInstancedMesh(records)
+
+  it('instanceId 와 record 의 순서가 동일하다', () => {
+    ;(stockMesh.userData._records as any[]).length.should.equal(3)
+    ;(stockMesh.userData._records as any[])[1].cellId.should.equal('1-0-0')
+  })
+
+  it('instance 0 을 직접 겨냥한 ray → instanceId 0 hit', () => {
+    const raycaster = new THREE.Raycaster()
+    // instance 0 은 (0,0,0). z=+50 에서 -Z 방향으로 쏘기.
+    raycaster.set(new THREE.Vector3(0, 0, 50), new THREE.Vector3(0, 0, -1))
+    const hits: THREE.Intersection[] = []
+    stockMesh.raycast(raycaster, hits)
+    hits.length.should.be.greaterThanOrEqual(1)
+    hits[0].instanceId!.should.equal(0)
+  })
+
+  it('instance 2 (x=40) 을 겨냥한 ray → instanceId 2 hit', () => {
+    const raycaster = new THREE.Raycaster()
+    raycaster.set(new THREE.Vector3(40, 0, 50), new THREE.Vector3(0, 0, -1))
+    const hits: THREE.Intersection[] = []
+    stockMesh.raycast(raycaster, hits)
+    hits.length.should.be.greaterThanOrEqual(1)
+    hits[0].instanceId!.should.equal(2)
+  })
+
+  it('hit 으로부터 record 역참조', () => {
+    const raycaster = new THREE.Raycaster()
+    raycaster.set(new THREE.Vector3(20, 0, 50), new THREE.Vector3(0, 0, -1))
+    const hits: THREE.Intersection[] = []
+    stockMesh.raycast(raycaster, hits)
+    const rec = resolveRecord(hits[0])
+    rec.should.not.be.null()
+    rec.cellId.should.equal('1-0-0')
+    rec.sku.should.equal('B')
+  })
+
+  it('raycast 가 빗나가면 hits 비어있음', () => {
+    const raycaster = new THREE.Raycaster()
+    // 멀리 y=+1000 에서 -Y 로 쏘면 stockMesh (y=0 plane) 와 평행하지 않으나, x=1000 빗나감.
+    raycaster.set(new THREE.Vector3(1000, 0, 50), new THREE.Vector3(0, 0, -1))
+    const hits: THREE.Intersection[] = []
+    stockMesh.raycast(raycaster, hits)
+    hits.length.should.equal(0)
+  })
+})
+
+// ── Group 2: rack walk-up — 우리 rack 인지 판별 ──────────────────────────────
+
+describe('Click: rack walk-up identifies "our rack"', () => {
+  const ourRealObject = { tag: 'our-rack' }
+  const otherRealObject = { tag: 'other-rack' }
+
+  // Set up: rack 의 root 와 자식 mesh들 — userData.context 가 우리 realObject
+  const ourRoot = new THREE.Group()
+  ourRoot.userData.context = ourRealObject
+  const ourFrameMesh = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1), new THREE.MeshBasicMaterial())
+  ourRoot.add(ourFrameMesh)   // frame 은 자체 context 없음 → walk-up 으로 찾음
+
+  const ourStockMesh = buildStockInstancedMesh([{ cellId: 'A', sku: 'a' }])
+  ourStockMesh.userData.context = ourRealObject   // override fixture default
+  ourRoot.add(ourStockMesh)
+
+  // Another rack — sibling
+  const otherRoot = new THREE.Group()
+  otherRoot.userData.context = otherRealObject
+  const otherMesh = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1), new THREE.MeshBasicMaterial())
+  otherRoot.add(otherMesh)
+
+  it('우리 rack 의 stock mesh hit → 반환', () => {
+    const intersects: THREE.Intersection[] = [
+      { object: ourStockMesh, instanceId: 0, distance: 30, point: new THREE.Vector3() } as any
+    ]
+    const hit = raycastRackHit(intersects, ourRealObject)
+    ;(hit === undefined).should.be.false()
+    hit!.object.should.equal(ourStockMesh)
+  })
+
+  it('우리 rack 의 frame mesh hit (자체 context 없음, walk-up) → 반환', () => {
+    const intersects: THREE.Intersection[] = [
+      { object: ourFrameMesh, distance: 10, point: new THREE.Vector3() } as any
+    ]
+    const hit = raycastRackHit(intersects, ourRealObject)
+    ;(hit === undefined).should.be.false()
+    hit!.object.should.equal(ourFrameMesh)
+  })
+
+  it('다른 rack 이 더 가까우면 — undefined (우리 rack 아님)', () => {
+    const intersects: THREE.Intersection[] = [
+      { object: otherMesh, distance: 10, point: new THREE.Vector3() } as any,
+      { object: ourStockMesh, instanceId: 0, distance: 30, point: new THREE.Vector3() } as any
+    ]
+    const hit = raycastRackHit(intersects, ourRealObject)
+    ;(hit === undefined).should.be.true()
+  })
+
+  it('intersects 비어있으면 undefined', () => {
+    ;(raycastRackHit([], ourRealObject) === undefined).should.be.true()
+  })
+
+  it('intersects undefined 이면 undefined', () => {
+    ;(raycastRackHit(undefined, ourRealObject) === undefined).should.be.true()
+  })
+
+  it('isStockHit — stockMesh hit 만 true', () => {
+    const stockHit: any = { object: ourStockMesh, instanceId: 0 }
+    const frameHit: any = { object: ourFrameMesh }
+    isStockHit(stockHit, ourStockMesh).should.be.true()
+    isStockHit(frameHit, ourStockMesh).should.be.false()
+    isStockHit(undefined, ourStockMesh).should.be.false()
+    isStockHit(stockHit, undefined).should.be.false()
+  })
+})
+
+// ── Group 3: records lookup contract ────────────────────────────────────────
+
+describe('Click: records lookup', () => {
+  it('hit.instanceId 가 records 범위 안 → 정상 record', () => {
+    const stockMesh = buildStockInstancedMesh([
+      { cellId: 'A', sku: 'a' },
+      { cellId: 'B', sku: 'b' }
+    ])
+    const hit: any = { object: stockMesh, instanceId: 1 }
+    const rec = resolveRecord(hit)
+    rec.cellId.should.equal('B')
+  })
+
+  it('records 가 비어있으면 undefined', () => {
+    const stockMesh = new THREE.InstancedMesh(
+      new THREE.BoxGeometry(1, 1, 1),
+      new THREE.MeshBasicMaterial(),
+      0
+    )
+    stockMesh.userData._records = []
+    const hit: any = { object: stockMesh, instanceId: 0 }
+    const rec = resolveRecord(hit)
+    ;(rec === undefined).should.be.true()
+  })
+
+  it('instanceId out-of-bounds → undefined', () => {
+    const stockMesh = buildStockInstancedMesh([{ cellId: 'X' }])
+    const hit: any = { object: stockMesh, instanceId: 5 }
+    const rec = resolveRecord(hit)
+    ;(rec === undefined).should.be.true()
+  })
+
+  it('hit 자체가 undefined → undefined', () => {
+    resolveRecord(undefined)?.should.equal('never')
+    // 정확히 undefined 인지 직접 확인
+    ;(resolveRecord(undefined) === undefined).should.be.true()
+  })
+})
+
+// ── Group 4: empty cell fallback — cellIdFromWorldPoint ─────────────────────
+
+describe('Click: empty cell — world point → cellId 역산', () => {
+  const state = { bays: 20, levels: 20, width: 1000, depth: 3000, shelfBaseHeight: 0 }
+  // bayWidth=50, levelHeight=150
+
+  it('rack 중심 (0, 0) → bay 10, level 10', () => {
+    cellIdFromWorldPoint({ x: 0, y: 0 }, state)!.should.equal('10-0-10')
+  })
+
+  it('첫 cell (0-0-0) — rack 좌하단 근처', () => {
+    cellIdFromWorldPoint({ x: -475, y: -1425 }, state)!.should.equal('0-0-0')
+  })
+
+  it('마지막 cell (19-0-19) — rack 우상단 근처', () => {
+    cellIdFromWorldPoint({ x: 475, y: 1425 }, state)!.should.equal('19-0-19')
+  })
+
+  it('X 좌표 rack 밖 → out-of-bounds', () => {
+    cellIdFromWorldPoint({ x: 600, y: 0 }, state)!.should.match(/out-of-bounds/)
+  })
+
+  it('Y 좌표 rack 밖 → out-of-bounds', () => {
+    cellIdFromWorldPoint({ x: 0, y: -2000 }, state)!.should.match(/out-of-bounds/)
+  })
+
+  it('shelfBaseHeight 적용 → 첫 level (level 0) 의 중심 y', () => {
+    const s = { bays: 10, levels: 10, width: 1000, depth: 3000, shelfBaseHeight: 200 }
+    // shelfZone = 2800, levelHeight = 280
+    // level 0 시작 y = -1500 + 200 = -1300, center y = -1300 + 140 = -1160
+    cellIdFromWorldPoint({ x: 0, y: -1160 }, s)!.should.equal('5-0-0')
+  })
+})
+
+// ── Group 5: storage-rack-3d 의 _records 저장 계약 ───────────────────────────
+
+describe('Click: storage-rack-3d._records contract', () => {
+  it('valid record 만 instance 가 됨 — _records 길이가 valid.length 와 일치', () => {
+    // 시뮬레이션: rebuildStockMesh 가 cellId 없는 record 를 거른다.
+    const data = [
+      { cellId: '0-0-0', sku: 'A' },        // valid
+      { sku: 'no-cell' },                    // invalid — cellId 없음
+      { cellId: '1-0-0', sku: 'B' }          // valid
+    ]
+    const valid = data.filter(r => r.cellId)
+    valid.length.should.equal(2)
+
+    const inst = new THREE.InstancedMesh(
+      new THREE.BoxGeometry(1, 1, 1),
+      new THREE.MeshBasicMaterial(),
+      valid.length
+    )
+    inst.userData._records = valid
+
+    ;(inst.userData._records as any[])[0].cellId.should.equal('0-0-0')
+    ;(inst.userData._records as any[])[1].cellId.should.equal('1-0-0')
+    ;(inst.userData._records as any[]).length.should.equal(2)
+  })
+
+  it('userData.context 도 함께 set 되어 framework 가 walk-up 으로 찾음', () => {
+    const inst = new THREE.InstancedMesh(
+      new THREE.BoxGeometry(1, 1, 1),
+      new THREE.MeshBasicMaterial(),
+      1
+    )
+    const realObject = { tag: 'fake-storage-rack-3d' }
+    inst.userData.context = realObject
+    inst.userData._records = [{ cellId: 'X' }]
+
+    inst.userData.context.should.equal(realObject)
+    ;(inst.userData._records as any[])[0].cellId.should.equal('X')
+  })
+})

package/test/test-storage-rack-slot-api.ts

@@ -0,0 +1,357 @@
+/*
+ * Plan A — Slot API unit tests.
+ *
+ * 검증 대상:
+ *  - obtainCarrier → state.data 에서 record 제거 + rack 자식으로 carrier 추가
+ *  - receiveAt → carrier dispose + state.data 에 record push
+ *  - 동일 cellId 가 record + carrier-child 양쪽 동시 존재하지 않는 불변식
+ *  - recordFromCarrier 가 의미있는 필드만 추출 (transform 등 skip)
+ *  - canReceiveAt / hasCarrierAt 가 두 source 모두 인식
+ *
+ * 실제 Rack 클래스를 things-scene 의 full pipeline 으로 인스턴스화하기 비현실적이라
+ * *순수 슬롯 의미론* 만 격리해 검증. SlottedHolder 컨트랙의 *불변식* 자체에 집중.
+ */
+
+import 'should'
+
+// ── Fixture: 컨트랙의 핵심 의미론을 격리한 mini-rack ─────────────────────────
+
+class MiniRack {
+  state: any
+  components: any[] = []
+  _disposed = new Set<any>()
+
+  constructor(initialData: any[] = []) {
+    this.state = { data: initialData }
+  }
+
+  get records(): any[] {
+    return this.state.data ?? []
+  }
+
+  setState(key: string, value: any): void {
+    this.state[key] = value
+  }
+
+  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
+  }
+
+  _carrierChildAt(cellId: string): any {
+    return this.components.find(c => c.state?.cellId === cellId && c.placement === 'operation')
+  }
+
+  hasCarrierAt(cellId: string): boolean {
+    if (this._carrierChildAt(cellId)) return true
+    return this.records.some(r => r?.cellId === cellId)
+  }
+
+  obtainCarrier(cellId: string): any {
+    const existing = this._carrierChildAt(cellId)
+    if (existing) return existing
+
+    const idx = this.records.findIndex(r => r?.cellId === cellId)
+    if (idx === -1) return null
+    const record = this.records[idx]
+
+    // 가짜 carrier — placement 'operation' + state.cellId
+    const carrier: any = {
+      placement: 'operation',
+      state: { ...record, cellId, type: record.type ?? 'parcel' },
+      parent: null,
+      dispose() { /* test 가 추적 */ }
+    }
+    this.addComponent(carrier)
+
+    // atomic: child 추가 직후 record 제거
+    this.setState('data', this.records.filter((_, i) => i !== idx))
+
+    return carrier
+  }
+
+  canReceiveAt(cellId: string, _carrier?: any): boolean {
+    return !this.hasCarrierAt(cellId)
+  }
+
+  async receiveAt(cellId: string, carrier: any, _options?: any): Promise<void> {
+    if (!this.canReceiveAt(cellId, carrier)) return
+
+    const record = this.recordFromCarrier(carrier, cellId)
+
+    const p = carrier.parent
+    if (p && typeof p.removeComponent === 'function') p.removeComponent(carrier)
+    this._disposed.add(carrier)
+    carrier.dispose?.()
+
+    this.setState('data', [...this.records, record])
+  }
+
+  recordFromCarrier(carrier: any, cellId: string): any {
+    const state = carrier.state ?? {}
+    const SKIP = new Set(['left', 'top', 'zPos', 'transform', 'rotation', 'scale', '_transferSlotId', 'cellId'])
+    const record: any = { cellId, type: state.type }
+    for (const k of Object.keys(state)) {
+      if (SKIP.has(k)) continue
+      record[k] = state[k]
+    }
+    return record
+  }
+}
+
+// ── Group 1: obtainCarrier ──────────────────────────────────────────────────
+
+describe('Plan A: obtainCarrier — materialize from state.data', () => {
+  it('record 가 있는 cellId → carrier materialize, record 제거', () => {
+    const rack = new MiniRack([
+      { cellId: '0-0-0', sku: 'A', qty: 1 },
+      { cellId: '1-0-0', sku: 'B', qty: 2 }
+    ])
+
+    const carrier = rack.obtainCarrier('0-0-0')!
+    carrier.should.not.be.null()
+    carrier.state.sku.should.equal('A')
+    carrier.state.cellId.should.equal('0-0-0')
+    carrier.parent.should.equal(rack)
+
+    // state.data 에서 빠짐
+    rack.records.length.should.equal(1)
+    rack.records[0].cellId.should.equal('1-0-0')
+
+    // rack 의 자식
+    rack.components.length.should.equal(1)
+    rack.components[0].should.equal(carrier)
+  })
+
+  it('record 가 없는 cellId → null', () => {
+    const rack = new MiniRack([{ cellId: '0-0-0' }])
+    ;(rack.obtainCarrier('5-0-5') === null).should.be.true()
+    // state.data 는 변동 없음
+    rack.records.length.should.equal(1)
+  })
+
+  it('이미 child carrier 가 있는 cellId → 그 child 그대로 반환 (idempotent)', () => {
+    const rack = new MiniRack([])
+    const existing: any = {
+      placement: 'operation',
+      state: { cellId: '0-0-0', sku: 'X' },
+      parent: rack
+    }
+    rack.components.push(existing)
+
+    const got = rack.obtainCarrier('0-0-0')
+    got!.should.equal(existing)
+    // record 도 child 도 추가 안 됨
+    rack.records.length.should.equal(0)
+    rack.components.length.should.equal(1)
+  })
+
+  it('child + record 동시 존재 → child 우선 (record 손대지 않음)', () => {
+    // 불변식: 동시 존재하면 안 되지만 정합성 보호 — child 가 truth
+    const rack = new MiniRack([{ cellId: '0-0-0', sku: 'phantom' }])
+    const existing: any = {
+      placement: 'operation',
+      state: { cellId: '0-0-0', sku: 'real' },
+      parent: rack
+    }
+    rack.components.push(existing)
+
+    const got = rack.obtainCarrier('0-0-0')
+    got!.state.sku.should.equal('real')
+    rack.records.length.should.equal(1)   // phantom 그대로 (정리는 별도 책임)
+  })
+
+  it('obtainCarrier 2회 연속 호출 → 두 번째는 같은 carrier (record 다시 소비 안 함)', () => {
+    const rack = new MiniRack([{ cellId: '0-0-0', sku: 'A' }])
+    const c1 = rack.obtainCarrier('0-0-0')
+    const c2 = rack.obtainCarrier('0-0-0')
+    c1!.should.equal(c2)
+    rack.records.length.should.equal(0)
+  })
+})
+
+// ── Group 2: receiveAt ──────────────────────────────────────────────────────
+
+describe('Plan A: receiveAt — absorb carrier into state.data', () => {
+  it('carrier 받으면 dispose + state.data 에 record push', async () => {
+    const rack = new MiniRack([])
+    const carrier: any = {
+      placement: 'operation',
+      state: { type: 'parcel', sku: 'X', qty: 5 },
+      parent: { removeComponent: () => {} },
+      dispose() {}
+    }
+
+    await rack.receiveAt('2-0-3', carrier)
+
+    rack._disposed.has(carrier).should.be.true()
+    rack.records.length.should.equal(1)
+    rack.records[0].cellId.should.equal('2-0-3')
+    rack.records[0].sku.should.equal('X')
+    rack.records[0].qty.should.equal(5)
+    rack.records[0].type.should.equal('parcel')
+  })
+
+  it('이미 점유된 cellId → reject (state.data 변동 없음)', async () => {
+    const rack = new MiniRack([{ cellId: '0-0-0', sku: 'occupied' }])
+    const carrier: any = {
+      placement: 'operation',
+      state: { type: 'parcel', sku: 'X' },
+      parent: { removeComponent: () => {} },
+      dispose() {}
+    }
+
+    await rack.receiveAt('0-0-0', carrier)
+
+    rack._disposed.has(carrier).should.be.false()
+    rack.records.length.should.equal(1)
+    rack.records[0].sku.should.equal('occupied')
+  })
+
+  it('parent 에서 떼낸 후 dispose', async () => {
+    const rack = new MiniRack([])
+    const removed: any[] = []
+    const parent = {
+      removeComponent(c: any) { removed.push(c) }
+    }
+    const carrier: any = {
+      placement: 'operation',
+      state: { type: 'parcel' },
+      parent,
+      dispose() {}
+    }
+
+    await rack.receiveAt('0-0-0', carrier)
+
+    removed.length.should.equal(1)
+    removed[0].should.equal(carrier)
+    rack._disposed.has(carrier).should.be.true()
+  })
+})
+
+// ── Group 3: 불변식 — 동일 cellId 가 양쪽 동시 존재 안 함 ─────────────────────
+
+describe('Plan A: 불변식 — record ↔ child 상호 배타', () => {
+  it('obtainCarrier 가 record 제거 → child 와 record 가 동일 cellId 로 양립 안 함', () => {
+    const rack = new MiniRack([{ cellId: 'A', sku: 'A' }])
+    const c = rack.obtainCarrier('A')
+    rack._carrierChildAt('A').should.equal(c)
+    rack.records.some((r: any) => r.cellId === 'A').should.be.false()
+  })
+
+  it('receiveAt 후 record 존재 → child 사라짐', async () => {
+    const rack = new MiniRack([])
+    const carrier: any = {
+      placement: 'operation', state: { type: 'parcel' },
+      parent: { removeComponent: () => {} }, dispose() {}
+    }
+    await rack.receiveAt('B', carrier)
+    rack.records.some((r: any) => r.cellId === 'B').should.be.true()
+    ;(rack._carrierChildAt('B') === undefined).should.be.true()
+  })
+
+  it('Full cycle — record → carrier → record (다른 cellId 로 이동)', async () => {
+    const rack = new MiniRack([{ cellId: 'A', sku: 'X' }])
+
+    // 1. record 만 존재
+    rack.hasCarrierAt('A').should.be.true()
+    rack.hasCarrierAt('B').should.be.false()
+
+    // 2. obtain → child 로
+    const carrier = rack.obtainCarrier('A')!
+    rack.hasCarrierAt('A').should.be.true()   // child 로 존재
+    ;(rack._carrierChildAt('A') !== undefined).should.be.true()
+    rack.records.some((r: any) => r.cellId === 'A').should.be.false()   // record 빠짐
+
+    // 3. 외부로 picked (parent 변경 시뮬)
+    rack.removeComponent(carrier)
+    carrier.parent = { removeComponent: (c: any) => {} }   // mover
+    rack.hasCarrierAt('A').should.be.false()
+
+    // 4. 새 cellId 로 receiveAt
+    await rack.receiveAt('B', carrier)
+    rack.hasCarrierAt('A').should.be.false()
+    rack.hasCarrierAt('B').should.be.true()
+    rack.records.some((r: any) => r.cellId === 'B').should.be.true()
+    rack._disposed.has(carrier).should.be.true()
+  })
+})
+
+// ── Group 4: recordFromCarrier — 의미있는 필드 추출 ──────────────────────────
+
+describe('Plan A: recordFromCarrier — transform 제외, 의미 보존', () => {
+  it('transform 관련 필드는 record 에 포함되지 않음', () => {
+    const rack = new MiniRack()
+    const carrier: any = {
+      state: {
+        type: 'parcel',
+        sku: 'A',
+        qty: 3,
+        left: 100, top: 200, zPos: 50,
+        transform: 'rotate(45deg)',
+        rotation: 90,
+        scale: 2,
+        _transferSlotId: 'forks',
+        cellId: 'old-cell'
+      }
+    }
+    const r = rack.recordFromCarrier(carrier, 'new-cell')
+    r.cellId.should.equal('new-cell')   // 새 cellId 가 override
+    r.type.should.equal('parcel')
+    r.sku.should.equal('A')
+    r.qty.should.equal(3)
+    ;('left' in r).should.be.false()
+    ;('top' in r).should.be.false()
+    ;('zPos' in r).should.be.false()
+    ;('transform' in r).should.be.false()
+    ;('rotation' in r).should.be.false()
+    ;('scale' in r).should.be.false()
+    ;('_transferSlotId' in r).should.be.false()
+  })
+
+  it('cellId 가 새 값으로 갱신 — old → new 이동 의미', () => {
+    const rack = new MiniRack()
+    const carrier: any = { state: { type: 'parcel', cellId: '0-0-0' } }
+    const r = rack.recordFromCarrier(carrier, '5-5-5')
+    r.cellId.should.equal('5-5-5')
+  })
+
+  it('type 누락 시 record.type 도 undefined (caller 책임)', () => {
+    const rack = new MiniRack()
+    const carrier: any = { state: { sku: 'X' } }
+    const r = rack.recordFromCarrier(carrier, '0-0-0')
+    ;(r.type === undefined).should.be.true()
+    r.sku.should.equal('X')
+  })
+})
+
+// ── Group 5: canReceiveAt / hasCarrierAt — 두 source 모두 인식 ───────────────
+
+describe('Plan A: hasCarrierAt / canReceiveAt 가 record 와 child 모두 인식', () => {
+  it('record 만 있어도 hasCarrierAt true, canReceiveAt false', () => {
+    const rack = new MiniRack([{ cellId: 'A' }])
+    rack.hasCarrierAt('A').should.be.true()
+    rack.canReceiveAt('A').should.be.false()
+  })
+
+  it('child 만 있어도 hasCarrierAt true, canReceiveAt false', () => {
+    const rack = new MiniRack([])
+    rack.components.push({
+      placement: 'operation', state: { cellId: 'B' }, parent: rack
+    } as any)
+    rack.hasCarrierAt('B').should.be.true()
+    rack.canReceiveAt('B').should.be.false()
+  })
+
+  it('record / child 모두 없으면 hasCarrierAt false, canReceiveAt true', () => {
+    const rack = new MiniRack([])
+    rack.hasCarrierAt('C').should.be.false()
+    rack.canReceiveAt('C').should.be.true()
+  })
+})