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

package/server/service/pipeline/stage3-board.ts

@@ -0,0 +1,179 @@
+/**
+ * Stage 3 — ComponentDraft → Board Model JSON.
+ * 좌표/단위 변환 + 3D Preset 적용.
+ */
+import { find3DPreset } from '../registry/index'
+import type { BoundingBox } from '../types/index'
+import type { ComponentCategory, ComponentDraft } from '../types/registry'
+
+export interface BoardModel {
+  width?: number
+  height?: number
+  fillStyle?: string
+  /**
+   * 컴포넌트 목록. things-scene 보드 모델 호환을 위해 optional.
+   * 빈 보드 / legacy 형식 / root container 가 직접 model 인 경우 누락 가능.
+   * 사용처는 항상 `(model.components ?? [])` 패턴으로 접근.
+   */
+  components?: BoardComponent[]
+  /** 메타: import 출처 */
+  importMeta?: {
+    format: string
+    sourceBbox: BoundingBox
+    units?: string
+    importedAt: string
+  }
+  /** things-scene / 사용자 도메인이 임의 추가하는 필드 */
+  [k: string]: any
+}
+
+export interface BoardComponent {
+  /** Universal category — 모든 컴포넌트가 보유. 변환·렌더 정책의 기반. */
+  category: ComponentCategory
+  /** 도메인 type. 'GenericObject' 면 변환 가능한 placeholder. */
+  type: string
+  id?: string
+  left: number
+  top: number
+  width: number
+  height: number
+  rotation?: number
+  /** 3D Preset 해석 결과 (있으면) */
+  threeD?: Record<string, any>
+  [k: string]: any
+}
+
+export interface AssembleOptions {
+  /** scope 들 — 3D preset 조회 시 사용 */
+  scopes?: string[]
+  /** 좌표계 정규화: true 면 entities 의 minX,minY 가 0,0 이 되도록 이동 */
+  normalizeOrigin?: boolean
+  /** Y 축 뒤집기: CAD (Y-up) → scene (Y-down) */
+  flipY?: boolean
+  /** 단위 → scene unit 변환 비율. 1 이면 그대로. */
+  scale?: number
+  /** 보드 배경색 */
+  backgroundColor?: string
+  /** importMeta 를 모델에 첨부 */
+  importMeta?: BoardModel['importMeta']
+}
+
+/**
+ * 보드 외곽 padding (양쪽). 컴포넌트가 root 가장자리에 정확히 맞닿지 않도록 살짝 여백.
+ * 너무 크면 빈 공간 낭비, 너무 작으면 시각적으로 갑갑함 → 40 unit.
+ */
+const BOARD_PADDING = 40
+
+/**
+ * 빈 보드 / 너무 작은 컨텐츠일 때 fallback 크기.
+ * 최소 1000x1000 — things-scene 의 RootContainer 기본 크기에 맞춤.
+ */
+const MIN_BOARD_SIZE = 1000
+
+export function assembleBoard(
+  drafts: ComponentDraft[],
+  bbox: BoundingBox,
+  options: AssembleOptions = {}
+): BoardModel {
+  const scale = options.scale ?? 1
+  const offsetX = options.normalizeOrigin ? -bbox.min.x : 0
+  const offsetY = options.normalizeOrigin ? -bbox.min.y : 0
+
+  // 1단계: bbox 기반 가설 board 크기. 그러나 entity bbox 와 position+size 가 어긋나는 경우
+  // 컴포넌트가 root 외곽으로 spill 할 수 있어 2단계에서 컴포넌트 실제 edge 로 보정한다.
+  let boardWidth = (bbox.max.x - bbox.min.x) * scale
+  let boardHeight = (bbox.max.y - bbox.min.y) * scale
+
+  // 1.5단계: 컴포넌트 layout 1차 (flipY 미적용 — boardHeight 확정 전이라 미루기).
+  type Layout = {
+    d: ComponentDraft
+    src: ComponentDraft['source']
+    left: number
+    rawTop: number
+    width: number
+    height: number
+  }
+  const layouts: Layout[] = drafts.map(d => {
+    const src = d.source
+    const left = src ? (src.position.x + offsetX) * scale : 0
+    const rawTop = src ? (src.position.y + offsetY) * scale : 0
+    const width = (src?.size?.width ?? 1) * scale
+    const height = (src?.size?.height ?? 1) * scale
+    return { d, src, left, rawTop, width, height }
+  })
+
+  // 2단계: 컴포넌트 실제 edge 로 board 크기 보정. bbox 보다 컴포넌트 right/bottom 이
+  // 크면 그것 기준. 모든 컴포넌트 left/top 도 음수 안 되도록 0 이상 보장 (있으면 offset 보정).
+  let computedRight = 0
+  let computedBottom = 0
+  let computedMinLeft = 0
+  let computedMinTop = 0
+  for (const l of layouts) {
+    if (l.left < computedMinLeft) computedMinLeft = l.left
+    if (l.rawTop < computedMinTop) computedMinTop = l.rawTop
+    if (l.left + l.width > computedRight) computedRight = l.left + l.width
+    if (l.rawTop + l.height > computedBottom) computedBottom = l.rawTop + l.height
+  }
+  // 음수 left/top 이 있으면 추가 offset 으로 0 으로 끌어올림.
+  const extraOffsetX = computedMinLeft < 0 ? -computedMinLeft : 0
+  const extraOffsetY = computedMinTop < 0 ? -computedMinTop : 0
+  if (extraOffsetX || extraOffsetY) {
+    for (const l of layouts) {
+      l.left += extraOffsetX
+      l.rawTop += extraOffsetY
+    }
+    computedRight += extraOffsetX
+    computedBottom += extraOffsetY
+  }
+
+  // 최종 board 크기 — bbox 와 컴포넌트 실제 max edge 중 큰 값 + padding.
+  // 컴포넌트 없으면 padding 의미 없고, fallback 으로 MIN_BOARD_SIZE.
+  boardWidth = Math.max(boardWidth, computedRight)
+  boardHeight = Math.max(boardHeight, computedBottom)
+  if (layouts.length > 0) {
+    boardWidth += BOARD_PADDING * 2
+    boardHeight += BOARD_PADDING * 2
+  }
+  boardWidth = Math.max(boardWidth, MIN_BOARD_SIZE)
+  boardHeight = Math.max(boardHeight, MIN_BOARD_SIZE)
+
+  // 3단계: padding 만큼 모든 컴포넌트 안쪽으로 평행이동 + flipY 적용.
+  const components: BoardComponent[] = layouts.map(({ d, src, left, rawTop, width, height }) => {
+    const finalLeft = left + BOARD_PADDING
+    const finalRawTop = rawTop + BOARD_PADDING
+    const finalTop = options.flipY ? boardHeight - finalRawTop - height : finalRawTop
+    const rotation = src?.rotation
+
+    const preset = find3DPreset(d.type, d.category, options.scopes)
+    const threeD = presetToState(preset)
+
+    return {
+      category: d.category,
+      type: d.type,
+      id: d.id,
+      left: finalLeft,
+      top: finalTop,
+      width,
+      height,
+      ...(rotation !== undefined && { rotation: options.flipY ? -rotation : rotation }),
+      threeD,
+      ...d.state
+    }
+  })
+
+  return {
+    width: boardWidth,
+    height: boardHeight,
+    fillStyle: options.backgroundColor ?? '#ffffff',
+    components,
+    importMeta: options.importMeta
+  }
+}
+
+function presetToState(preset: import('../types/registry.js').ThreeDPreset): Record<string, any> {
+  return {
+    geometry: preset.geometry,
+    ...(preset.material && { material: preset.material }),
+    origin: preset.origin ?? 'bottom'
+  }
+}

package/server/service/pipeline/stage4-binding.ts

@@ -0,0 +1,31 @@
+/**
+ * Stage 4 — 보드 모델에 데이터 바인딩 자동 설정.
+ * 컴포넌트 type 에 등록된 SubscriptionRule 을 찾아 subscriptionTag 등 부여.
+ */
+import { findSubscriptionRule } from '../registry/index'
+import type { BoardComponent, BoardModel } from './stage3-board'
+
+export interface BindingOptions {
+  scopes?: string[]
+}
+
+/**
+ * 보드 모델의 모든 컴포넌트에 subscription 정보를 주입.
+ * things-factory 의 dataSubscriptionProvider 가 인식하는 형태로.
+ */
+export function applyDataBinding(model: BoardModel, options: BindingOptions = {}): BoardModel {
+  const components = model.components.map(c => bindComponent(c, options))
+  return { ...model, components }
+}
+
+function bindComponent(c: BoardComponent, options: BindingOptions): BoardComponent {
+  const rule = findSubscriptionRule(c.type, options.scopes)
+  if (!rule) return c
+
+  return {
+    ...c,
+    subscriptionTag: rule.tag,
+    subscriptionIdField: rule.idField ?? 'NAME',
+    ...(rule.fieldMappings && { subscriptionFieldMappings: rule.fieldMappings })
+  }
+}

package/server/service/registry/index.ts

@@ -0,0 +1,127 @@
+/**
+ * 앱이 자기 도메인 매핑을 등록하는 Registry.
+ * scope 별로 분리 보관 (예: 'fmsim', 'mms', 'wms').
+ *
+ * 백엔드 단일 프로세스 안에서 in-memory 로 유지된다. 모듈 부트스트랩 시 등록.
+ */
+import type { ComponentCategory, ImportRule, SubscriptionRule, ThreeDPreset } from '../types/registry'
+
+/**
+ * 코어가 제공하는 카테고리별 기본 3D Preset.
+ * 앱이 자기 도메인 preset 을 등록 안 해도, 카테고리만 정의되면 합리적 3D 표현.
+ *
+ * 매칭 우선순위: app preset(componentType) → app preset(category) → 이 디폴트(category) → unknown 디폴트
+ */
+const CORE_DEFAULT_PRESETS_BY_CATEGORY: Record<ComponentCategory, ThreeDPreset> = {
+  container: { category: 'container', geometry: { kind: 'box', height: 3000 }, material: { color: '#888888', roughness: 0.7 }, origin: 'bottom' },
+  vehicle:   { category: 'vehicle',   geometry: { kind: 'box', height: 800 },  material: { color: '#3a8c5e' }, origin: 'bottom' },
+  path:      { category: 'path',      geometry: { kind: 'extrude', depth: 100 }, material: { color: '#bccfe0' } },
+  region:    { category: 'region',    geometry: { kind: 'extrude', depth: 10 },  material: { color: '#a3d9ff', opacity: 0.4 } },
+  equipment: { category: 'equipment', geometry: { kind: 'box', height: 2000 }, material: { color: '#777777' }, origin: 'bottom' },
+  io:        { category: 'io',        geometry: { kind: 'box', height: 200 },  material: { color: '#ffcc66' }, origin: 'bottom' },
+  marker:    { category: 'marker',    geometry: { kind: 'box', height: 100 },  material: { color: '#ffffff' } },
+  structure: { category: 'structure', geometry: { kind: 'extrude', depth: 4000 }, material: { color: '#dddddd', opacity: 0.3 }, origin: 'bottom' },
+  unknown:   { category: 'unknown',   geometry: { kind: 'box', height: 500 },  material: { color: '#aaaaaa', opacity: 0.7 }, origin: 'bottom' }
+}
+
+interface ScopedRegistry<T> {
+  [scope: string]: T[]
+}
+
+const importRulesByScope: ScopedRegistry<ImportRule> = {}
+const threeDPresetsByScope: ScopedRegistry<ThreeDPreset> = {}
+const subscriptionRulesByScope: ScopedRegistry<SubscriptionRule> = {}
+
+// ── ImportRule ─────────────────────────────────────────────────────
+
+export function registerImportRules(scope: string, rules: ImportRule[]): void {
+  importRulesByScope[scope] = (importRulesByScope[scope] || []).concat(rules)
+}
+
+export function getImportRules(scopes?: string[]): ImportRule[] {
+  if (!scopes || scopes.length === 0) {
+    return Object.values(importRulesByScope).flat()
+  }
+  return scopes.flatMap(s => importRulesByScope[s] || [])
+}
+
+export function clearImportRules(scope: string): void {
+  delete importRulesByScope[scope]
+}
+
+// ── 3D Preset ──────────────────────────────────────────────────────
+
+export function register3DPresets(scope: string, presets: ThreeDPreset[]): void {
+  threeDPresetsByScope[scope] = (threeDPresetsByScope[scope] || []).concat(presets)
+}
+
+export function get3DPresets(scopes?: string[]): ThreeDPreset[] {
+  if (!scopes || scopes.length === 0) {
+    return Object.values(threeDPresetsByScope).flat()
+  }
+  return scopes.flatMap(s => threeDPresetsByScope[s] || [])
+}
+
+/**
+ * 컴포넌트 type + category 로 3D preset 을 찾는다.
+ * 우선순위:
+ *   1) 앱 등록 preset 중 componentType 정확 일치
+ *   2) 앱 등록 preset 중 category 일치
+ *   3) 코어 디폴트 카테고리 preset
+ *   4) 코어 디폴트 'unknown' preset
+ */
+export function find3DPreset(
+  componentType: string,
+  category?: ComponentCategory,
+  scopes?: string[]
+): ThreeDPreset {
+  const appPresets = get3DPresets(scopes)
+
+  const exact = appPresets.find(p => p.componentType === componentType)
+  if (exact) return exact
+
+  if (category) {
+    const byCategory = appPresets.find(p => p.category === category && !p.componentType)
+    if (byCategory) return byCategory
+
+    if (CORE_DEFAULT_PRESETS_BY_CATEGORY[category]) {
+      return CORE_DEFAULT_PRESETS_BY_CATEGORY[category]
+    }
+  }
+
+  return CORE_DEFAULT_PRESETS_BY_CATEGORY.unknown
+}
+
+export function clear3DPresets(scope: string): void {
+  delete threeDPresetsByScope[scope]
+}
+
+// ── Subscription Rule ──────────────────────────────────────────────
+
+export function registerSubscriptionRules(scope: string, rules: SubscriptionRule[]): void {
+  subscriptionRulesByScope[scope] = (subscriptionRulesByScope[scope] || []).concat(rules)
+}
+
+export function getSubscriptionRules(scopes?: string[]): SubscriptionRule[] {
+  if (!scopes || scopes.length === 0) {
+    return Object.values(subscriptionRulesByScope).flat()
+  }
+  return scopes.flatMap(s => subscriptionRulesByScope[s] || [])
+}
+
+export function findSubscriptionRule(
+  componentType: string,
+  scopes?: string[]
+): SubscriptionRule | undefined {
+  return getSubscriptionRules(scopes).find(r => r.componentType === componentType)
+}
+
+export function clearSubscriptionRules(scope: string): void {
+  delete subscriptionRulesByScope[scope]
+}
+
+export function clearAllRegistries(): void {
+  for (const k of Object.keys(importRulesByScope)) delete importRulesByScope[k]
+  for (const k of Object.keys(threeDPresetsByScope)) delete threeDPresetsByScope[k]
+  for (const k of Object.keys(subscriptionRulesByScope)) delete subscriptionRulesByScope[k]
+}

package/server/service/types/index.ts

@@ -0,0 +1,169 @@
+/**
+ * Universal Entity — 도면 형식(DXF/IFC/이미지/SVG/glTF)에 무관한 통일 모델.
+ * 모든 Format Adapter 가 이 타입으로 정규화한다.
+ */
+export type EntityKind = 'group' | 'shape' | 'path' | 'text' | 'mesh3d' | 'image-region'
+
+export interface Vec2 {
+  x: number
+  y: number
+}
+
+export interface Vec3 {
+  x: number
+  y: number
+  z: number
+}
+
+export interface Size2 {
+  width: number
+  height: number
+}
+
+export interface Size3 {
+  width: number
+  height: number
+  depth: number
+}
+
+export interface BoundingBox {
+  min: Vec2
+  max: Vec2
+}
+
+export interface UniversalEntity {
+  /** 도면 내 고유 ID */
+  uid: string
+  /** 엔티티 종류 */
+  kind: EntityKind
+  /** 위치 (좌상단 또는 중심 — 어댑터별로 정규화 정책 명시) */
+  position: Vec2
+  /** 크기 (없을 수도 있음, e.g. text) */
+  size?: Size2
+  /** 회전 (도수, 시계방향) */
+  rotation?: number
+  /** 이 엔티티의 bounding box */
+  bbox: BoundingBox
+  /** 의미적 단서 — 가능한 만큼 채움 */
+  attribs: EntityAttribs
+  /** 공간 관계 (선택) */
+  neighbors?: EntityRelation[]
+  /** 3D 자산 참조 (3D 형식만) */
+  meshRef?: string
+}
+
+export interface EntityAttribs {
+  /** 블록 이름, IFC GlobalId, 식별자 */
+  name?: string
+  /** CAD 레이어 이름 */
+  layer?: string
+  /** IFC 의미 클래스 (예: 'IfcStockerStorage') */
+  semanticType?: string
+  /** 텍스트 내용 (text 종류일 때) */
+  text?: string
+  /** 도면 모양 종류 (rect/circle/polyline 등) */
+  shape?: 'rect' | 'circle' | 'polyline' | 'polygon'
+  /**
+   * 카테고리 힌트 — AI 분류기 / 매처가 구체 type 까지는 못 정해도 카테고리만 줄 때 사용.
+   * Stage2 매핑이 ImportRule 매치에 실패하면 이 값을 보고 카테고리별 generic-* placeholder
+   * 로 폴백한다 (`MappingOptions.categoryFallback`).
+   */
+  categoryHint?: import('./registry').ComponentCategory
+  /** 임의 추가 속성 */
+  [k: string]: any
+}
+
+export interface EntityRelation {
+  uid: string
+  relation: 'adjacent' | 'inside' | 'connected' | 'labeled-by'
+  distance?: number
+}
+
+/**
+ * Adapter 결과 — 정규화된 entity 목록 + 메타데이터.
+ *
+ * 단일 변형이 default. AI/VLM 어댑터는 추가로 `variants` (다중 시안) 를 줄 수 있음 —
+ * 같은 도면을 다르게 해석한 후보들. 사용자가 review 단계에서 선택. variants[0] 와
+ * 최상위 entities 는 동일 (default 시안).
+ */
+export interface ParseResult {
+  entities: UniversalEntity[]
+  metadata: AdapterMetadata
+  bbox: BoundingBox
+  /** 도면 단위 (mm/m/inch 등). 명시되지 않으면 'unknown' */
+  units?: 'mm' | 'cm' | 'm' | 'inch' | 'unknown'
+  /**
+   * 다중 시안 (AI 가 같은 도면을 다른 관점으로 해석). 미지정 시 단일 변형 (default 만).
+   * 각 시안은 자기 entities + 자기 subjectName/Description + 자기 importStrategy.
+   */
+  variants?: ParseVariant[]
+}
+
+/**
+ * AI 가 제공하는 다중 해석 시안 — 같은 도면, 다른 관점/분류 전략.
+ * 예: "장비 중심" / "운송 중심" / "영역 중심" — 또는 "보수적" / "균형" / "공격적".
+ */
+export interface ParseVariant {
+  /** URL 친화적 short id — materialize 시 사용. */
+  id: string
+  /** 사용자에게 보여줄 한글 라벨. 예: "장비 중심", "운송 중심". */
+  label: string
+  /** 짧은 한 줄 설명 (선택) — 이 시안이 뭘 강조하는가. */
+  description?: string
+  entities: UniversalEntity[]
+  bbox?: BoundingBox
+  /** 도면 정체성 — 짧은 제목 (보드 name 추천 기반). */
+  subjectName?: string
+  /** 도면 정체성 — 1-2 문장 설명 (보드 description 추천 기반). */
+  subjectDescription?: string
+  /** AI 의 의도 narrative — 왜 이 시안을 이렇게 해석했나. review 카드 표시. */
+  importStrategy?: string
+}
+
+export interface AdapterMetadata {
+  format: string
+  formatVersion?: string
+  source?: string
+  /** 어댑터가 알아낸 추가 메타 (예: DXF $INSUNITS) */
+  [k: string]: any
+}
+
+export interface ParseOptions {
+  /** 최대 entity 수 (성능 가드) */
+  maxEntities?: number
+  /** 무시할 레이어 이름들 */
+  excludeLayers?: string[]
+  /** 추가 옵션 */
+  [k: string]: any
+}
+
+/**
+ * Adapter 입력 — 백엔드/프론트엔드 양쪽에서 사용 가능하도록 최대한 폭넓게 수용.
+ *  - string: DXF 등 텍스트 포맷의 본문
+ *  - Buffer: Node 환경의 파일 바이너리
+ *  - ArrayBuffer / Uint8Array: 바이너리 페이로드
+ */
+export type AdapterInput = string | ArrayBuffer | Uint8Array | Buffer
+
+/**
+ * Format Adapter — 형식별 파서. 모든 어댑터는 동일 인터페이스 구현.
+ */
+export interface FormatAdapter {
+  readonly format: string
+  readonly supportedExtensions: string[]
+  readonly capabilities: AdapterCapabilities
+
+  /** 파일이 이 어댑터로 처리 가능한지 빠른 검사 (확장자 + 시그니처) */
+  detect(file: AdapterInput, filename?: string): Promise<boolean>
+
+  /** 실제 파싱 → UniversalEntity 목록 */
+  parse(file: AdapterInput, options?: ParseOptions): Promise<ParseResult>
+}
+
+export interface AdapterCapabilities {
+  has2D: boolean
+  has3D: boolean
+  hasSemanticLabels: boolean
+  hasTextLabels: boolean
+  hasAttributes: boolean
+}

package/server/service/types/registry.ts

@@ -0,0 +1,186 @@
+import type { EntityKind, UniversalEntity } from './index'
+
+/**
+ * Universal Component Category — 도메인 비종속 분류 체계.
+ * 코어가 정의하며, 모든 앱이 공유. 새 카테고리 추가는 코어 변경 필요.
+ *
+ * 도메인 type ('Stocker', 'AGV') 과 별개로, 모든 컴포넌트는 카테고리에 속함.
+ * AI 추론 / 기본 3D Preset / Cross-app 호환성의 기반.
+ */
+export type ComponentCategory =
+  | 'container'   // Stocker, Buffer, Shelf, Rack — 정적 보관소
+  | 'vehicle'     // AGV, OHT, Forklift, AMR — 이동체
+  | 'path'        // Conveyor, AGVLine, OHTLine — 이동 경로
+  | 'region'      // Zone, Area, Floor — 영역
+  | 'equipment'   // Machine, Workstation, Robot — 작업 설비
+  | 'io'          // Port, Dock, Gate — 입출력 지점
+  | 'marker'      // Label, Sign, Gauge — 표시·계측
+  | 'structure'   // Wall, Pillar, Door — 건축 구조
+  | 'unknown'     // 분류 미상 (GenericObject 로 변환됨)
+
+/**
+ * ImportRule — 앱이 등록하는 매핑 규칙.
+ * 한 entity 가 어떤 컴포넌트 type 으로 변환될지 결정.
+ */
+export interface ImportRule {
+  /** 결과 컴포넌트 type (예: 'Stocker', 'AGV', 'Conveyor') */
+  componentType: string
+
+  /**
+   * Universal Category. 권장값. 누락 시 'unknown'.
+   * AI 추론 / 기본 3D preset 폴백의 기반.
+   */
+  category?: ComponentCategory
+
+  /** 매칭 조건 — 하나라도 해당되면 매칭. 모두 비어있으면 항상 매칭 안 됨. */
+  match: ImportMatcher
+
+  /** 결과 변환 정책 */
+  build: ImportBuildSpec
+
+  /** 충돌 시 우선순위 (높을수록 먼저). 기본 0 */
+  priority?: number
+}
+
+export interface ImportMatcher {
+  /** CAD (DXF/SVG) 매칭 */
+  cad?: {
+    /** INSERT 블록 이름 패턴 */
+    blockNamePattern?: RegExp
+    /** 레이어 이름 (정확 일치 또는 정규식) */
+    layer?: string | RegExp
+    /** entity 종류 화이트리스트 */
+    entityKinds?: EntityKind[]
+    /** 인접 텍스트 패턴 (라벨 매칭) */
+    textAdjacent?: RegExp
+  }
+
+  /** IFC 매칭 */
+  ifc?: {
+    /** IFC 클래스명 (예: 'IfcStockerStorage', 또는 정규식) */
+    ifcClass?: string | RegExp
+    /** PropertySet 의 특정 속성 */
+    propertySet?: { name: string; value?: any }
+  }
+
+  /** 이미지(VLM) 매칭 — VLM 응답의 라벨 후보 */
+  image?: {
+    labels: string[]
+  }
+
+  /** 모양/크기 기반 매칭 (모든 형식 공통) */
+  geometry?: {
+    shape?: 'rect' | 'circle' | 'polyline' | 'polygon'
+    sizeRange?: { minArea?: number; maxArea?: number }
+    aspectRatio?: { min?: number; max?: number }
+  }
+}
+
+export interface ImportBuildSpec {
+  /** 컴포넌트 기본 상태 */
+  defaultState?: Record<string, any>
+  /** ID 부여 전략 */
+  idStrategy?: IdStrategy
+  /** 사용자 정의 변환 (있으면 우선) */
+  transform?: (entity: UniversalEntity, draft: ComponentDraft) => ComponentDraft
+}
+
+export type IdStrategy =
+  | 'fromAttribute' // attribs.name 사용
+  | 'fromAdjacentText' // 인접 텍스트 라벨
+  | 'fromIfcGlobalId'
+  | 'auto' // 'TYPE_001' 자동 생성
+  | { custom: (entity: UniversalEntity) => string }
+
+/**
+ * Stage 2/3 의 중간 결과. 보드 모델 컴포넌트로 변환되기 직전 상태.
+ */
+export interface ComponentDraft {
+  /** Universal category. 항상 채워짐 (rule 누락 시 'unknown') */
+  category: ComponentCategory
+  /** 도메인 type. 'unknown' 카테고리면 'GenericObject' */
+  type: string
+  id?: string
+  state: Record<string, any>
+  /** 매칭된 ImportRule (디버깅/검수용). 'unknown' 이면 undefined */
+  matchedBy?: ImportRule
+  /** 원본 entity (재참조 / 매핑 검토용 / 변환 시 단서) */
+  source?: UniversalEntity
+}
+
+/**
+ * 3D Preset — 컴포넌트 type 또는 카테고리에 대한 3D 기본 표현.
+ *
+ * 매칭 우선순위:
+ *   1) componentType 정확 일치
+ *   2) componentType 없으면 category 폴백
+ *   3) 둘 다 없으면 코어 기본 'unknown' preset
+ */
+export interface ThreeDPreset {
+  /** 정확 매칭용 도메인 type. category 와 둘 중 하나는 필수. */
+  componentType?: string
+  /** 카테고리 단위 폴백 매칭 */
+  category?: ComponentCategory
+  geometry: ThreeDGeometry
+  material?: ThreeDMaterial
+  /** bbox 기준점 — bottom: 바닥 닿음, center: 중심 */
+  origin?: 'bottom' | 'center'
+  /** 후처리 훅 */
+  postProcess?: (componentState: Record<string, any>) => void
+}
+
+export type ThreeDGeometry =
+  | { kind: 'box'; height: number }
+  | { kind: 'cylinder'; height: number; radius: number }
+  | { kind: 'gltf'; url: string; scale?: number }
+  | { kind: 'extrude'; depth: number; bevel?: boolean }
+
+export interface ThreeDMaterial {
+  color?: string
+  roughness?: number
+  metalness?: number
+  texture?: string
+  opacity?: number
+}
+
+/**
+ * Subscription Rule — 컴포넌트 type ↔ 데이터 소스 태그 매핑.
+ */
+export interface SubscriptionRule {
+  componentType: string
+  /** 데이터 소스 태그 (예: 'MCS_LV_VEHICLE') */
+  tag: string
+  /** 응답 record 의 ID 필드 (default 'NAME') */
+  idField?: string
+  /** 추가 필드 매핑 (서버 필드 → 컴포넌트 상태) */
+  fieldMappings?: Record<string, string>
+}
+
+/**
+ * 매핑 결과 — Stage 2 의 출력.
+ *
+ * 모든 entity 가 ComponentDraft 가 됨:
+ *  - 매칭 성공: 도메인 type (e.g. 'Stocker', category='container')
+ *  - 매칭 실패: 'GenericObject' (category='unknown') — 좌표/원본 attribs 보존
+ *
+ * 사용자가 'GenericObject' 를 사후에 도메인 type 으로 변환 가능 (`convertGenericTo`).
+ */
+export interface MappingResult {
+  /** 모든 컴포넌트 draft (도메인 + GenericObject) */
+  components: ComponentDraft[]
+  /** 매핑 통계 */
+  stats: {
+    total: number
+    matched: number   // 도메인 type 으로 분류
+    generic: number   // GenericObject 로 폴백
+    skipped: number   // 무시 (예: 레이어 제외 등)
+  }
+  /** 경고 / 충돌 정보 */
+  warnings: MappingWarning[]
+}
+
+export interface MappingWarning {
+  level: 'info' | 'warn' | 'error'
+  entity?: UniversalEntity
+  message: string
+}

package/things-factory.config.js

@@ -0,0 +1 @@
+export default {}