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

package/server/service/extraction/pipeline.ts

@@ -0,0 +1,163 @@
+/*
+ * 하이브리드 추출 파이프라인 (골격) — Phase Board-AI §3.8.
+ *
+ *   detect → geometry + labels → [VariantStrategy 또는 단일 fuse] → 시안별 scale → refine
+ *
+ * 기하는 *공유* (정확) → 시안들은 해석만 다름 → 3안 선택 UX 보존하되 셋 다 레이아웃 정상.
+ * impl 은 ExtractorSet 으로 주입 (스캐폴딩엔 stub). 기존 어댑터 경로와 독립.
+ */
+import type { UniversalEntity, BoundingBox, AdapterInput } from '../types/index'
+import type {
+  SourceKind,
+  ExtractorSet,
+  GeometricPrimitive,
+  Label,
+  VariantDraft,
+  ScaleResult,
+  ExtractionContext
+} from './contracts'
+import { detectSourceKind, getExtractorSet } from './source-router'
+
+export interface HybridExtractResult {
+  /** default 시안 entities (= variants[0]). */
+  entities: UniversalEntity[]
+  /** 다중 시안 (선택 UX). */
+  variants: VariantDraft[]
+  bbox: BoundingBox
+  sourceKind: SourceKind
+}
+
+export async function extractHybrid(
+  input: AdapterInput,
+  ctx: ExtractionContext = {},
+  filename?: string
+): Promise<HybridExtractResult> {
+  const kind = await detectSourceKind(input, filename)
+  const set = getExtractorSet(kind)
+  if (!set) {
+    throw new Error(`[board-import/extraction] '${kind}' ExtractorSet 미등록 — registerExtractorSet 로 주입 필요`)
+  }
+
+  // 1. 기하(위치) + 2. 라벨(식별/스케일 단서) — 공유 추출.
+  const primitives = await set.geometry.extract(input, ctx)
+  const labels: Label[] = set.labels ? await set.labels.extract(input, ctx) : []
+
+  // 3. 시안 생성 — 전략 있으면 N안, 없으면 단일 default.
+  let drafts: VariantDraft[] = set.variants
+    ? await set.variants.interpret(primitives, labels, set, ctx)
+    : [{ id: 'default', label: 'default', entities: await fuse(primitives, labels, set, ctx) }]
+  if (drafts.length === 0) drafts = [{ id: 'default', label: 'default', entities: [] }]
+
+  // 4. 시안별 스케일 보정 + 5. 레이아웃 정리.
+  for (const d of drafts) {
+    if (set.scale) applyScale(d.entities, await set.scale.calibrate(labels, primitives, ctx))
+    if (set.refiner) d.entities = set.refiner.refine(d.entities, ctx)
+  }
+
+  return {
+    entities: drafts[0].entities,
+    variants: drafts,
+    bbox: outerBbox(drafts[0].entities),
+    sourceKind: kind
+  }
+}
+
+// ── 기본 융합 (스캐폴딩) ────────────────────────────────────────────────────────
+// 기하 프리미티브 → UniversalEntity, 가장 가까운 라벨을 name 으로 앵커.
+// TODO(본격): region 별 set.recognizer.recognize → attribs.semanticType/componentType + categoryHint.
+async function fuse(
+  primitives: GeometricPrimitive[],
+  labels: Label[],
+  set: ExtractorSet,
+  ctx?: ExtractionContext
+): Promise<UniversalEntity[]> {
+  return Promise.all(
+    primitives.map(async (p, i) => {
+      const lbl = nearestLabel(p, labels)
+
+      if (p.entity) {
+        // 벡터: 이미 완전한 엔티티(타입/속성 보유) — 무손실 사용. name 없으면 근접 라벨로 보강.
+        const e = p.entity
+        if (!e.attribs.name && lbl) e.attribs = { ...e.attribs, name: lbl.text }
+        return e
+      }
+
+      const e = primitiveToEntity(p, i)
+      if (lbl) e.attribs.name = lbl.text
+
+      // CV 등 bare 프리미티브 — Recognizer 로 의미(componentType) 부여. (좌표 아님)
+      if (set.recognizer) {
+        const region = lbl ? { ...p, meta: { ...p.meta, label: lbl.text } } : p
+        const r = await set.recognizer.recognize(region, ctx)
+        if (r.componentType) {
+          e.attribs.semanticType = r.componentType
+          e.attribs.confidence = r.confidence
+        }
+        if (r.attribs) Object.assign(e.attribs, r.attribs)
+      }
+      return e
+    })
+  )
+}
+
+function primitiveToEntity(p: GeometricPrimitive, i: number): UniversalEntity {
+  const w = p.bbox.max.x - p.bbox.min.x
+  const h = p.bbox.max.y - p.bbox.min.y
+  return {
+    uid: `ext-${i}`,
+    kind: 'shape',
+    position: { x: p.bbox.min.x, y: p.bbox.min.y },
+    size: { width: w, height: h },
+    bbox: p.bbox,
+    attribs: {}
+  }
+}
+
+function center(b: BoundingBox) {
+  return { x: (b.min.x + b.max.x) / 2, y: (b.min.y + b.max.y) / 2 }
+}
+
+function nearestLabel(p: GeometricPrimitive, labels: Label[]): Label | undefined {
+  if (!labels.length) return undefined
+  const c = center(p.bbox)
+  let best: Label | undefined
+  let bestD = Infinity
+  for (const l of labels) {
+    const lc = center(l.bbox)
+    const d = (lc.x - c.x) ** 2 + (lc.y - c.y) ** 2
+    if (d < bestD) {
+      bestD = d
+      best = l
+    }
+  }
+  return best
+}
+
+function applyScale(entities: UniversalEntity[], s: ScaleResult): void {
+  const f = s.unitsPerPixel
+  const ox = s.origin.x
+  const oy = s.origin.y
+  for (const e of entities) {
+    e.position = { x: (e.position.x - ox) * f, y: (e.position.y - oy) * f }
+    if (e.size) e.size = { width: e.size.width * f, height: e.size.height * f }
+    e.bbox = {
+      min: { x: (e.bbox.min.x - ox) * f, y: (e.bbox.min.y - oy) * f },
+      max: { x: (e.bbox.max.x - ox) * f, y: (e.bbox.max.y - oy) * f }
+    }
+  }
+}
+
+function outerBbox(entities: UniversalEntity[]): BoundingBox {
+  if (!entities.length) return { min: { x: 0, y: 0 }, max: { x: 0, y: 0 } }
+  let minX = Infinity
+  let minY = Infinity
+  let maxX = -Infinity
+  let maxY = -Infinity
+  for (const e of entities) {
+    minX = Math.min(minX, e.bbox.min.x)
+    minY = Math.min(minY, e.bbox.min.y)
+    maxX = Math.max(maxX, e.bbox.max.x)
+    maxY = Math.max(maxY, e.bbox.max.y)
+  }
+  return { min: { x: minX, y: minY }, max: { x: maxX, y: maxY } }
+}

package/server/service/extraction/source-router.ts

@@ -0,0 +1,45 @@
+/*
+ * 소스 라우팅 — 입력(+파일명)을 SourceKind 로 분류하고, 그 경로의 ExtractorSet 을 돌려준다.
+ * impl 묶음은 register 로 주입 (스캐폴딩 단계엔 stub 묶음). 기존 어댑터 경로는 무관/보존.
+ */
+import type { AdapterInput } from '../types/index'
+import type { SourceKind, ExtractorSet } from './contracts'
+
+const VECTOR_EXT = new Set(['dxf', 'svg', 'ifc'])
+const RASTER_EXT = new Set(['png', 'jpg', 'jpeg', 'webp', 'gif', 'bmp'])
+
+/**
+ * 입력 → 소스 분류. 현재는 확장자 기반의 1차 분류.
+ *  - pdf: vector 우선 가정 (실제론 vector/raster 페이지 판별 필요 — 추후).
+ *  - 비트맵: 일단 raster-topdown. top-down vs photo 세분은 VLM 1-pass 분류로 (추후).
+ */
+export async function detectSourceKind(_input: AdapterInput, filename?: string): Promise<SourceKind> {
+  const ext = (filename?.split('.').pop() || '').toLowerCase()
+  if (VECTOR_EXT.has(ext) || ext === 'pdf') return 'vector'
+  if (RASTER_EXT.has(ext)) return 'raster-topdown'
+  return 'unknown'
+}
+
+export type ExtractorSetFactory = () => ExtractorSet
+
+const _registry = new Map<SourceKind, ExtractorSetFactory>()
+
+/** 소스별 추출기 묶음 등록 (impl 주입 지점). */
+export function registerExtractorSet(kind: SourceKind, factory: ExtractorSetFactory): void {
+  _registry.set(kind, factory)
+}
+
+/** 소스별 추출기 묶음 조회. 미등록 시 undefined. */
+export function getExtractorSet(kind: SourceKind): ExtractorSet | undefined {
+  return _registry.get(kind)?.()
+}
+
+/** 등록된 소스 종류 (진단/검사용). */
+export function registeredSourceKinds(): SourceKind[] {
+  return [..._registry.keys()]
+}
+
+/** 등록 초기화 (테스트 격리 / 재구성용). */
+export function clearExtractorSets(): void {
+  _registry.clear()
+}

package/server/service/extraction/stubs.ts

@@ -0,0 +1,46 @@
+/*
+ * 스캐폴딩 stub 구현 — 구조가 컴파일·배선되도록 자리만 잡는다.
+ * 남은 stub (본격 테스트 단계에서 소스 적합 impl 로 교체):
+ *   CvGeometryExtractor   → OpenCV(선/사각/연결성분) 또는 Python 사이드카
+ *   CloudOcrLabelExtractor → GCP Vision / AWS Textract / Tesseract
+ * 미구현 stub 은 호출 시 명확히 throw — 실수로 live 경로에 붙어도 즉시 드러난다.
+ * (실구현: VectorGeometryExtractor / GridSnapLayoutRefiner / VlmRecognizer / LabelScaleCalibrator)
+ */
+import type { UniversalEntity } from '../types/index'
+import type {
+  GeometryExtractor,
+  LabelExtractor,
+  LayoutRefiner,
+  GeometricPrimitive,
+  Label,
+  ExtractionContext
+} from './contracts'
+
+const NI = (what: string): never => {
+  throw new Error(`[board-import/extraction] ${what} 미구현 (스캐폴딩) — Phase B 본격 테스트 단계에서 구현`)
+}
+
+export class CvGeometryExtractor implements GeometryExtractor {
+  readonly id = 'cv-geometry'
+  async extract(): Promise<GeometricPrimitive[]> {
+    return NI('CvGeometryExtractor.extract (OpenCV 선/사각/연결성분)')
+  }
+}
+
+export class CloudOcrLabelExtractor implements LabelExtractor {
+  readonly id = 'cloud-ocr'
+  async extract(): Promise<Label[]> {
+    return NI('CloudOcrLabelExtractor.extract (GCP Vision / Textract)')
+  }
+}
+
+/**
+ * 레이아웃 정리 stub — 정렬/스냅/겹침해소는 미구현이라 *그대로 통과*(no-op).
+ * (throw 가 아니라 안전한 항등 — refiner 미구현이어도 파이프라인이 깨지지 않도록.)
+ */
+export class IdentityLayoutRefiner implements LayoutRefiner {
+  readonly id = 'identity'
+  refine(entities: UniversalEntity[], _ctx?: ExtractionContext): UniversalEntity[] {
+    return entities
+  }
+}

package/server/service/extraction/vector-geometry.ts

@@ -0,0 +1,26 @@
+/*
+ * VectorGeometryExtractor — 벡터 소스(DXF 등)를 *직접 파싱*해 정밀 기하 추출.
+ * Phase Board-AI §3.8 의 "벡터 = 1순위 정밀 경로". 기존 DxfAdapter 를 흡수(델리게이트):
+ * DXF entity 는 이미 위치+크기+회전+attribs(name/layer/shape) 를 가진 UniversalEntity 이므로,
+ * 각 엔티티를 GeometricPrimitive.entity 로 그대로 실어 *무손실* 전달한다.
+ *
+ * 추후: SVG / IFC 어댑터를 detect 로 분기해 같은 방식으로 흡수.
+ */
+import type { AdapterInput } from '../types/index'
+import type { GeometryExtractor, GeometricPrimitive, ExtractionContext } from './contracts'
+import { DxfAdapter } from '../adapters/dxf-adapter'
+
+export class VectorGeometryExtractor implements GeometryExtractor {
+  readonly id = 'vector-geometry'
+  private readonly dxf = new DxfAdapter()
+
+  async extract(input: AdapterInput, _ctx?: ExtractionContext): Promise<GeometricPrimitive[]> {
+    // 현재 DXF 만 지원. (SVG/IFC 확장 시 detect 로 어댑터 선택.)
+    const result = await this.dxf.parse(input)
+    return result.entities.map(e => ({
+      kind: e.kind === 'path' ? ('line' as const) : ('rect' as const),
+      bbox: e.bbox,
+      entity: e // 무손실 보존 — fuse 가 그대로 사용
+    }))
+  }
+}

package/server/service/extraction/vlm-recognizer.ts

@@ -0,0 +1,87 @@
+/*
+ * VlmRecognizer — region 이 *어떤 컴포넌트인지* 식별 (Phase Board-AI §3.8 의 Recognizer).
+ *
+ * 좌표/레이아웃은 절대 추정하지 않는다(그건 Geometry/CV 의 몫). VLM/LLM 의 강점인
+ * *의미 인식* 만: 주어진 신호(라벨·모양·크기·레이어) + 카탈로그 → componentType.
+ * 카탈로그(ctx.catalog) 가 있으면 그 안의 값만 허용(그라운딩).
+ *
+ * provider 는 ai-client-base 의 AIClient. 생성자 주입 가능(테스트), 미주입 시 기본 클라이언트.
+ */
+import { getDefaultAIClient, type AIClient } from '@things-factory/ai-client-base'
+import type { Recognizer, RecognitionResult, GeometricPrimitive, ExtractionContext } from './contracts'
+
+interface RawRecognition {
+  componentType?: string | null
+  confidence?: number
+  attribs?: Record<string, any>
+}
+
+const SYSTEM =
+  '당신은 시설 도면의 한 영역(region)이 어떤 보드 컴포넌트 type 인지 판정하는 분류기다. ' +
+  '좌표/위치/크기를 추정하지 말고, 주어진 신호(라벨/모양/크기/레이어)와 카탈로그만으로 *type* 만 판정한다. ' +
+  'STRICT JSON 만 반환(마크다운/주석 금지).'
+
+export class VlmRecognizer implements Recognizer {
+  readonly id = 'vlm-recognizer'
+
+  constructor(private readonly client?: AIClient) {}
+
+  async recognize(region: GeometricPrimitive, ctx?: ExtractionContext): Promise<RecognitionResult> {
+    const client = this.client ?? getDefaultAIClient()
+    if (!client) {
+      throw new Error('[board-import/extraction] VlmRecognizer 는 AIClient 가 필요합니다 (setDefaultAIClient / config.aiClient).')
+    }
+    const raw = await client.generateJSON<RawRecognition>(buildPrompt(region, ctx), {
+      systemPrompt: SYSTEM,
+      temperature: 0,
+      maxTokens: 300
+    })
+    return normalize(raw, ctx?.catalog)
+  }
+}
+
+/** region 신호 + 카탈로그 → 인식 프롬프트. */
+export function buildPrompt(region: GeometricPrimitive, ctx?: ExtractionContext): string {
+  const w = region.bbox.max.x - region.bbox.min.x
+  const h = region.bbox.max.y - region.bbox.min.y
+  const aspect = h !== 0 ? w / h : 0
+  const a = region.entity?.attribs ?? {}
+  const m = region.meta ?? {}
+
+  const signals: string[] = [`kind=${region.kind}`, `size=${round(w)}x${round(h)}`, `aspect=${aspect.toFixed(2)}`]
+  const name = a.name ?? m.name ?? m.label
+  if (name) signals.push(`label="${name}"`)
+  if (a.shape ?? m.shape) signals.push(`shape=${a.shape ?? m.shape}`)
+  if (a.layer ?? m.layer) signals.push(`layer=${a.layer ?? m.layer}`)
+  if (a.text ?? m.text) signals.push(`text="${a.text ?? m.text}"`)
+
+  const catalogLine =
+    ctx?.catalog && ctx.catalog.length
+      ? `\n카탈로그(이 중에서만 선택, 맞는 게 없으면 componentType=null):\n${ctx.catalog.join(', ')}`
+      : '\n카탈로그 미지정 — 가장 적절한 컴포넌트 type 을 자유롭게 판정.'
+  const hint = ctx?.userPrompt ? `\n사용자 힌트: ${ctx.userPrompt}` : ''
+
+  return (
+    `다음 영역의 신호로 보드 컴포넌트 type 을 판정하라.\n신호: ${signals.join(', ')}${catalogLine}${hint}\n` +
+    `반환 JSON: { "componentType": string|null, "confidence": 0..1, "attribs": { ... } }`
+  )
+}
+
+/** 응답 정규화 + 카탈로그 그라운딩 + confidence 클램프. */
+export function normalize(raw: RawRecognition | null | undefined, catalog?: string[]): RecognitionResult {
+  let type =
+    typeof raw?.componentType === 'string' && raw.componentType.trim() ? raw.componentType.trim() : undefined
+  // 카탈로그 있으면 그 안의 값만 허용 — 그라운딩(환각 type 차단).
+  if (type && catalog && catalog.length && !catalog.includes(type)) type = undefined
+
+  let conf = typeof raw?.confidence === 'number' && Number.isFinite(raw.confidence) ? raw.confidence : 0.5
+  conf = Math.max(0, Math.min(1, conf))
+  if (!type) conf = Math.min(conf, 0.3) // 타입 미상이면 신뢰도 상한
+
+  const attribs = raw?.attribs && typeof raw.attribs === 'object' ? raw.attribs : undefined
+  return { componentType: type, confidence: conf, attribs }
+}
+
+function round(n: number): number {
+  return Math.round(n * 100) / 100
+}

package/server/service/import-session/import-actions.test.ts

@@ -0,0 +1,185 @@
+/**
+ * import-actions — 단위 테스트.
+ *
+ * ResolverContext 무관 service 함수의 동작 검증. mock SessionRepoLike 로 격리.
+ * 비동기 worker (runImportJob) 는 setImmediate side-effect 로 분리되어 있어
+ * 본 테스트 범위 밖 — startImportJobAsync 는 session 저장 후 즉시 return 만 검증.
+ */
+import {
+  startImportJobAsync,
+  fetchImportSession,
+  listImportSessionsByChatSession,
+  describeAdapter,
+  type ImportActionsContext,
+  type SessionRepoLike
+} from './import-actions'
+
+const DOMAIN = { id: 'domain-1', name: 'test' }
+const USER = { id: 'user-1' }
+const CTX: ImportActionsContext = { domain: DOMAIN, user: USER }
+
+function makeRepo(overrides: Partial<SessionRepoLike> = {}) {
+  const findOneByCalls: any[] = []
+  const saveCalls: any[] = []
+  const findCalls: any[] = []
+  const repo: any = {
+    findOneByCalls,
+    saveCalls,
+    findCalls,
+    findOneBy: async (criteria: any) => {
+      findOneByCalls.push(criteria)
+      return null
+    },
+    save: async (entity: any) => {
+      saveCalls.push(entity)
+      return { ...entity, id: 'session-' + (saveCalls.length) }
+    },
+    find: async (options: any) => {
+      findCalls.push(options)
+      return []
+    },
+    ...overrides
+  }
+  return repo
+}
+
+// ── startImportJobAsync ────────────────────────────────────────────
+
+describe('startImportJobAsync', () => {
+  test('session 을 status=queued / progress=0 으로 저장', async () => {
+    const repo = makeRepo()
+    await startImportJobAsync({ attachmentId: 'a1' }, CTX, repo, () => {})
+    expect(repo.saveCalls).toHaveLength(1)
+    expect(repo.saveCalls[0]).toMatchObject({
+      domain: DOMAIN,
+      attachmentId: 'a1',
+      status: 'queued',
+      progress: 0,
+      message: 'Queued',
+      creator: USER
+    })
+  })
+
+  test('options 가 optionsJson 으로 직렬화', async () => {
+    const repo = makeRepo()
+    await startImportJobAsync(
+      {
+        attachmentId: 'a1',
+        scopes: ['fmsim'],
+        normalizeOrigin: true,
+        flipY: false,
+        scale: 2,
+        applyBinding: false,
+        parseOptions: { excludeLayers: ['ANNO'] }
+      },
+      CTX,
+      repo,
+      () => {}
+    )
+    const json = JSON.parse(repo.saveCalls[0].optionsJson)
+    expect(json).toEqual({
+      scopes: ['fmsim'],
+      normalizeOrigin: true,
+      flipY: false,
+      scale: 2,
+      applyBinding: false,
+      parseOptions: { excludeLayers: ['ANNO'] }
+    })
+  })
+
+  test('chatSessionId 가 옵션이라 미지정 시 undefined 로 저장', async () => {
+    const repo = makeRepo()
+    await startImportJobAsync({ attachmentId: 'a1' }, CTX, repo, () => {})
+    expect(repo.saveCalls[0].chatSessionId).toBeUndefined()
+  })
+})
+
+// ── fetchImportSession ────────────────────────────────────────────
+
+describe('fetchImportSession', () => {
+  test('domain id 기반 격리 조회', async () => {
+    const repo = makeRepo()
+    await fetchImportSession('s1', CTX, repo)
+    expect(repo.findOneByCalls[0]).toEqual({
+      id: 's1',
+      domain: { id: DOMAIN.id }
+    })
+  })
+
+  test('미존재 시 null', async () => {
+    const repo = makeRepo()
+    const r = await fetchImportSession('s1', CTX, repo)
+    expect(r).toBeNull()
+  })
+
+  test('존재 시 session 그대로 반환', async () => {
+    const session = { id: 's1', status: 'completed' } as any
+    const repo = makeRepo({ findOneBy: async () => session })
+    const r = await fetchImportSession('s1', CTX, repo)
+    expect(r).toBe(session)
+  })
+})
+
+// ── listImportSessionsByChatSession ────────────────────────────────
+
+describe('listImportSessionsByChatSession', () => {
+  test('chatSessionId + domain 기반, 최신순 50개', async () => {
+    const repo = makeRepo()
+    await listImportSessionsByChatSession('chat-1', CTX, repo)
+    expect(repo.findCalls[0]).toEqual({
+      where: { chatSessionId: 'chat-1', domain: { id: DOMAIN.id } },
+      order: { createdAt: 'DESC' },
+      take: 50
+    })
+  })
+})
+
+// ── describeAdapter ───────────────────────────────────────────────
+
+describe('describeAdapter', () => {
+  test('FormatAdapter 의 능력을 직렬화 가능 평면 객체로', () => {
+    const adapter = {
+      format: 'dxf',
+      supportedExtensions: ['.dxf'],
+      capabilities: {
+        has2D: true,
+        has3D: false,
+        hasSemanticLabels: false,
+        hasTextLabels: true,
+        hasAttributes: true
+      }
+    }
+    expect(describeAdapter(adapter)).toEqual({
+      format: 'dxf',
+      supportedExtensions: ['.dxf'],
+      capabilities: {
+        has2D: true,
+        has3D: false,
+        hasSemanticLabels: false,
+        hasTextLabels: true,
+        hasAttributes: true
+      }
+    })
+  })
+
+  test('falsy capability 도 false 로 정규화', () => {
+    const adapter = {
+      format: 'image',
+      supportedExtensions: ['.png'],
+      capabilities: {
+        has2D: 1, // truthy non-bool
+        has3D: undefined,
+        hasSemanticLabels: 'yes',
+        hasTextLabels: 0,
+        hasAttributes: null
+      }
+    }
+    expect(describeAdapter(adapter as any).capabilities).toEqual({
+      has2D: true,
+      has3D: false,
+      hasSemanticLabels: true,
+      hasTextLabels: false,
+      hasAttributes: false
+    })
+  })
+})