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

package/server/service/converters/generic-to.test.ts

@@ -0,0 +1,105 @@
+/**
+ * convertPlaceholderTo / attachGlbToPlaceholder — 단위 테스트.
+ *
+ * 코어 placeholder type (placeholder) + 도메인 추상 (GenericTransport 등 호출자 명시)
+ * 모두 변환 가능한지 검증. 좌표/크기/source 보존, GLB attach morph 정책 회귀 방지.
+ */
+import {
+  convertPlaceholderTo,
+  isPlaceholderType,
+  CORE_PLACEHOLDER_TYPES
+} from './generic-to'
+import { GENERIC_OBJECT_TYPE } from '../pipeline/stage2-mapping'
+
+// 호출자가 도메인 추상까지 인정하는 경우의 fixtures.
+const EXTRA = ['GenericTransport', 'GenericFacility'] as const
+
+// ── 계약 어설션 ─────────────────────────────────────────────────────
+// things-scene 의 CORE_PLACEHOLDER_TYPES 와 mirror. client/server 경계로
+// 직접 import 불가 — 이 테스트가 양쪽 값 일치를 보증.
+describe('CORE_PLACEHOLDER_TYPES contract', () => {
+  test('GENERIC_OBJECT_TYPE 은 반드시 placeholder 고정', () => {
+    expect(GENERIC_OBJECT_TYPE).toBe('placeholder')
+  })
+
+  test('CORE_PLACEHOLDER_TYPES 는 [placeholder] 고정 — things-scene 과 동기화', () => {
+    expect(Array.from(CORE_PLACEHOLDER_TYPES)).toEqual(['placeholder'])
+  })
+})
+
+describe('isPlaceholderType', () => {
+  test('코어 type 들은 인정', () => {
+    for (const t of CORE_PLACEHOLDER_TYPES) {
+      expect(isPlaceholderType(t)).toBe(true)
+    }
+  })
+
+  test('extra list 의 도메인 추상도 인정', () => {
+    expect(isPlaceholderType('GenericTransport', EXTRA)).toBe(true)
+    expect(isPlaceholderType('GenericFacility', EXTRA)).toBe(true)
+  })
+
+  test('미등록 type 은 거부', () => {
+    expect(isPlaceholderType('Stocker')).toBe(false)
+    expect(isPlaceholderType(undefined)).toBe(false)
+  })
+
+  test('extra 미지정 시 도메인 추상 거부', () => {
+    expect(isPlaceholderType('GenericTransport')).toBe(false)
+  })
+})
+
+describe('convertPlaceholderTo', () => {
+  const base = {
+    type: 'placeholder',
+    id: 'src-1',
+    left: 100,
+    top: 200,
+    width: 80,
+    height: 60,
+    rotation: 0.5,
+    fillStyle: 'rgba(180,180,180,0.18)',
+    placeholderLabel: 'maybe stocker',
+    placeholderHint: 'STK_001'
+  }
+
+  test('placeholder 가 아닌 type 은 throw', () => {
+    expect(() =>
+      convertPlaceholderTo({ ...base, type: 'rect' } as any, 'Stocker')
+    ).toThrow(/not a generic placeholder/)
+  })
+
+  test('좌표/크기/회전/id 보존', () => {
+    const r = convertPlaceholderTo(base as any, 'Stocker') as any
+    expect(r.left).toBe(100)
+    expect(r.top).toBe(200)
+    expect(r.width).toBe(80)
+    expect(r.height).toBe(60)
+    expect(r.rotation).toBe(0.5)
+    expect(r.id).toBe('src-1')
+  })
+
+  test('새 type 으로 변환 + category=unknown (rule 미등록)', () => {
+    const r = convertPlaceholderTo(base as any, 'Stocker') as any
+    expect(r.type).toBe('Stocker')
+    expect(r.category).toBe('unknown')
+  })
+
+  test('placeholder 시각 메타 (fillStyle / placeholderLabel) 는 제거', () => {
+    const r = convertPlaceholderTo(base as any, 'Stocker') as any
+    expect(r.fillStyle).toBeUndefined()
+    expect(r.placeholderLabel).toBeUndefined()
+    expect(r.placeholderHint).toBeUndefined()
+    expect(r.convertedFrom).toBeUndefined()
+  })
+
+  test('도메인 추상 (extraPlaceholderTypes 명시) 도 변환 가능', () => {
+    const transport = { ...base, type: 'GenericTransport', id: 'tx-1' }
+    const r = convertPlaceholderTo(transport as any, 'Forklift', {
+      extraPlaceholderTypes: ['GenericTransport']
+    }) as any
+    expect(r.type).toBe('Forklift')
+    expect(r.convertedFrom).toBeUndefined()
+  })
+})
+

package/server/service/converters/generic-to.ts

@@ -0,0 +1,121 @@
+/**
+ * Generic placeholder → 도메인 컴포넌트 변환.
+ *
+ * Import 시 매칭되지 않은 entity 는 `placeholder` 타입으로 보드에 배치된다.
+ * 사용자가 사후에 모델러 UI 에서 "Convert to ..." 액션으로 도메인 컴포넌트로 변환.
+ *
+ * 아키텍처 원칙:
+ *   - `placeholder` — 도메인 비종속 임시 추상. 다른 type 으로 변환하는 기능만.
+ *     GLB 지원 없음 (GltfComponent mixin 제거됨).
+ *   - 도메인 generic 추상 (GenericTransport, GenericFacility 등) — 영구 도메인 추상.
+ *     GLB 바디를 직접 채우는 방식으로 사용. 변환 대상 아님.
+ *
+ * 변환 시:
+ *   - 좌표/크기/회전 보존
+ *   - source (원본 entity attribs) 보존
+ *   - 등록된 ImportRule.build 의 defaultState / idStrategy 적용
+ */
+import { find3DPreset, getImportRules } from '../registry/index'
+import type { BoardComponent } from '../pipeline/stage3-board'
+import type { ComponentCategory } from '../types/registry'
+import { GENERIC_OBJECT_TYPE } from '../pipeline/stage2-mapping'
+
+export interface ConvertOptions {
+  scopes?: string[]
+  /** 새 컴포넌트의 ID. 미지정 시 ImportRule 의 idStrategy 적용 또는 자동 생성. */
+  id?: string
+  /**
+   * 코어 placeholder type ('placeholder') 외에 인정할 도메인 추상 type list.
+   * 예: ['GenericTransport', 'GenericFacility'].
+   * 호출자가 자기 도메인 패키지의 추상까지 변환 대상으로 포함하도록 명시.
+   */
+  extraPlaceholderTypes?: ReadonlyArray<string>
+}
+
+/**
+ * things-scene 코어가 등록한 도메인 비종속 placeholder type.
+ *
+ * @sync things-scene/src/components/generic-placeholders.ts CORE_PLACEHOLDER_TYPES
+ * client/server 경계로 직접 import 불가 — 값을 바꾸면 양쪽 동시 수정 필수.
+ * 계약은 generic-to.test.ts 의 'CORE_PLACEHOLDER_TYPES contract' 어설션으로 보증.
+ */
+export const CORE_PLACEHOLDER_TYPES = [GENERIC_OBJECT_TYPE] as const
+
+export function isPlaceholderType(
+  type: string | undefined,
+  extraTypes: ReadonlyArray<string> = []
+): boolean {
+  if (!type) return false
+  if ((CORE_PLACEHOLDER_TYPES as readonly string[]).includes(type)) return true
+  return extraTypes.includes(type)
+}
+
+// ── 일반화된 변환 helper ─────────────────────────────────────────────
+
+/**
+ * 추상 placeholder 를 지정된 도메인 type 으로 변환. 호환되는 모든 generic-* 수용 (코어 + 도메인).
+ *
+ * 기존 좌표/크기/회전/source 보존. placeholder 시각 메타 (placeholderLabel/Hint, fillStyle 등) 는 제거.
+ */
+export function convertPlaceholderTo(
+  placeholder: BoardComponent,
+  toType: string,
+  options: ConvertOptions = {}
+): BoardComponent {
+  const extra = options.extraPlaceholderTypes ?? []
+  if (!isPlaceholderType(placeholder.type, extra)) {
+    throw new Error(
+      `Source component is not a generic placeholder (type=${placeholder.type}). ` +
+        `Expected one of: ${[...CORE_PLACEHOLDER_TYPES, ...extra].join(', ')}`
+    )
+  }
+
+  const rules = getImportRules(options.scopes)
+  const rule = rules.find(r => r.componentType === toType)
+
+  const category: ComponentCategory = rule?.category ?? 'unknown'
+  const newId = options.id ?? placeholder.id
+
+  const preset = find3DPreset(toType, category, options.scopes)
+  const threeD = {
+    geometry: preset.geometry,
+    ...(preset.material && { material: preset.material }),
+    origin: preset.origin ?? 'bottom'
+  }
+
+  // placeholder 시각/스타일 메타는 새 type 으로 옮길 때 의미 없음 — 제거.
+  const {
+    strokeStyle: _strokeStyle,
+    strokeDashArray: _strokeDashArray,
+    fillStyle: _fillStyle,
+    label: _label,
+    placeholderLabel: _placeholderLabel,
+    placeholderHint: _placeholderHint,
+    ...preservedState
+  } = placeholder as any
+
+  return {
+    ...preservedState,
+    category,
+    type: toType,
+    id: newId,
+    threeD,
+    ...(rule?.build.defaultState || {})
+  }
+}
+
+// ── Backward-compat alias — 기존 호출처 호환 ──────────────────────
+
+/**
+ * @deprecated Use `convertPlaceholderTo`. Placeholder 한정 — 새 코드는 일반화된 helper.
+ */
+export function convertGenericTo(
+  generic: BoardComponent,
+  toType: string,
+  options: ConvertOptions = {}
+): BoardComponent {
+  if (generic.type !== GENERIC_OBJECT_TYPE) {
+    throw new Error(`Source component is not Placeholder (type=${generic.type})`)
+  }
+  return convertPlaceholderTo(generic, toType, options)
+}

package/server/service/extraction/contracts.ts

@@ -0,0 +1,142 @@
+/*
+ * 하이브리드 추출 contracts (Phase Board-AI §3.8) — 이미지/도면 → 레이아웃 추출을
+ * *역할분담* 으로 분해하기 위한 provider-중립 인터페이스.
+ *
+ *   위치/기하  ← GeometryExtractor (벡터 파싱 > CV > VLM폴백)
+ *   식별/라벨  ← LabelExtractor    (OCR: GCP/Textract/Tesseract)
+ *   의미/타입  ← Recognizer        (VLM — region 인식 전담, 좌표 아님)
+ *   스케일     ← ScaleCalibrator   (치수/스케일바/알려진 크기)
+ *   정리       ← LayoutRefiner     (정렬/스냅/등간격/겹침해소)
+ *
+ * 구현체는 스캐폴딩 단계에선 stub. 본격 테스트 단계에서 소스 적합 impl 을 채운다.
+ */
+import type { UniversalEntity, Vec2, BoundingBox, AdapterInput, ParseResult } from '../types/index'
+
+/** 입력 소스 분류 — 추출 경로 선택 기준. */
+export type SourceKind =
+  | 'vector' //         DXF/IFC/SVG/PDF-vector — 정밀 기하 직접 파싱
+  | 'raster-topdown' // 평면도 비트맵 — CV + OCR + VLM 하이브리드
+  | 'photo' //          사진/3D 렌더 — VLM 러프 폴백
+  | 'unknown'
+
+/** 검출된 저수준 기하 프리미티브 (픽셀/소스 좌표계). */
+export interface GeometricPrimitive {
+  kind: 'line' | 'rect' | 'region' | 'point'
+  bbox: BoundingBox
+  /** line 일 때 양 끝점. */
+  segment?: { a: Vec2; b: Vec2 }
+  /** 검출 신뢰도 0..1 (있으면). */
+  score?: number
+  /**
+   * 이미 완전한 엔티티를 아는 추출기(벡터: DXF/IFC/SVG)가 원 엔티티를 그대로 실어 보낸다.
+   * 있으면 fuse 가 무손실로 사용(attribs/rotation/vertices 보존). CV 추출기는 비움 → fuse 가
+   * bbox 로 bare 엔티티 생성 후 Recognizer 가 의미 부여.
+   */
+  entity?: UniversalEntity
+  /** 추출기별 원시 메타. */
+  meta?: Record<string, any>
+}
+
+/** OCR 라벨 — 텍스트 + 위치 (식별/앵커/스케일 단서). */
+export interface Label {
+  text: string
+  bbox: BoundingBox
+  score?: number
+}
+
+/** 한 region(프리미티브/crop)에 대한 의미 인식 결과. */
+export interface RecognitionResult {
+  /** 실제 보드 컴포넌트 type (카탈로그 그라운딩). 불명 시 undefined. */
+  componentType?: string
+  confidence: number
+  attribs?: Record<string, any>
+}
+
+/** 스케일 캘리브레이션 결과 — 픽셀 → board 단위 변환. */
+export interface ScaleResult {
+  unitsPerPixel: number
+  origin: Vec2
+  units?: ParseResult['units']
+}
+
+/** 추출 컨텍스트 — 이미지 dims, 사용자 힌트, 카탈로그 등 (확장 여지). */
+export interface ExtractionContext {
+  imageWidth?: number
+  imageHeight?: number
+  userPrompt?: string
+  /** 카탈로그 그라운딩용 컴포넌트 type 목록 (Recognizer 가 제약). */
+  catalog?: string[]
+  /**
+   * 명시 스케일 기준 — 알려진 픽셀 span = 알려진 실제 길이 (예: UI 2점 캘리브레이션,
+   * 스케일바). ScaleCalibrator 가 최우선 사용. unitsPerPixel = units / pixels.
+   */
+  scaleReference?: { pixels: number; units: number; unit?: string }
+  [k: string]: any
+}
+
+// ── contracts ────────────────────────────────────────────────────────────────
+
+export interface GeometryExtractor {
+  readonly id: string
+  extract(input: AdapterInput, ctx?: ExtractionContext): Promise<GeometricPrimitive[]>
+}
+
+export interface LabelExtractor {
+  readonly id: string
+  extract(input: AdapterInput, ctx?: ExtractionContext): Promise<Label[]>
+}
+
+export interface Recognizer {
+  readonly id: string
+  /** region(프리미티브 + ctx)이 어떤 컴포넌트인지 — VLM 인식 전담(좌표 아님). */
+  recognize(region: GeometricPrimitive, ctx?: ExtractionContext): Promise<RecognitionResult>
+}
+
+export interface ScaleCalibrator {
+  readonly id: string
+  calibrate(labels: Label[], primitives: GeometricPrimitive[], ctx?: ExtractionContext): Promise<ScaleResult>
+}
+
+export interface LayoutRefiner {
+  readonly id: string
+  refine(entities: UniversalEntity[], ctx?: ExtractionContext): UniversalEntity[]
+}
+
+/** 한 시안(해석) — 공유 기하 위에 의미/그룹핑/전략만 달리한 결과. */
+export interface VariantDraft {
+  /** URL 친화 short id (예: 'equipment-focus'). */
+  id: string
+  /** 사용자 표시 라벨 (예: '장비 중심'). */
+  label: string
+  description?: string
+  entities: UniversalEntity[]
+  subjectName?: string
+  subjectDescription?: string
+  importStrategy?: string
+}
+
+/**
+ * 시안 전략 — *정확한 공유 기하+라벨* 을 받아 N개 해석 시안을 만든다.
+ * (UX: 사용자가 3안 중 선택하는 흐름 보존. 기하는 공유라 셋 다 레이아웃 정상, 해석만 다름.)
+ * 미지정 시 파이프라인이 단일 default 시안 1개를 만든다.
+ */
+export interface VariantStrategy {
+  readonly id: string
+  interpret(
+    primitives: GeometricPrimitive[],
+    labels: Label[],
+    set: ExtractorSet,
+    ctx?: ExtractionContext
+  ): Promise<VariantDraft[]>
+}
+
+/** 한 소스경로의 추출기 묶음 (geometry 필수, 나머지는 경로별 선택). */
+export interface ExtractorSet {
+  geometry: GeometryExtractor
+  labels?: LabelExtractor
+  recognizer?: Recognizer
+  scale?: ScaleCalibrator
+  refiner?: LayoutRefiner
+  /** 다중 시안 생성 전략 (3안 선택 UX). 미지정 시 단일 default 시안. */
+  variants?: VariantStrategy
+}