@things-factory/board-import 10.0.0-beta.108

package/server/service/adapters/image-adapter.test.ts

@@ -0,0 +1,545 @@
+/**
+ * ImageAdapter — 단위 테스트.
+ *
+ * VLM (BoardImportAI.parseFromImage) 가 외부 의존이라 mock 으로 격리.
+ *  - detect: filename 확장자 + magic byte 검사
+ *  - parse: AI client 미등록 / vision 미지원 / 빈 응답 / 비정규 응답 정규화
+ *  - parse: 정상 응답에 대한 entity / bbox / metadata
+ */
+import { ImageAdapter } from './image-adapter'
+import { setAIClient, type BoardImportAI } from '../ai/types'
+import type { UniversalEntity } from '../types/index'
+
+// ── mock AI client ──────────────────────────────────────────────────
+
+interface MockAIOptions {
+  parseFromImage?: BoardImportAI['parseFromImage']
+}
+
+function makeMockAI(opts: MockAIOptions = {}): BoardImportAI {
+  return {
+    id: 'mock:test',
+    parseFromImage: opts.parseFromImage
+  }
+}
+
+// 매 테스트 사이 client 격리 — root jest setup 의 clearMocks 와 별개.
+afterEach(() => {
+  setAIClient(undefined)
+})
+
+// ── detect ───────────────────────────────────────────────────────────
+
+describe('ImageAdapter.detect', () => {
+  const adapter = new ImageAdapter()
+
+  test('파일명 확장자 .png/.jpg/.jpeg/.webp/.gif/.bmp 통과', async () => {
+    for (const ext of ['.png', '.jpg', '.jpeg', '.webp', '.gif', '.bmp']) {
+      expect(await adapter.detect(Buffer.alloc(0), `floor${ext}`)).toBe(true)
+    }
+  })
+
+  test('PNG magic byte 인식 (filename 없어도)', async () => {
+    const png = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0])
+    expect(await adapter.detect(png)).toBe(true)
+  })
+
+  test('JPEG magic byte 인식', async () => {
+    const jpg = Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0, 0, 0, 0])
+    expect(await adapter.detect(jpg)).toBe(true)
+  })
+
+  test('GIF magic byte 인식', async () => {
+    const gif = Buffer.from([0x47, 0x49, 0x46, 0x38, 0x39, 0x61, 0, 0])
+    expect(await adapter.detect(gif)).toBe(true)
+  })
+
+  test('WebP (RIFF...WEBP) magic byte 인식', async () => {
+    const webp = Buffer.from([
+      0x52, 0x49, 0x46, 0x46, 0x00, 0x00, 0x00, 0x00, 0x57, 0x45, 0x42, 0x50
+    ])
+    expect(await adapter.detect(webp)).toBe(true)
+  })
+
+  test('비이미지 binary (DXF 텍스트) 는 false', async () => {
+    const dxf = Buffer.from('  0\nSECTION\n  2\nHEADER\n')
+    expect(await adapter.detect(dxf)).toBe(false)
+  })
+
+  test('너무 짧은 buffer 는 false', async () => {
+    expect(await adapter.detect(Buffer.from([0x89, 0x50]))).toBe(false)
+  })
+})
+
+// ── parse: 사전 조건 검증 ────────────────────────────────────────────
+
+describe('ImageAdapter.parse — 사전 검증', () => {
+  const adapter = new ImageAdapter()
+  const png = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+
+  test('AI client 미등록 시 명확한 에러', async () => {
+    setAIClient(undefined)
+    await expect(adapter.parse(png)).rejects.toThrow(/registered BoardImportAI/)
+  })
+
+  test('parseFromImage 미구현 (vision 미지원) 시 명확한 에러', async () => {
+    setAIClient(makeMockAI({ parseFromImage: undefined }))
+    await expect(adapter.parse(png)).rejects.toThrow(/parseFromImage/)
+  })
+
+  test('string 입력은 거절 (binary 만 수용)', async () => {
+    setAIClient(makeMockAI({ parseFromImage: async () => [] }))
+    await expect(adapter.parse('not-a-buffer' as any)).rejects.toThrow(/Buffer/)
+  })
+
+  test('Uint8Array / ArrayBuffer 도 수용', async () => {
+    let calledWith: Buffer | undefined
+    setAIClient(
+      makeMockAI({
+        parseFromImage: async (buf: any) => {
+          calledWith = buf
+          return []
+        }
+      })
+    )
+    const arr = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0, 0, 0, 0])
+    await adapter.parse(arr)
+    expect(Buffer.isBuffer(calledWith)).toBe(true)
+  })
+})
+
+// ── parse: 결과 정규화 ──────────────────────────────────────────────
+
+describe('ImageAdapter.parse — VLM 응답 정규화', () => {
+  const adapter = new ImageAdapter()
+  const png = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+
+  test('빈 응답 시 entities=[] + zero bbox', async () => {
+    setAIClient(makeMockAI({ parseFromImage: async () => [] }))
+    const result = await adapter.parse(png)
+    expect(result.entities).toEqual([])
+    expect(result.bbox).toEqual({ min: { x: 0, y: 0 }, max: { x: 0, y: 0 } })
+    expect(result.units).toBe('unknown')
+    expect(result.metadata.format).toBe('image')
+    expect(result.metadata.source).toBe('vlm')
+  })
+
+  test('uid 누락 시 인덱스 기반 fallback', async () => {
+    setAIClient(
+      makeMockAI({
+        parseFromImage: async () =>
+          [
+            { kind: 'shape', position: { x: 10, y: 20 }, size: { width: 30, height: 40 } } as any,
+            { kind: 'shape', position: { x: 50, y: 60 }, size: { width: 10, height: 10 } } as any
+          ] as UniversalEntity[]
+      })
+    )
+    const result = await adapter.parse(png)
+    expect(result.entities[0].uid).toBe('img-0')
+    expect(result.entities[1].uid).toBe('img-1')
+  })
+
+  test('bbox 누락 시 position+size 로 합성', async () => {
+    setAIClient(
+      makeMockAI({
+        parseFromImage: async () =>
+          [
+            {
+              uid: 'a',
+              kind: 'shape',
+              position: { x: 10, y: 20 },
+              size: { width: 30, height: 40 }
+            } as any
+          ] as UniversalEntity[]
+      })
+    )
+    const result = await adapter.parse(png)
+    expect(result.entities[0].bbox).toEqual({ min: { x: 10, y: 20 }, max: { x: 40, y: 60 } })
+  })
+
+  test('비숫자 position 은 (0,0) 으로 fallback', async () => {
+    setAIClient(
+      makeMockAI({
+        parseFromImage: async () =>
+          [{ uid: 'a', kind: 'shape', position: { x: 'bad', y: NaN } } as any] as UniversalEntity[]
+      })
+    )
+    const result = await adapter.parse(png)
+    expect(result.entities[0].position).toEqual({ x: 0, y: 0 })
+  })
+
+  test('전체 bbox 는 모든 entity bbox 합집합', async () => {
+    setAIClient(
+      makeMockAI({
+        parseFromImage: async () =>
+          [
+            { uid: 'a', kind: 'shape', bbox: { min: { x: 0, y: 0 }, max: { x: 10, y: 10 } } } as any,
+            {
+              uid: 'b',
+              kind: 'shape',
+              bbox: { min: { x: 50, y: 30 }, max: { x: 100, y: 80 } }
+            } as any
+          ] as UniversalEntity[]
+      })
+    )
+    const result = await adapter.parse(png)
+    expect(result.bbox).toEqual({ min: { x: 0, y: 0 }, max: { x: 100, y: 80 } })
+  })
+
+  test('AI client id 가 metadata.aiClientId 로 노출', async () => {
+    setAIClient(makeMockAI({ parseFromImage: async () => [] }))
+    const result = await adapter.parse(png)
+    expect(result.metadata.aiClientId).toBe('mock:test')
+  })
+
+  test('options.context 와 options.categories 가 parseFromImage 에 전달됨', async () => {
+    let receivedOpts: any
+    setAIClient(
+      makeMockAI({
+        parseFromImage: async (_buf, opts) => {
+          receivedOpts = opts
+          return []
+        }
+      })
+    )
+    await adapter.parse(png, { context: 'factory floor', categories: ['stocker', 'agv'] } as any)
+    expect(receivedOpts.context).toBe('factory floor')
+    expect(receivedOpts.categories).toEqual(['stocker', 'agv'])
+  })
+
+  test('non-array 응답은 빈 배열로 안전 처리 (LLM 출력 신뢰 X)', async () => {
+    setAIClient(makeMockAI({ parseFromImage: async () => null as any }))
+    const result = await adapter.parse(png)
+    expect(result.entities).toEqual([])
+  })
+})
+
+// ── parse: 이미지 dimension + 좌표 정규화 보정 ─────────────────────────
+
+/**
+ * 1024 x 768 PNG 헤더 (IHDR width=0x400, height=0x300).
+ * width@16-19, height@20-23 (BE).
+ */
+function makePng1024x768(): Buffer {
+  const buf = Buffer.alloc(26)
+  buf[0] = 0x89; buf[1] = 0x50; buf[2] = 0x4e; buf[3] = 0x47
+  buf[4] = 0x0d; buf[5] = 0x0a; buf[6] = 0x1a; buf[7] = 0x0a
+  // length(4) + 'IHDR'(4) + width(4 BE) + height(4 BE) + ...
+  buf.writeUInt32BE(13, 8)
+  buf[12] = 0x49; buf[13] = 0x48; buf[14] = 0x44; buf[15] = 0x52
+  buf.writeUInt32BE(1024, 16)
+  buf.writeUInt32BE(768, 20)
+  return buf
+}
+
+describe('ImageAdapter.parse — 이미지 dimension', () => {
+  const adapter = new ImageAdapter()
+
+  test('PNG 헤더에서 width/height 읽어 metadata + parseFromImage 옵션에 주입', async () => {
+    let receivedOpts: any
+    setAIClient(
+      makeMockAI({
+        parseFromImage: async (_buf, opts) => {
+          receivedOpts = opts
+          return []
+        }
+      })
+    )
+    const result = await adapter.parse(makePng1024x768())
+    expect((receivedOpts as any).imageWidth).toBe(1024)
+    expect((receivedOpts as any).imageHeight).toBe(768)
+    expect(result.metadata.imageWidth).toBe(1024)
+    expect(result.metadata.imageHeight).toBe(768)
+  })
+
+  test('헤더만 있는 짧은 buffer 도 안전 — dimension 못 읽으면 undefined', async () => {
+    let receivedOpts: any
+    setAIClient(
+      makeMockAI({
+        parseFromImage: async (_buf, opts) => {
+          receivedOpts = opts
+          return []
+        }
+      })
+    )
+    // 짧은 PNG signature 만 — IHDR 없음 → undefined
+    const tiny = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+    await adapter.parse(tiny)
+    expect((receivedOpts as any).imageWidth).toBeUndefined()
+    expect((receivedOpts as any).imageHeight).toBeUndefined()
+  })
+})
+
+describe('ImageAdapter.parse — 좌표 정규화 자동 보정', () => {
+  const adapter = new ImageAdapter()
+
+  test('모든 좌표가 [0..1] 범위면 image dimension 으로 곱해서 픽셀 좌표로 보정', async () => {
+    setAIClient(
+      makeMockAI({
+        parseFromImage: async () =>
+          [
+            {
+              uid: 'a',
+              kind: 'shape',
+              position: { x: 0.1, y: 0.2 },
+              size: { width: 0.05, height: 0.05 },
+              bbox: { min: { x: 0.1, y: 0.2 }, max: { x: 0.15, y: 0.25 } }
+            } as any
+          ] as UniversalEntity[]
+      })
+    )
+    const result = await adapter.parse(makePng1024x768())
+    const e = result.entities[0]
+    // 1024 x 768 로 곱해진 값
+    expect(e.position.x).toBeCloseTo(102.4)
+    expect(e.position.y).toBeCloseTo(153.6)
+    expect(e.size!.width).toBeCloseTo(51.2)
+    expect(e.size!.height).toBeCloseTo(38.4)
+    expect(e.bbox.max.x).toBeCloseTo(153.6)
+    expect(e.bbox.max.y).toBeCloseTo(192)
+  })
+
+  test('좌표 중 하나라도 2 초과면 정규화 좌표가 아니라고 판단 — 그대로 보존', async () => {
+    setAIClient(
+      makeMockAI({
+        parseFromImage: async () =>
+          [
+            {
+              uid: 'a',
+              kind: 'shape',
+              position: { x: 100, y: 200 },
+              size: { width: 50, height: 50 },
+              bbox: { min: { x: 100, y: 200 }, max: { x: 150, y: 250 } }
+            } as any
+          ] as UniversalEntity[]
+      })
+    )
+    const result = await adapter.parse(makePng1024x768())
+    const e = result.entities[0]
+    expect(e.position.x).toBe(100)
+    expect(e.size!.width).toBe(50)
+    expect(e.bbox.max.x).toBe(150)
+  })
+
+  test('image dimension 을 못 읽었으면 정규화 의심돼도 그대로 (스케일 못 함)', async () => {
+    setAIClient(
+      makeMockAI({
+        parseFromImage: async () =>
+          [
+            {
+              uid: 'a',
+              kind: 'shape',
+              position: { x: 0.1, y: 0.2 },
+              size: { width: 0.05, height: 0.05 },
+              bbox: { min: { x: 0.1, y: 0.2 }, max: { x: 0.15, y: 0.25 } }
+            } as any
+          ] as UniversalEntity[]
+      })
+    )
+    // dimension 못 읽는 짧은 PNG signature
+    const tiny = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])
+    const result = await adapter.parse(tiny)
+    expect(result.entities[0].position.x).toBeCloseTo(0.1)
+  })
+})
+
+// ── parse: 1-pass structured response (viewType + confidence + reasoning) ──
+
+describe('ImageAdapter.parse — 1-pass structured response', () => {
+  const adapter = new ImageAdapter()
+
+  test('VLM 이 ImageAnalysis 형태로 반환 시 viewType / confidence / reasoning 이 metadata 노출', async () => {
+    // top-down 으로 테스트 — perspective-3d 는 grid fallback 으로 좌표가 override 되어
+    // metadata 노출과 좌표 보존을 한 번에 확인하기 어렵다. metadata 노출만 검증.
+    setAIClient(
+      makeMockAI({
+        parseFromImage: async () =>
+          ({
+            viewType: 'top-down',
+            confidence: 0.85,
+            reasoning: 'orthographic floor plan from above',
+            entities: [
+              {
+                uid: 'a',
+                kind: 'shape',
+                position: { x: 100, y: 200 },
+                size: { width: 50, height: 60 },
+                bbox: { min: { x: 100, y: 200 }, max: { x: 150, y: 260 } }
+              }
+            ]
+          } as any)
+      })
+    )
+    const result = await adapter.parse(makePng1024x768())
+    expect(result.metadata.viewType).toBe('top-down')
+    expect(result.metadata.viewTypeConfidence).toBe(0.85)
+    expect(result.metadata.viewTypeReasoning).toBe('orthographic floor plan from above')
+    expect(result.entities.length).toBe(1)
+    expect(result.entities[0].position.x).toBe(100)
+  })
+
+  test('viewType 누락 시 기본 top-down', async () => {
+    setAIClient(
+      makeMockAI({
+        parseFromImage: async () =>
+          ({ entities: [{ uid: 'a', kind: 'shape', position: { x: 10, y: 20 } }] } as any)
+      })
+    )
+    const result = await adapter.parse(makePng1024x768())
+    expect(result.metadata.viewType).toBe('top-down')
+  })
+
+  test('options.viewType 강제 시 VLM 응답 무시하고 그것으로', async () => {
+    setAIClient(
+      makeMockAI({
+        parseFromImage: async () =>
+          ({
+            viewType: 'top-down',
+            confidence: 0.9,
+            entities: [{ uid: 'a', kind: 'shape', position: { x: 10, y: 20 } }]
+          } as any)
+      })
+    )
+    const result = await adapter.parse(makePng1024x768(), { viewType: 'perspective-3d' } as any)
+    expect(result.metadata.viewType).toBe('perspective-3d')
+  })
+
+  test('userPrompt 가 parseFromImage 옵션으로 흘러감', async () => {
+    let receivedOpts: any
+    setAIClient(
+      makeMockAI({
+        parseFromImage: async (_buf, opts) => {
+          receivedOpts = opts
+          return [] as any
+        }
+      })
+    )
+    await adapter.parse(makePng1024x768(), {
+      userPrompt: 'fab lithography zone, central rectangles are stockers'
+    } as any)
+    expect((receivedOpts as any).userPrompt).toBe(
+      'fab lithography zone, central rectangles are stockers'
+    )
+  })
+
+  test('userPrompt 가 metadata 에도 노출 (디버깅)', async () => {
+    setAIClient(makeMockAI({ parseFromImage: async () => [] as any }))
+    const result = await adapter.parse(makePng1024x768(), { userPrompt: 'hint' } as any)
+    expect(result.metadata.userPrompt).toBe('hint')
+  })
+
+  test('perspective-3d 모드는 좌표 추론 신뢰 못 하므로 grid 로 fallback', async () => {
+    // VLM 이 entity 좌표를 반환해도 grid layout 이 override (F-7).
+    // size 는 보존, position 은 격자 cell 로.
+    setAIClient(
+      makeMockAI({
+        parseFromImage: async () =>
+          ({
+            viewType: 'perspective-3d',
+            confidence: 0.9,
+            entities: [
+              {
+                uid: 'a',
+                kind: 'shape',
+                position: { x: 999, y: 888 }, // 임의 좌표
+                size: { width: 50, height: 80 },
+                bbox: { min: { x: 999, y: 888 }, max: { x: 1049, y: 968 } }
+              },
+              {
+                uid: 'b',
+                kind: 'shape',
+                position: { x: 100, y: 200 },
+                size: { width: 60, height: 60 },
+                bbox: { min: { x: 100, y: 200 }, max: { x: 160, y: 260 } }
+              }
+            ]
+          } as any)
+      })
+    )
+    const result = await adapter.parse(makePng1024x768())
+    // 첫 entity 는 (0, 0), 두번째는 grid 다음 cell
+    expect(result.entities[0].position.x).toBe(0)
+    expect(result.entities[0].position.y).toBe(0)
+    // size 는 보존
+    expect(result.entities[0].size!.width).toBe(50)
+    expect(result.entities[0].size!.height).toBe(80)
+    // 두 번째는 cols=ceil(sqrt(2))=2 라 col=1, row=0
+    expect(result.entities[1].position.y).toBe(0)
+    expect(result.entities[1].position.x).toBeGreaterThan(0)
+    // metadata 에 layout method 표시
+    expect(result.metadata.layoutMethod).toBe('grid')
+  })
+
+  test('top-down 은 grid fallback 미적용 — VLM 좌표 그대로', async () => {
+    setAIClient(
+      makeMockAI({
+        parseFromImage: async () =>
+          ({
+            viewType: 'top-down',
+            confidence: 0.95,
+            entities: [
+              {
+                uid: 'a',
+                kind: 'shape',
+                position: { x: 100, y: 200 },
+                size: { width: 50, height: 60 }
+              }
+            ]
+          } as any)
+      })
+    )
+    const result = await adapter.parse(makePng1024x768())
+    expect(result.entities[0].position.x).toBe(100)
+    expect(result.entities[0].position.y).toBe(200)
+    expect(result.metadata.layoutMethod).toBeUndefined()
+  })
+
+  test('photo 도 grid fallback 적용', async () => {
+    setAIClient(
+      makeMockAI({
+        parseFromImage: async () =>
+          ({
+            viewType: 'photo',
+            confidence: 0.7,
+            entities: [
+              { uid: 'a', kind: 'shape', position: { x: 999, y: 888 }, size: { width: 40, height: 40 } }
+            ]
+          } as any)
+      })
+    )
+    const result = await adapter.parse(makePng1024x768())
+    expect(result.entities[0].position).toEqual({ x: 0, y: 0 })
+    expect(result.metadata.layoutMethod).toBe('grid')
+  })
+
+  test('grid 는 4개 entity 시 2x2 배치', async () => {
+    setAIClient(
+      makeMockAI({
+        parseFromImage: async () =>
+          ({
+            viewType: 'perspective-3d',
+            confidence: 0.8,
+            entities: Array.from({ length: 4 }, (_, i) => ({
+              uid: `e${i}`,
+              kind: 'shape',
+              position: { x: 0, y: 0 },
+              size: { width: 50, height: 50 }
+            }))
+          } as any)
+      })
+    )
+    const result = await adapter.parse(makePng1024x768())
+    expect(result.entities[0].position.x).toBe(0)
+    expect(result.entities[0].position.y).toBe(0)
+    // ceil(sqrt(4))=2 cols
+    // entity 1: col=1, row=0
+    expect(result.entities[1].position.y).toBe(0)
+    expect(result.entities[1].position.x).toBeGreaterThan(0)
+    // entity 2: col=0, row=1
+    expect(result.entities[2].position.x).toBe(0)
+    expect(result.entities[2].position.y).toBeGreaterThan(0)
+    // entity 3: col=1, row=1
+    expect(result.entities[3].position.x).toBeGreaterThan(0)
+    expect(result.entities[3].position.y).toBeGreaterThan(0)
+  })
+})