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

package/server/service/pipeline/stage2-mapping.ts

@@ -0,0 +1,195 @@
+/**
+ * Stage 2 — Universal Entities → Component Drafts.
+ * 등록된 ImportRule 들을 entity 마다 평가하여 컴포넌트 type 결정.
+ */
+import { getImportRules } from '../registry/index.js'
+import type { ParseResult, UniversalEntity } from '../types/index.js'
+import type {
+  ComponentDraft,
+  IdStrategy,
+  ImportMatcher,
+  MappingResult,
+  MappingWarning
+} from '../types/registry.js'
+
+/** 매핑되지 않은 entity 가 변환되는 placeholder 도메인 type. */
+export const GENERIC_OBJECT_TYPE = 'GenericObject'
+
+export interface MappingOptions {
+  /** 어떤 scope 의 규칙을 사용할지 (생략 시 전부) */
+  scopes?: string[]
+  /**
+   * 매칭 안 된 entity 를 GenericObject 로 변환할지 여부 (default: true).
+   * false 면 buffer 에서 제외되고 stats.skipped 로 카운트.
+   */
+  emitGeneric?: boolean
+}
+
+export function applyMapping(parsed: ParseResult, options: MappingOptions = {}): MappingResult {
+  const rules = getImportRules(options.scopes)
+    .slice()
+    .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0))
+
+  const components: ComponentDraft[] = []
+  const warnings: MappingWarning[] = []
+  const stats = { total: parsed.entities.length, matched: 0, generic: 0, skipped: 0 }
+
+  const usedIds = new Map<string, number>()
+  const emitGeneric = options.emitGeneric !== false
+
+  for (const entity of parsed.entities) {
+    const rule = rules.find(r => matchRule(r.match, entity))
+
+    if (!rule) {
+      if (!emitGeneric) {
+        stats.skipped++
+        continue
+      }
+      const draft = makeGenericDraft(entity, usedIds)
+      components.push(draft)
+      stats.generic++
+      continue
+    }
+
+    const id = resolveId(rule.build.idStrategy ?? 'auto', entity, rule.componentType, usedIds)
+    let draft: ComponentDraft = {
+      category: rule.category ?? 'unknown',
+      type: rule.componentType,
+      id,
+      state: { ...(rule.build.defaultState || {}) },
+      matchedBy: rule,
+      source: entity
+    }
+
+    if (rule.build.transform) {
+      try {
+        draft = rule.build.transform(entity, draft)
+      } catch (e) {
+        warnings.push({
+          level: 'warn',
+          entity,
+          message: `transform 실패 (${rule.componentType}): ${(e as Error).message}`
+        })
+      }
+    }
+
+    components.push(draft)
+    stats.matched++
+  }
+
+  return { components, stats, warnings }
+}
+
+/**
+ * 매칭되지 않은 entity 를 GenericObject draft 로 변환.
+ * 좌표·크기·원본 attribs 모두 보존하여 사후 변환 가능하게 한다.
+ */
+function makeGenericDraft(entity: UniversalEntity, usedIds: Map<string, number>): ComponentDraft {
+  const id = resolveId('auto', entity, GENERIC_OBJECT_TYPE, usedIds)
+  return {
+    category: 'unknown',
+    type: GENERIC_OBJECT_TYPE,
+    id,
+    state: {
+      strokeStyle: '#888888',
+      strokeDashArray: '4 4',
+      fillStyle: 'rgba(128,128,128,0.15)',
+      label: entity.attribs.name || entity.attribs.layer || entity.attribs.text || ''
+    },
+    source: entity
+  }
+}
+
+// ── 매칭 로직 ──────────────────────────────────────────────────────
+
+function matchRule(matcher: ImportMatcher, entity: UniversalEntity): boolean {
+  if (matcher.cad) {
+    const m = matcher.cad
+    let ok = true
+    if (m.blockNamePattern && !m.blockNamePattern.test(entity.attribs.name || '')) ok = false
+    if (m.layer && !matchString(m.layer, entity.attribs.layer || '')) ok = false
+    if (m.entityKinds && !m.entityKinds.includes(entity.kind)) ok = false
+    if (m.textAdjacent) {
+      const adjacentText = (entity.neighbors || [])
+        .filter(r => r.relation === 'labeled-by')
+        .map(r => r.uid)
+      if (!adjacentText.some(t => m.textAdjacent!.test(t))) ok = false
+    }
+    if (ok) return true
+  }
+
+  if (matcher.ifc) {
+    const m = matcher.ifc
+    let ok = true
+    if (m.ifcClass && !matchString(m.ifcClass, entity.attribs.semanticType || '')) ok = false
+    if (ok) return true
+  }
+
+  if (matcher.geometry) {
+    const g = matcher.geometry
+    let ok = true
+    if (g.shape && entity.attribs.shape !== g.shape) ok = false
+    if (g.sizeRange && entity.size) {
+      const area = entity.size.width * entity.size.height
+      if (g.sizeRange.minArea !== undefined && area < g.sizeRange.minArea) ok = false
+      if (g.sizeRange.maxArea !== undefined && area > g.sizeRange.maxArea) ok = false
+    }
+    if (g.aspectRatio && entity.size) {
+      const ratio = entity.size.height === 0 ? 1 : entity.size.width / entity.size.height
+      if (g.aspectRatio.min !== undefined && ratio < g.aspectRatio.min) ok = false
+      if (g.aspectRatio.max !== undefined && ratio > g.aspectRatio.max) ok = false
+    }
+    if (ok) return true
+  }
+
+  if (matcher.image && matcher.image.labels.length > 0) {
+    const label = entity.attribs.vlmLabel
+    if (label && matcher.image.labels.includes(label)) return true
+  }
+
+  return false
+}
+
+function matchString(pattern: string | RegExp, value: string): boolean {
+  if (typeof pattern === 'string') return pattern === value
+  return pattern.test(value)
+}
+
+// ── ID 부여 전략 ──────────────────────────────────────────────────
+
+function resolveId(
+  strategy: IdStrategy,
+  entity: UniversalEntity,
+  type: string,
+  usedIds: Map<string, number>
+): string {
+  let id: string | undefined
+
+  if (typeof strategy === 'object' && 'custom' in strategy) {
+    id = strategy.custom(entity)
+  } else {
+    switch (strategy) {
+      case 'fromAttribute':
+        id = entity.attribs.name
+        break
+      case 'fromAdjacentText':
+        id = (entity.neighbors || []).find(r => r.relation === 'labeled-by')?.uid
+        break
+      case 'fromIfcGlobalId':
+        id = entity.attribs.ifcGlobalId
+        break
+      case 'auto':
+      default:
+        id = undefined
+    }
+  }
+
+  if (!id) {
+    const seq = (usedIds.get(type) ?? 0) + 1
+    usedIds.set(type, seq)
+    id = `${type.toUpperCase()}_${String(seq).padStart(3, '0')}`
+  } else {
+    usedIds.set(id, (usedIds.get(id) ?? 0) + 1)
+  }
+  return id
+}

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

@@ -0,0 +1,114 @@
+/**
+ * Stage 3 — ComponentDraft → Board Model JSON.
+ * 좌표/단위 변환 + 3D Preset 적용.
+ */
+import { find3DPreset } from '../registry/index.js'
+import type { BoundingBox } from '../types/index.js'
+import type { ComponentCategory, ComponentDraft } from '../types/registry.js'
+
+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']
+}
+
+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
+
+  const boardWidth = (bbox.max.x - bbox.min.x) * scale
+  const boardHeight = (bbox.max.y - bbox.min.y) * scale
+
+  const components: BoardComponent[] = 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 top = options.flipY ? boardHeight - rawTop - (src?.size?.height ?? 0) * scale : rawTop
+    const width = (src?.size?.width ?? 1) * scale
+    const height = (src?.size?.height ?? 1) * scale
+    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,
+      top,
+      width,
+      height,
+      ...(rotation !== undefined && { rotation: options.flipY ? -rotation : rotation }),
+      threeD,
+      ...d.state
+    }
+  })
+
+  return {
+    width: boardWidth || 1000,
+    height: boardHeight || 1000,
+    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.js'
+import type { BoardComponent, BoardModel } from './stage3-board.js'
+
+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.js'
+
+/**
+ * 코어가 제공하는 카테고리별 기본 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,133 @@
+/**
+ * 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'
+  /** 임의 추가 속성 */
+  [k: string]: any
+}
+
+export interface EntityRelation {
+  uid: string
+  relation: 'adjacent' | 'inside' | 'connected' | 'labeled-by'
+  distance?: number
+}
+
+/**
+ * Adapter 결과 — 정규화된 entity 목록 + 메타데이터.
+ */
+export interface ParseResult {
+  entities: UniversalEntity[]
+  metadata: AdapterMetadata
+  bbox: BoundingBox
+  /** 도면 단위 (mm/m/inch 등). 명시되지 않으면 'unknown' */
+  units?: 'mm' | 'cm' | 'm' | 'inch' | 'unknown'
+}
+
+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
+}