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

package/server/service/extraction/extraction.test.ts

@@ -0,0 +1,374 @@
+/**
+ * 하이브리드 추출 — 단위 테스트.
+ *
+ * 커버:
+ *  - GridSnapLayoutRefiner: x/y 클러스터 정렬, 3-클러스터, bbox 평행이동, grid 스냅,
+ *    빈배열, 원본 비파괴, size 없는 엔티티 autoTolerance 폴백.
+ *  - source-router: 확장자별 detectSourceKind, register/get/clear.
+ *  - extractHybrid(mock 추출기): fuse 라벨앵커(가장 가까운 라벨), 스케일 변환, 다중 시안,
+ *    refiner 적용.
+ *  - extractHybrid(에러): 미등록 set → throw, stub(CV) → 미구현 throw.
+ *  - extractHybrid(벡터/DXF): DxfAdapter 흡수 무손실(layer/kind) + 단일 시안.
+ */
+import {
+  GridSnapLayoutRefiner,
+  VlmRecognizer,
+  LabelScaleCalibrator,
+  extractHybrid,
+  registerDefaultExtractors,
+  registerExtractorSet,
+  clearExtractorSets,
+  detectSourceKind,
+  getExtractorSet
+} from './index'
+import type {
+  GeometricPrimitive,
+  Label,
+  ScaleResult,
+  VariantDraft,
+  GeometryExtractor,
+  LabelExtractor,
+  ScaleCalibrator,
+  VariantStrategy
+} from './index'
+import type { UniversalEntity } from '../types/index'
+import type { AIClient } from '@things-factory/ai-client-base'
+
+// ── helpers / mocks ──────────────────────────────────────────────────────────
+function ent(uid: string, x: number, y: number, w = 10, h = 10): UniversalEntity {
+  return {
+    uid,
+    kind: 'shape',
+    position: { x, y },
+    size: { width: w, height: h },
+    bbox: { min: { x, y }, max: { x: x + w, y: y + h } },
+    attribs: {}
+  }
+}
+const rectPrim = (x: number, y: number, w: number, h: number): GeometricPrimitive => ({
+  kind: 'rect',
+  bbox: { min: { x, y }, max: { x: x + w, y: y + h } }
+})
+const label = (text: string, x: number, y: number, w = 4, h = 4): Label => ({
+  text,
+  bbox: { min: { x, y }, max: { x: x + w, y: y + h } }
+})
+const mockGeom = (prims: GeometricPrimitive[]): GeometryExtractor => ({ id: 'mock-geom', extract: async () => prims })
+const mockOcr = (labels: Label[]): LabelExtractor => ({ id: 'mock-ocr', extract: async () => labels })
+const mockScale = (s: ScaleResult): ScaleCalibrator => ({ id: 'mock-scale', calibrate: async () => s })
+const mockVariants = (drafts: VariantDraft[]): VariantStrategy => ({ id: 'mock-var', interpret: async () => drafts })
+const mockClient = (gen: (prompt: string) => any): AIClient =>
+  ({
+    id: 'mock:test',
+    chat: async () => '',
+    generateJSON: async (prompt: any) => gen(typeof prompt === 'string' ? prompt : JSON.stringify(prompt))
+  } as AIClient)
+const prim = (w = 50, h = 80): GeometricPrimitive => ({ kind: 'rect', bbox: { min: { x: 0, y: 0 }, max: { x: w, y: h } } })
+
+beforeEach(() => clearExtractorSets()) // 전역 레지스트리 격리
+
+// ── GridSnapLayoutRefiner ──────────────────────────────────────────────────────
+describe('GridSnapLayoutRefiner', () => {
+  it('근접 x 좌표를 클러스터 평균으로 정렬', () => {
+    const out = new GridSnapLayoutRefiner({ alignTolerance: 5 }).refine([ent('a', 10, 0), ent('b', 12, 0), ent('c', 90, 0)])
+    expect(out[0].position.x).toBeCloseTo(11)
+    expect(out[1].position.x).toBeCloseTo(11)
+    expect(out[2].position.x).toBeCloseTo(90)
+  })
+
+  it('y 좌표도 동일하게 정렬', () => {
+    const out = new GridSnapLayoutRefiner({ alignTolerance: 5 }).refine([ent('a', 0, 100), ent('b', 0, 103), ent('c', 0, 200)])
+    expect(out[0].position.y).toBeCloseTo(101.5)
+    expect(out[1].position.y).toBeCloseTo(101.5)
+    expect(out[2].position.y).toBeCloseTo(200)
+  })
+
+  it('3개 클러스터 각각 평균으로 (단일연결)', () => {
+    const out = new GridSnapLayoutRefiner({ alignTolerance: 3 }).refine([
+      ent('a', 0, 0), ent('b', 2, 0), ent('c', 50, 0), ent('d', 51, 0), ent('e', 100, 0)
+    ])
+    expect(out[0].position.x).toBeCloseTo(1)
+    expect(out[1].position.x).toBeCloseTo(1)
+    expect(out[2].position.x).toBeCloseTo(50.5)
+    expect(out[3].position.x).toBeCloseTo(50.5)
+    expect(out[4].position.x).toBeCloseTo(100)
+  })
+
+  it('정렬 시 bbox 평행이동 + size 보존', () => {
+    const out = new GridSnapLayoutRefiner({ alignTolerance: 5 }).refine([ent('a', 10, 0, 20, 20), ent('b', 14, 0, 20, 20)])
+    expect(out[0].position.x).toBeCloseTo(12)
+    expect(out[0].bbox.min.x).toBeCloseTo(12)
+    expect(out[0].bbox.max.x).toBeCloseTo(32)
+    expect(out[0].size!.width).toBe(20)
+  })
+
+  it('grid 스냅 (align off)', () => {
+    const out = new GridSnapLayoutRefiner({ align: false, grid: 10 }).refine([ent('a', 7, 23)])
+    expect(out[0].position).toEqual({ x: 10, y: 20 })
+  })
+
+  it('빈 배열 안전 + 원본 비파괴(clone)', () => {
+    expect(new GridSnapLayoutRefiner().refine([])).toEqual([])
+    const src = [ent('a', 10, 0)]
+    new GridSnapLayoutRefiner({ grid: 100 }).refine(src)
+    expect(src[0].position.x).toBe(10)
+  })
+
+  it('size 없는 엔티티 — autoTolerance 좌표 spread 폴백', () => {
+    const noSize = (uid: string, x: number): UniversalEntity => ({
+      uid, kind: 'text', position: { x, y: 0 }, bbox: { min: { x, y: 0 }, max: { x, y: 0 } }, attribs: {}
+    })
+    // spread=1000 → tol=2% =20. {0,5} 묶이고 1000 독립.
+    const out = new GridSnapLayoutRefiner().refine([noSize('a', 0), noSize('b', 5), noSize('c', 1000)])
+    expect(out[0].position.x).toBeCloseTo(2.5)
+    expect(out[1].position.x).toBeCloseTo(2.5)
+    expect(out[2].position.x).toBeCloseTo(1000)
+  })
+})
+
+// ── source-router ──────────────────────────────────────────────────────────────
+describe('source-router', () => {
+  it('detectSourceKind — 확장자별 분류', async () => {
+    expect(await detectSourceKind('', 'a.dxf')).toBe('vector')
+    expect(await detectSourceKind('', 'a.svg')).toBe('vector')
+    expect(await detectSourceKind('', 'a.ifc')).toBe('vector')
+    expect(await detectSourceKind('', 'a.pdf')).toBe('vector')
+    expect(await detectSourceKind('', 'a.png')).toBe('raster-topdown')
+    expect(await detectSourceKind('', 'a.JPG')).toBe('raster-topdown') // 대소문자 무관
+    expect(await detectSourceKind('', 'a.zip')).toBe('unknown')
+    expect(await detectSourceKind('')).toBe('unknown') // 파일명 없음
+  })
+
+  it('register/get/clear', () => {
+    expect(getExtractorSet('photo')).toBeUndefined()
+    registerExtractorSet('photo', () => ({ geometry: mockGeom([]) }))
+    expect(getExtractorSet('photo')?.geometry.id).toBe('mock-geom')
+    clearExtractorSets()
+    expect(getExtractorSet('photo')).toBeUndefined()
+  })
+})
+
+// ── extractHybrid (mock 추출기로 우리 로직 검증) ──────────────────────────────────
+describe('extractHybrid — 융합/스케일/시안', () => {
+  it('fuse: 각 프리미티브가 *가장 가까운* 라벨로 name 앵커', async () => {
+    registerExtractorSet('raster-topdown', () => ({
+      geometry: mockGeom([rectPrim(0, 0, 10, 10), rectPrim(100, 100, 10, 10)]),
+      labels: mockOcr([label('STK_01', 1, 1), label('STK_02', 101, 101)])
+    }))
+    const res = await extractHybrid('x', {}, 'plan.png')
+    expect(res.sourceKind).toBe('raster-topdown')
+    expect(res.entities.map(e => e.attribs.name)).toEqual(['STK_01', 'STK_02'])
+  })
+
+  it('scale: unitsPerPixel/origin 으로 위치·크기·bbox 변환', async () => {
+    registerExtractorSet('raster-topdown', () => ({
+      geometry: mockGeom([rectPrim(10, 20, 30, 40)]),
+      scale: mockScale({ unitsPerPixel: 2, origin: { x: 10, y: 20 } })
+    }))
+    const res = await extractHybrid('x', {}, 'plan.png')
+    const e = res.entities[0]
+    expect(e.position).toEqual({ x: 0, y: 0 }) // (10-10,20-20)*2
+    expect(e.size).toEqual({ width: 60, height: 80 }) // 30*2, 40*2
+    expect(e.bbox.max).toEqual({ x: 60, y: 80 })
+  })
+
+  it('variants: 전략이 N 시안 → variants 보존, entities=variants[0]', async () => {
+    registerExtractorSet('raster-topdown', () => ({
+      geometry: mockGeom([rectPrim(0, 0, 10, 10)]),
+      variants: mockVariants([
+        { id: 'eq', label: '장비', entities: [ent('a', 0, 0)] },
+        { id: 'tr', label: '운송', entities: [ent('b', 5, 5)] },
+        { id: 'rg', label: '구역', entities: [ent('c', 9, 9)] }
+      ])
+    }))
+    const res = await extractHybrid('x', {}, 'plan.png')
+    expect(res.variants.map(v => v.id)).toEqual(['eq', 'tr', 'rg'])
+    expect(res.entities[0].uid).toBe('a') // default = variants[0]
+  })
+
+  it('refiner 가 시안 entities 에 적용됨', async () => {
+    registerExtractorSet('raster-topdown', () => ({
+      geometry: mockGeom([rectPrim(7, 7, 10, 10)]),
+      refiner: new GridSnapLayoutRefiner({ align: false, grid: 10 })
+    }))
+    const res = await extractHybrid('x', {}, 'plan.png')
+    expect(res.entities[0].position).toEqual({ x: 10, y: 10 }) // 7→10 grid snap
+  })
+
+  it('recognizer 가 bare 프리미티브에 semanticType 부여 (라벨 신호 전달)', async () => {
+    registerExtractorSet('raster-topdown', () => ({
+      geometry: mockGeom([rectPrim(0, 0, 50, 80)]),
+      labels: mockOcr([label('STK_001', 1, 1)]),
+      recognizer: new VlmRecognizer(mockClient(() => ({ componentType: 'stocker', confidence: 0.9 })))
+    }))
+    const res = await extractHybrid('x', {}, 'plan.png')
+    expect(res.entities[0].attribs.name).toBe('STK_001')
+    expect(res.entities[0].attribs.semanticType).toBe('stocker')
+    expect(res.entities[0].attribs.confidence).toBeCloseTo(0.9)
+  })
+
+  it('실 LabelScaleCalibrator 가 치수 라벨로 entities 스케일', async () => {
+    registerExtractorSet('raster-topdown', () => ({
+      geometry: mockGeom([rectPrim(0, 0, 200, 100)]),
+      labels: mockOcr([label('5000mm', 0, 0)]),
+      scale: new LabelScaleCalibrator()
+    }))
+    const res = await extractHybrid('x', {}, 'plan.png')
+    // 5000mm / extent 200px = 25 mm/px → 200px*25 = 5000
+    expect(res.entities[0].size!.width).toBeCloseTo(5000)
+    expect(res.entities[0].size!.height).toBeCloseTo(2500)
+  })
+})
+
+// ── VlmRecognizer (mock AIClient) ────────────────────────────────────────────────
+describe('VlmRecognizer', () => {
+  it('응답을 componentType/confidence/attribs 로 매핑', async () => {
+    const r = new VlmRecognizer(mockClient(() => ({ componentType: 'stocker', confidence: 0.9, attribs: { capacity: 10 } })))
+    expect(await r.recognize(prim())).toEqual({ componentType: 'stocker', confidence: 0.9, attribs: { capacity: 10 } })
+  })
+
+  it('카탈로그 그라운딩 — 카탈로그 밖 타입 거부(undefined) + 신뢰도 상한 0.3', async () => {
+    const r = new VlmRecognizer(mockClient(() => ({ componentType: 'unicorn', confidence: 0.95 })))
+    const out = await r.recognize(prim(), { catalog: ['stocker', 'conveyor'] })
+    expect(out.componentType).toBeUndefined()
+    expect(out.confidence).toBeLessThanOrEqual(0.3)
+  })
+
+  it('카탈로그 안 타입은 유지', async () => {
+    const r = new VlmRecognizer(mockClient(() => ({ componentType: 'conveyor', confidence: 0.8 })))
+    const out = await r.recognize(prim(), { catalog: ['stocker', 'conveyor'] })
+    expect(out.componentType).toBe('conveyor')
+    expect(out.confidence).toBeCloseTo(0.8)
+  })
+
+  it('confidence 기본 0.5 + 범위 클램프(0..1)', async () => {
+    expect((await new VlmRecognizer(mockClient(() => ({ componentType: 'x' }))).recognize(prim())).confidence).toBe(0.5)
+    expect((await new VlmRecognizer(mockClient(() => ({ componentType: 'x', confidence: 9 }))).recognize(prim())).confidence).toBe(1)
+    expect((await new VlmRecognizer(mockClient(() => ({ componentType: 'x', confidence: -2 }))).recognize(prim())).confidence).toBe(0)
+  })
+
+  it('componentType null/빈문자 → undefined + 신뢰도 상한', async () => {
+    const out = await new VlmRecognizer(mockClient(() => ({ componentType: null, confidence: 0.9 }))).recognize(prim())
+    expect(out.componentType).toBeUndefined()
+    expect(out.confidence).toBeLessThanOrEqual(0.3)
+  })
+
+  it('AIClient 없으면 명확히 throw', async () => {
+    await expect(new VlmRecognizer().recognize(prim())).rejects.toThrow(/AIClient/)
+  })
+
+  it('프롬프트에 region 신호(라벨·크기) + 카탈로그 포함', async () => {
+    let captured = ''
+    const r = new VlmRecognizer(
+      mockClient(p => {
+        captured = p
+        return { componentType: 'stocker' }
+      })
+    )
+    const region: GeometricPrimitive = { kind: 'rect', bbox: { min: { x: 0, y: 0 }, max: { x: 50, y: 80 } }, meta: { label: 'STK_001' } }
+    await r.recognize(region, { catalog: ['stocker'] })
+    expect(captured).toContain('STK_001')
+    expect(captured).toContain('50x80')
+    expect(captured).toContain('stocker')
+  })
+
+  it('벡터 엔티티의 attribs.name 을 라벨 신호로 사용', async () => {
+    let captured = ''
+    const r = new VlmRecognizer(
+      mockClient(p => {
+        captured = p
+        return { componentType: 'dock' }
+      })
+    )
+    const e = ent('e', 0, 0)
+    e.attribs.name = 'DOCK_A'
+    await r.recognize({ kind: 'rect', bbox: e.bbox, entity: e })
+    expect(captured).toContain('DOCK_A')
+  })
+})
+
+// ── LabelScaleCalibrator ─────────────────────────────────────────────────────────
+describe('LabelScaleCalibrator', () => {
+  const calib = new LabelScaleCalibrator()
+
+  it('명시 reference 최우선 → unitsPerPixel=units/pixels, 단위/origin 반영', async () => {
+    const r = await calib.calibrate([], [rectPrim(10, 20, 50, 50)], { scaleReference: { pixels: 100, units: 10, unit: 'm' } })
+    expect(r.unitsPerPixel).toBeCloseTo(0.1)
+    expect(r.units).toBe('m')
+    expect(r.origin).toEqual({ x: 10, y: 20 })
+  })
+
+  it('치수 라벨 휴리스틱 — maxDim(mm) ÷ 최대 픽셀범위', async () => {
+    // extent=200, 5000mm → 25 mm/px, units mm
+    const r = await calib.calibrate([label('5000mm', 0, 0)], [rectPrim(0, 0, 200, 100)])
+    expect(r.unitsPerPixel).toBeCloseTo(25)
+    expect(r.units).toBe('mm')
+  })
+
+  it('단위 추론 — dominant 단위로 환산', async () => {
+    // extent=100, dims {1m,2m,30cm} → dominant m, maxMm 2000 → 20mm/px → 0.02 m/px
+    const r = await calib.calibrate(
+      [label('1m', 0, 0), label('2m', 0, 0), label('30cm', 0, 0)],
+      [rectPrim(0, 0, 100, 100)]
+    )
+    expect(r.units).toBe('m')
+    expect(r.unitsPerPixel).toBeCloseTo(0.02)
+  })
+
+  it('치수/ref 없음 → 폴백(unitsPerPixel=1, units=unknown) + origin', async () => {
+    const r = await calib.calibrate([], [rectPrim(5, 5, 10, 10)])
+    expect(r).toEqual({ unitsPerPixel: 1, origin: { x: 5, y: 5 }, units: 'unknown' })
+  })
+
+  it('비치수 라벨(STK_001) 은 무시 → 폴백', async () => {
+    const r = await calib.calibrate([label('STK_001', 0, 0), label('AGV-3', 0, 0)], [rectPrim(0, 0, 50, 50)])
+    expect(r.unitsPerPixel).toBe(1)
+    expect(r.units).toBe('unknown')
+  })
+
+  it('프리미티브 없으면 origin {0,0}', async () => {
+    const r = await calib.calibrate([], [])
+    expect(r.origin).toEqual({ x: 0, y: 0 })
+  })
+})
+
+// ── extractHybrid 에러/스텁 경로 ──────────────────────────────────────────────────
+describe('extractHybrid — 에러 경로', () => {
+  it('미등록 소스 → 명확한 throw', async () => {
+    await expect(extractHybrid('x', {}, 'plan.png')).rejects.toThrow(/미등록/)
+  })
+
+  it('미지원 확장자 → unknown → throw', async () => {
+    await expect(extractHybrid('x', {}, 'a.zip')).rejects.toThrow(/'unknown'/)
+  })
+
+  it('stub(CvGeometry) → 미구현 throw (실수로 live 붙으면 즉시 드러남)', async () => {
+    registerDefaultExtractors() // raster-topdown 은 CvGeometryExtractor(stub)
+    await expect(extractHybrid('x', {}, 'plan.png')).rejects.toThrow(/미구현/)
+  })
+})
+
+// ── extractHybrid 벡터(DXF) end-to-end ─────────────────────────────────────────
+describe('extractHybrid — 벡터(DXF) 경로', () => {
+  const DXF = [
+    '0', 'SECTION', '2', 'ENTITIES',
+    '0', 'LINE', '8', 'WALL', '10', '0', '20', '0', '11', '100', '21', '0',
+    '0', 'LINE', '8', 'WALL', '10', '0', '20', '0', '11', '0', '21', '50',
+    '0', 'ENDSEC', '0', 'EOF'
+  ].join('\n')
+
+  beforeEach(() => registerDefaultExtractors())
+
+  it('sourceKind=vector', async () => {
+    expect((await extractHybrid(DXF, {}, 'test.dxf')).sourceKind).toBe('vector')
+  })
+
+  it('DXF LINE 2개 → 무손실(layer/kind 보존) + 단일 default 시안', async () => {
+    const res = await extractHybrid(DXF, {}, 'test.dxf')
+    expect(res.entities.length).toBe(2)
+    expect(res.entities.every(e => e.attribs.layer === 'WALL')).toBe(true)
+    expect(res.entities.every(e => e.kind === 'path')).toBe(true)
+    expect(res.variants.length).toBe(1)
+    expect(res.variants[0].id).toBe('default')
+  })
+})

package/server/service/extraction/index.ts

@@ -0,0 +1,51 @@
+/*
+ * 하이브리드 추출 모듈 (Phase Board-AI §3.8) — barrel.
+ *
+ * 순수 *추가* 모듈. 기존 어댑터/파이프라인(ImageAdapter, stage1-4)은 무변경.
+ * 본격 테스트 단계에서 나머지 stub → 실 impl 로 교체하고 ImageAdapter 를 흡수.
+ *
+ * 현재 실구현: VectorGeometryExtractor(DXF), GridSnapLayoutRefiner, VlmRecognizer(AI client),
+ *             LabelScaleCalibrator. 아직 stub: CvGeometryExtractor, CloudOcrLabelExtractor.
+ */
+export * from './contracts'
+export * from './source-router'
+export * from './pipeline'
+export { VectorGeometryExtractor } from './vector-geometry'
+export { GridSnapLayoutRefiner, type LayoutRefineOptions } from './layout-refiner'
+export { VlmRecognizer } from './vlm-recognizer'
+export { LabelScaleCalibrator } from './label-scale-calibrator'
+export { CvGeometryExtractor, CloudOcrLabelExtractor, IdentityLayoutRefiner } from './stubs'
+
+import { registerExtractorSet } from './source-router'
+import { VectorGeometryExtractor } from './vector-geometry'
+import { GridSnapLayoutRefiner } from './layout-refiner'
+import { VlmRecognizer } from './vlm-recognizer'
+import { LabelScaleCalibrator } from './label-scale-calibrator'
+import { CvGeometryExtractor, CloudOcrLabelExtractor } from './stubs'
+
+/**
+ * 기본 추출기 묶음 등록. *명시 호출 시에만* 등록 (side-effect 없음).
+ *  - vector       : VectorGeometryExtractor(실) + GridSnapLayoutRefiner(실) → 지금 동작.
+ *  - raster-topdown / photo : VlmRecognizer·LabelScaleCalibrator·GridSnapLayoutRefiner 는 실,
+ *    CV(geometry)/OCR 은 아직 stub. CvGeometry stub 이 먼저 throw 하므로 raster 경로 전체는
+ *    CV 구현 후 동작.
+ * 본격 테스트 단계에서 남은 stub(CV/OCR)을 실 impl 로 교체.
+ */
+export function registerDefaultExtractors(): void {
+  registerExtractorSet('vector', () => ({
+    geometry: new VectorGeometryExtractor(),
+    refiner: new GridSnapLayoutRefiner()
+  }))
+  registerExtractorSet('raster-topdown', () => ({
+    geometry: new CvGeometryExtractor(),
+    labels: new CloudOcrLabelExtractor(),
+    recognizer: new VlmRecognizer(),
+    scale: new LabelScaleCalibrator(),
+    refiner: new GridSnapLayoutRefiner()
+  }))
+  registerExtractorSet('photo', () => ({
+    geometry: new CvGeometryExtractor(),
+    recognizer: new VlmRecognizer(),
+    refiner: new GridSnapLayoutRefiner()
+  }))
+}

package/server/service/extraction/label-scale-calibrator.ts

@@ -0,0 +1,124 @@
+/*
+ * LabelScaleCalibrator — 픽셀 좌표를 실제 단위로 변환할 스케일을 도출 (Phase Board-AI §3.8).
+ *
+ * 우선순위:
+ *   1) 명시 reference (ctx.scaleReference: 알려진 픽셀 span = 실제 길이) — 가장 정확.
+ *   2) 치수 라벨 휴리스틱 — 가장 큰 치수값(mm 환산) ÷ 레이아웃 최대 픽셀 범위. ballpark.
+ *      (정밀 px↔real 페어링엔 치수선 기하가 필요 — 추후. 여기선 근사.)
+ *   3) 폴백 — 항등 스케일(unitsPerPixel=1), 단위는 라벨에서 추론 or 'unknown'.
+ *
+ * origin 은 항상 프리미티브 묶음의 좌상단(min 코너) → 좌표를 0 기준 상대화.
+ * 순수·결정적 (외부 호출 없음).
+ */
+import type { ScaleCalibrator, ScaleResult, GeometricPrimitive, Label, ExtractionContext } from './contracts'
+
+type Unit = 'mm' | 'cm' | 'm' | 'inch'
+const UNIT_TO_MM: Record<Unit, number> = { mm: 1, cm: 10, m: 1000, inch: 25.4 }
+
+interface Dim {
+  value: number
+  unit: Unit
+}
+
+export class LabelScaleCalibrator implements ScaleCalibrator {
+  readonly id = 'label-scale'
+
+  async calibrate(
+    labels: Label[],
+    primitives: GeometricPrimitive[],
+    ctx?: ExtractionContext
+  ): Promise<ScaleResult> {
+    const origin = layoutOrigin(primitives)
+    const dims = parseDimensions(labels)
+    const labelUnit = dominantUnit(dims)
+
+    // 1) 명시 reference 최우선.
+    const ref = ctx?.scaleReference
+    if (ref && ref.pixels > 0 && Number.isFinite(ref.units)) {
+      return {
+        unitsPerPixel: ref.units / ref.pixels,
+        origin,
+        units: normUnit(ref.unit) ?? labelUnit ?? 'unknown'
+      }
+    }
+
+    // 2) 치수 라벨 휴리스틱.
+    const extent = layoutExtentPx(primitives)
+    if (dims.length > 0 && extent > 0 && labelUnit) {
+      const maxMm = Math.max(...dims.map(d => d.value * UNIT_TO_MM[d.unit]))
+      const mmPerPixel = maxMm / extent
+      return { unitsPerPixel: mmPerPixel / UNIT_TO_MM[labelUnit], origin, units: labelUnit }
+    }
+
+    // 3) 폴백.
+    return { unitsPerPixel: 1, origin, units: labelUnit ?? 'unknown' }
+  }
+}
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+function layoutOrigin(primitives: GeometricPrimitive[]): { x: number; y: number } {
+  if (!primitives.length) return { x: 0, y: 0 }
+  let minX = Infinity
+  let minY = Infinity
+  for (const p of primitives) {
+    if (p.bbox.min.x < minX) minX = p.bbox.min.x
+    if (p.bbox.min.y < minY) minY = p.bbox.min.y
+  }
+  return { x: minX, y: minY }
+}
+
+function layoutExtentPx(primitives: GeometricPrimitive[]): number {
+  if (!primitives.length) return 0
+  let minX = Infinity
+  let minY = Infinity
+  let maxX = -Infinity
+  let maxY = -Infinity
+  for (const p of primitives) {
+    minX = Math.min(minX, p.bbox.min.x)
+    minY = Math.min(minY, p.bbox.min.y)
+    maxX = Math.max(maxX, p.bbox.max.x)
+    maxY = Math.max(maxY, p.bbox.max.y)
+  }
+  return Math.max(maxX - minX, maxY - minY)
+}
+
+/** "5000mm" / "12.5 m" / '300cm' 같은 치수 라벨 파싱 (단위 필수 — 무단위 숫자는 무시). */
+function parseDimensions(labels: Label[]): Dim[] {
+  const out: Dim[] = []
+  for (const l of labels) {
+    const m = /^\s*(\d+(?:[.,]\d+)?)\s*(mm|cm|m|in|inch|")\s*$/i.exec(l.text ?? '')
+    if (!m) continue
+    const value = parseFloat(m[1].replace(',', '.'))
+    if (!Number.isFinite(value) || value <= 0) continue
+    const u = normUnit(m[2])
+    if (u) out.push({ value, unit: u })
+  }
+  return out
+}
+
+/** 가장 빈번한 단위 (동률이면 먼저 본 것). */
+function dominantUnit(dims: Dim[]): Unit | undefined {
+  if (!dims.length) return undefined
+  const count = new Map<Unit, number>()
+  for (const d of dims) count.set(d.unit, (count.get(d.unit) ?? 0) + 1)
+  let best: Unit | undefined
+  let bestN = 0
+  for (const d of dims) {
+    const n = count.get(d.unit)!
+    if (n > bestN) {
+      bestN = n
+      best = d.unit
+    }
+  }
+  return best
+}
+
+function normUnit(u?: string): Unit | undefined {
+  if (!u) return undefined
+  const s = u.toLowerCase()
+  if (s === 'mm') return 'mm'
+  if (s === 'cm') return 'cm'
+  if (s === 'm') return 'm'
+  if (s === 'in' || s === 'inch' || s === '"') return 'inch'
+  return undefined
+}

package/server/service/extraction/layout-refiner.ts

@@ -0,0 +1,104 @@
+/*
+ * GridSnapLayoutRefiner — 추출된 엔티티 레이아웃을 *정리*. Phase Board-AI §3.8 의 LayoutRefiner.
+ * 모든 경로(벡터·CV·VLM) 공용 품질 레버.
+ *
+ *   - align : 근접한 left/top 좌표를 단일연결 클러스터로 묶어 평균으로 스냅 → 행/열 정렬.
+ *   - grid  : (옵션) 위치를 grid step 으로 스냅.
+ *
+ * 순수·결정적 (같은 입력 → 같은 출력). 크기는 보존, 위치 이동분만큼 bbox 평행이동.
+ */
+import type { UniversalEntity } from '../types/index'
+import type { LayoutRefiner, ExtractionContext } from './contracts'
+
+export interface LayoutRefineOptions {
+  /** 근접 좌표 정렬 (default true). */
+  align?: boolean
+  /** 정렬 클러스터 허용오차. 미지정 시 엔티티 크기 중앙값으로 자동. */
+  alignTolerance?: number
+  /** >0 이면 위치를 이 step 으로 스냅. */
+  grid?: number
+}
+
+export class GridSnapLayoutRefiner implements LayoutRefiner {
+  readonly id = 'grid-snap'
+
+  constructor(private readonly opts: LayoutRefineOptions = {}) {}
+
+  refine(entities: UniversalEntity[], _ctx?: ExtractionContext): UniversalEntity[] {
+    if (entities.length === 0) return entities
+    const out = entities.map(cloneEntity)
+
+    if (this.opts.align !== false) {
+      const tol = this.opts.alignTolerance ?? autoTolerance(out)
+      const xs = clusterSnap(out.map(e => e.position.x), tol)
+      const ys = clusterSnap(out.map(e => e.position.y), tol)
+      out.forEach((e, i) => moveTo(e, xs[i], ys[i]))
+    }
+
+    const g = this.opts.grid
+    if (g && g > 0) {
+      out.forEach(e => moveTo(e, Math.round(e.position.x / g) * g, Math.round(e.position.y / g) * g))
+    }
+    return out
+  }
+}
+
+/** 위치를 (nx,ny)로 옮기고 bbox 도 같은 delta 로 평행이동 (size 보존). */
+function moveTo(e: UniversalEntity, nx: number, ny: number): void {
+  const dx = nx - e.position.x
+  const dy = ny - e.position.y
+  if (dx === 0 && dy === 0) return
+  e.position = { x: nx, y: ny }
+  e.bbox = {
+    min: { x: e.bbox.min.x + dx, y: e.bbox.min.y + dy },
+    max: { x: e.bbox.max.x + dx, y: e.bbox.max.y + dy }
+  }
+}
+
+/** 단일연결 클러스터링 — 정렬 후 인접 간격 ≤ tol 이면 한 클러스터, 클러스터 평균으로 스냅. */
+function clusterSnap(vals: number[], tol: number): number[] {
+  const order = vals.map((v, i) => ({ v, i })).sort((a, b) => a.v - b.v)
+  const snapped = new Array<number>(vals.length)
+  const flush = (s: number, e: number) => {
+    let sum = 0
+    for (let k = s; k < e; k++) sum += order[k].v
+    const mean = sum / (e - s)
+    for (let k = s; k < e; k++) snapped[order[k].i] = mean
+  }
+  let start = 0
+  for (let k = 1; k < order.length; k++) {
+    if (order[k].v - order[k - 1].v > tol) {
+      flush(start, k)
+      start = k
+    }
+  }
+  flush(start, order.length)
+  return snapped
+}
+
+/** 자동 허용오차 — 엔티티 크기 중앙값의 40%. 크기 없으면 좌표 spread 의 2%. */
+function autoTolerance(entities: UniversalEntity[]): number {
+  const dims: number[] = []
+  for (const e of entities) if (e.size) dims.push(e.size.width, e.size.height)
+  if (dims.length) return 0.4 * median(dims)
+  const xs = entities.map(e => e.position.x)
+  const ys = entities.map(e => e.position.y)
+  const spread = Math.max(Math.max(...xs) - Math.min(...xs), Math.max(...ys) - Math.min(...ys))
+  return 0.02 * (spread || 1)
+}
+
+function median(arr: number[]): number {
+  const s = [...arr].sort((a, b) => a - b)
+  const m = Math.floor(s.length / 2)
+  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2
+}
+
+function cloneEntity(e: UniversalEntity): UniversalEntity {
+  return {
+    ...e,
+    position: { ...e.position },
+    size: e.size ? { ...e.size } : undefined,
+    bbox: { min: { ...e.bbox.min }, max: { ...e.bbox.max } },
+    attribs: { ...e.attribs }
+  }
+}