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

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@things-factory/board-import",
+  "version": "10.0.0-beta.64",
+  "main": "dist-server/index.js",
+  "things-factory": true,
+  "author": "heartyoh",
+  "description": "도면(CAD/이미지/IFC) → Operato Board (2D + 3D) → 데이터 바인딩 통합 import 파이프라인 (백엔드 코어)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "@things-factory:registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hatiolab/things-factory.git",
+    "directory": "packages/board-import"
+  },
+  "scripts": {
+    "build": "npm run clean:server && tsc --p tsconfig.json",
+    "build:server": "npm run clean:server && tsc",
+    "clean:server": "rm -rf dist-server",
+    "clean": "npm run clean:server"
+  },
+  "dependencies": {
+    "@operato/graphql": "^10.0.0-beta.1",
+    "@things-factory/ai-client-base": "^10.0.0-beta.64",
+    "@things-factory/attachment-base": "^10.0.0-beta.57",
+    "@things-factory/auth-base": "^10.0.0-beta.57",
+    "@things-factory/env": "^10.0.0-beta.19",
+    "@things-factory/shell": "^10.0.0-beta.53",
+    "dxf-parser": "^1.1.2"
+  },
+  "gitHead": "8a2729cb8c838ed8fc3c7921fa67f7279c2d13b1"
+}

package/server/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @things-factory/board-import — 도면(CAD/이미지/IFC) → Board Model 백엔드 코어.
+ *
+ * Phase 1: DXF 결정적 파이프라인 (AI 미사용).
+ * Phase 2+: GraphQL/REST 엔드포인트, AI 통합.
+ */
+export * from './service/index.js'

package/server/service/adapters/dxf-adapter.ts

@@ -0,0 +1,217 @@
+/**
+ * DXF Format Adapter — DXF 텍스트 파일을 UniversalEntity 목록으로 정규화.
+ *
+ * 백엔드 환경(Node.js)에서 동작. 입력은 string / Buffer / ArrayBuffer / Uint8Array 모두 허용.
+ *
+ * 구현 범위 (Phase 1):
+ *   - INSERT (블록 참조) → kind='shape', attribs.name 추출
+ *   - LWPOLYLINE / POLYLINE → kind='path'
+ *   - CIRCLE → kind='shape', attribs.shape='circle'
+ *   - LINE → kind='path' (단일 선분)
+ *   - TEXT / MTEXT → kind='text'
+ *   - 레이어, 좌표, 회전 추출
+ *   - $INSUNITS 단위 추출
+ *
+ * 보류 (Phase 2+):
+ *   - HATCH, SPLINE, ELLIPSE 의 정밀 변환
+ *   - 블록 정의 안의 entities 깊이 펼치기
+ *   - 외부 참조 (XREF)
+ */
+import DxfParser from 'dxf-parser'
+
+import type {
+  AdapterCapabilities,
+  AdapterInput,
+  BoundingBox,
+  FormatAdapter,
+  ParseOptions,
+  ParseResult,
+  UniversalEntity
+} from '../types/index.js'
+
+const DXF_INSUNITS_TO_UNITS: Record<number, ParseResult['units']> = {
+  0: 'unknown',
+  1: 'inch',
+  4: 'mm',
+  5: 'cm',
+  6: 'm'
+}
+
+export class DxfAdapter implements FormatAdapter {
+  readonly format = 'dxf'
+  readonly supportedExtensions = ['.dxf']
+  readonly capabilities: AdapterCapabilities = {
+    has2D: true,
+    has3D: false,
+    hasSemanticLabels: false,
+    hasTextLabels: true,
+    hasAttributes: true
+  }
+
+  async detect(file: AdapterInput, filename?: string): Promise<boolean> {
+    if (filename && filename.toLowerCase().endsWith('.dxf')) return true
+    const head = readHead(file, 256)
+    return /\b0\s*\n\s*SECTION\b/.test(head) || /^\s*999/.test(head)
+  }
+
+  async parse(file: AdapterInput, options: ParseOptions = {}): Promise<ParseResult> {
+    const text = readText(file)
+    const parser = new DxfParser()
+    const dxf = parser.parseSync(text)
+
+    if (!dxf) throw new Error('DXF 파싱 실패')
+
+    const entities: UniversalEntity[] = []
+    let uidCounter = 0
+    const nextUid = () => `dxf-${++uidCounter}`
+
+    const excludeLayers = new Set((options.excludeLayers || []).map(l => l.toLowerCase()))
+    const maxEntities = options.maxEntities ?? 100000
+
+    for (const e of dxf.entities || []) {
+      if (entities.length >= maxEntities) break
+
+      const layer = (e as any).layer || ''
+      if (excludeLayers.has(layer.toLowerCase())) continue
+
+      const ue = entityToUniversal(e, layer, nextUid())
+      if (ue) entities.push(ue)
+    }
+
+    const bbox = computeBoundingBox(entities)
+    const units = DXF_INSUNITS_TO_UNITS[(dxf.header as any)?.$INSUNITS ?? 0]
+
+    return {
+      entities,
+      metadata: {
+        format: 'dxf',
+        formatVersion: (dxf.header as any)?.$ACADVER,
+        ...((dxf.header as any) || {})
+      },
+      bbox,
+      units
+    }
+  }
+}
+
+// ── DXF entity → UniversalEntity ─────────────────────────────────────
+
+function entityToUniversal(e: any, layer: string, uid: string): UniversalEntity | null {
+  const type = e.type as string
+
+  switch (type) {
+    case 'INSERT': {
+      const x = e.position?.x ?? 0
+      const y = e.position?.y ?? 0
+      const width = (e.xScale ?? 1) * 1
+      const height = (e.yScale ?? 1) * 1
+      return {
+        uid,
+        kind: 'shape',
+        position: { x, y },
+        size: { width, height },
+        rotation: e.rotation ?? 0,
+        bbox: { min: { x, y }, max: { x: x + width, y: y + height } },
+        attribs: {
+          name: e.name,
+          layer,
+          shape: 'rect'
+        }
+      }
+    }
+
+    case 'CIRCLE': {
+      const cx = e.center?.x ?? 0
+      const cy = e.center?.y ?? 0
+      const r = e.radius ?? 0
+      return {
+        uid,
+        kind: 'shape',
+        position: { x: cx - r, y: cy - r },
+        size: { width: 2 * r, height: 2 * r },
+        bbox: { min: { x: cx - r, y: cy - r }, max: { x: cx + r, y: cy + r } },
+        attribs: { layer, shape: 'circle' }
+      }
+    }
+
+    case 'LWPOLYLINE':
+    case 'POLYLINE': {
+      const verts: { x: number; y: number }[] = (e.vertices || []).map((v: any) => ({ x: v.x, y: v.y }))
+      if (verts.length === 0) return null
+      const xs = verts.map(v => v.x)
+      const ys = verts.map(v => v.y)
+      const min = { x: Math.min(...xs), y: Math.min(...ys) }
+      const max = { x: Math.max(...xs), y: Math.max(...ys) }
+      return {
+        uid,
+        kind: 'path',
+        position: { x: min.x, y: min.y },
+        size: { width: max.x - min.x, height: max.y - min.y },
+        bbox: { min, max },
+        attribs: { layer, shape: 'polyline', vertices: verts, closed: !!e.shape }
+      }
+    }
+
+    case 'LINE': {
+      const x1 = e.vertices?.[0]?.x ?? 0
+      const y1 = e.vertices?.[0]?.y ?? 0
+      const x2 = e.vertices?.[1]?.x ?? 0
+      const y2 = e.vertices?.[1]?.y ?? 0
+      const min = { x: Math.min(x1, x2), y: Math.min(y1, y2) }
+      const max = { x: Math.max(x1, x2), y: Math.max(y1, y2) }
+      return {
+        uid,
+        kind: 'path',
+        position: { x: min.x, y: min.y },
+        size: { width: max.x - min.x, height: max.y - min.y },
+        bbox: { min, max },
+        attribs: { layer, shape: 'polyline', vertices: [{ x: x1, y: y1 }, { x: x2, y: y2 }] }
+      }
+    }
+
+    case 'TEXT':
+    case 'MTEXT': {
+      const x = e.position?.x ?? e.startPoint?.x ?? 0
+      const y = e.position?.y ?? e.startPoint?.y ?? 0
+      const text = e.text ?? e.string ?? ''
+      const h = e.textHeight ?? e.height ?? 1
+      return {
+        uid,
+        kind: 'text',
+        position: { x, y },
+        bbox: { min: { x, y }, max: { x: x + h * (text.length || 1), y: y + h } },
+        attribs: { layer, text }
+      }
+    }
+
+    default:
+      return null
+  }
+}
+
+// ── 유틸 ─────────────────────────────────────────────────────────────
+
+function computeBoundingBox(entities: UniversalEntity[]): BoundingBox {
+  if (entities.length === 0) return { min: { x: 0, y: 0 }, max: { x: 0, y: 0 } }
+  let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity
+  for (const e of entities) {
+    if (e.bbox.min.x < minX) minX = e.bbox.min.x
+    if (e.bbox.min.y < minY) minY = e.bbox.min.y
+    if (e.bbox.max.x > maxX) maxX = e.bbox.max.x
+    if (e.bbox.max.y > maxY) maxY = e.bbox.max.y
+  }
+  return { min: { x: minX, y: minY }, max: { x: maxX, y: maxY } }
+}
+
+function readText(file: AdapterInput): string {
+  if (typeof file === 'string') return file
+  if (Buffer.isBuffer(file)) return file.toString('utf-8')
+  if (file instanceof Uint8Array) return Buffer.from(file).toString('utf-8')
+  if (file instanceof ArrayBuffer) return Buffer.from(new Uint8Array(file)).toString('utf-8')
+  throw new Error('Unsupported DXF input type')
+}
+
+function readHead(file: AdapterInput, maxBytes: number): string {
+  const text = readText(file)
+  return text.substring(0, maxBytes)
+}

package/server/service/ai/types.ts

@@ -0,0 +1,284 @@
+/**
+ * BoardImportAI — board-import 의 **도메인 AI 인터페이스**.
+ *
+ * Provider 추상화 (chat/JSON/vision) 는 `@things-factory/ai-client-base` 의 `AIClient` 가 담당.
+ * 이 모듈은 board-import 의 도메인 메서드 (컨벤션 추론, Few-shot 분류, 도면 이미지 파싱,
+ * 자연어 → ImportRule) 만 정의하고, 기본 구현은 base AIClient 위에 LLM 프롬프트로 만든다.
+ *
+ * 사용 예:
+ * ```ts
+ * import { createAIClient } from '@things-factory/ai-client-base'
+ * import { setAIClient, DefaultBoardImportAI } from '@things-factory/board-import'
+ *
+ * const base = createAIClient({ provider: 'anthropic', apiKey: '...' })
+ * setAIClient(new DefaultBoardImportAI(base))
+ * ```
+ *
+ * Phase 1-2 결정적 파이프라인은 AI 미사용. 위 등록은 Phase 3+ 메서드 활성화용.
+ */
+import { parseJSONResponse, type AIClient as BaseAIClient } from '@things-factory/ai-client-base'
+import type { ComponentCategory, ImportRule } from '../types/registry.js'
+import type { UniversalEntity } from '../types/index.js'
+
+export interface BoardImportAI {
+  /** 식별자 — 보통 base.id 와 동일 (provider:model) */
+  readonly id: string
+
+  /**
+   * 미매칭 entity 묶음을 보고 컨벤션 규칙을 추론.
+   * 예: "STK_001, STK_002 가 stocker 인 것 같습니다" → 정규식 규칙 제안
+   */
+  inferConventions?(
+    entities: UniversalEntity[],
+    options?: ConventionInferenceOptions
+  ): Promise<RuleSuggestion[]>
+
+  /**
+   * 사용자가 일부 entity 를 라벨링했을 때, 나머지 미라벨 entity 의 카테고리·type 을 추론.
+   * Few-shot 분류.
+   */
+  classifyEntities?(
+    labeled: LabeledEntity[],
+    unlabeled: UniversalEntity[],
+    options?: ClassificationOptions
+  ): Promise<EntityClassification[]>
+
+  /**
+   * 도면 이미지(PNG/JPG/PDF 페이지) 에서 객체를 검출하여 UniversalEntity 로 변환.
+   * Phase 3 (이미지 어댑터) 에서 사용.
+   */
+  parseFromImage?(
+    image: Buffer | Uint8Array,
+    options?: ImageParseOptions
+  ): Promise<UniversalEntity[]>
+
+  /**
+   * 자연어 매핑 정의 ("STK는 stocker, BUF는 buffer") → ImportRule[] 로 변환.
+   */
+  parseNaturalLanguageMapping?(
+    text: string,
+    availableTypes: string[]
+  ): Promise<ImportRule[]>
+}
+
+// ── 옵션 / 결과 타입 ────────────────────────────────────────────────
+
+export interface ConventionInferenceOptions {
+  /** 알려진 도메인 type 후보 (LLM 이 이 안에서 고르도록) */
+  knownTypes?: string[]
+  /** 카테고리 후보 */
+  categories?: ComponentCategory[]
+  /** 최대 제안 개수 */
+  maxSuggestions?: number
+}
+
+export interface RuleSuggestion {
+  /** 자동 생성된 ImportRule 후보 */
+  rule: ImportRule
+  /** 0..1 신뢰도 */
+  confidence: number
+  /** 추론 근거 */
+  reasoning?: string
+}
+
+export interface ClassificationOptions {
+  knownTypes?: string[]
+  categories?: ComponentCategory[]
+}
+
+export interface LabeledEntity {
+  entity: UniversalEntity
+  type: string
+  category?: ComponentCategory
+}
+
+export interface EntityClassification {
+  entityUid: string
+  type: string
+  category: ComponentCategory
+  confidence: number
+}
+
+export interface ImageParseOptions {
+  /** 자연어 컨텍스트. 예: "factory floor plan with AGV paths" */
+  context?: string
+  categories?: ComponentCategory[]
+}
+
+// ── 기본 구현 — base AIClient 위에 LLM 프롬프트로 ────────────────────
+
+export class DefaultBoardImportAI implements BoardImportAI {
+  readonly id: string
+  constructor(private base: BaseAIClient) {
+    this.id = base.id
+  }
+
+  async inferConventions(
+    entities: UniversalEntity[],
+    options: ConventionInferenceOptions = {}
+  ): Promise<RuleSuggestion[]> {
+    const sample = entities.slice(0, 100).map(e => ({
+      uid: e.uid,
+      name: e.attribs.name,
+      layer: e.attribs.layer,
+      kind: e.kind,
+      shape: e.attribs.shape
+    }))
+    const knownTypes = options.knownTypes ?? []
+    const categories = options.categories ?? []
+    const maxSuggestions = options.maxSuggestions ?? 5
+
+    const prompt = `You analyze CAD/IFC drawing entities and infer naming/layer conventions for an import pipeline.
+
+Unmatched entities (sample):
+${JSON.stringify(sample, null, 2)}
+
+Available component types: ${knownTypes.length ? knownTypes.join(', ') : '(any)'}
+Available categories: ${categories.length ? categories.join(', ') : '(any)'}
+
+Suggest up to ${maxSuggestions} convention rules. For each, return:
+- rule.componentType: chosen type
+- rule.category: one of available categories (or 'unknown')
+- rule.match.cad.blockNamePattern: regex pattern source string (e.g. "^STK_")
+- rule.match.cad.layer: optional regex source string
+- rule.build.idStrategy: 'fromAttribute' or 'auto'
+- confidence: 0..1
+- reasoning: short explanation`
+
+    const raw = await this.base.generateJSON<any[]>(prompt, { systemPrompt: SYSTEM_HINT })
+    return Array.isArray(raw) ? raw.map(r => ({ ...r, rule: hydrateRuleRegexes(r.rule) })) : []
+  }
+
+  async classifyEntities(
+    labeled: LabeledEntity[],
+    unlabeled: UniversalEntity[],
+    options: ClassificationOptions = {}
+  ): Promise<EntityClassification[]> {
+    const examples = labeled.map(l => ({
+      name: l.entity.attribs.name,
+      layer: l.entity.attribs.layer,
+      kind: l.entity.kind,
+      type: l.type,
+      category: l.category
+    }))
+    const targets = unlabeled.map(e => ({
+      uid: e.uid,
+      name: e.attribs.name,
+      layer: e.attribs.layer,
+      kind: e.kind
+    }))
+
+    const prompt = `Few-shot entity classification.
+
+Labeled examples:
+${JSON.stringify(examples, null, 2)}
+
+Available types: ${(options.knownTypes ?? []).join(', ') || '(any)'}
+Available categories: ${(options.categories ?? []).join(', ') || '(any)'}
+
+Classify these unlabeled entities. Return JSON array of:
+- entityUid
+- type
+- category
+- confidence: 0..1
+
+Targets:
+${JSON.stringify(targets, null, 2)}`
+
+    const raw = await this.base.generateJSON<EntityClassification[]>(prompt, { systemPrompt: SYSTEM_HINT })
+    return Array.isArray(raw) ? raw : []
+  }
+
+  async parseFromImage(
+    image: Buffer | Uint8Array,
+    options: ImageParseOptions = {}
+  ): Promise<UniversalEntity[]> {
+    if (!this.base.vision) {
+      throw new Error(`AI client (${this.base.id}) does not support vision input`)
+    }
+    const prompt = `Detect distinct objects in this drawing image.${
+      options.context ? '\nContext: ' + options.context : ''
+    }${
+      options.categories ? '\nPossible categories: ' + options.categories.join(', ') : ''
+    }
+
+Return JSON array of UniversalEntity-like objects:
+- uid: string
+- kind: 'shape' | 'path' | 'text'
+- position: {x, y}
+- size: {width, height}
+- bbox: {min:{x,y}, max:{x,y}}
+- attribs: {name?, semanticType?, text?, layer?}`
+
+    const text = await this.base.vision(image as Buffer, prompt)
+    return parseJSONResponse<UniversalEntity[]>(text)
+  }
+
+  async parseNaturalLanguageMapping(
+    text: string,
+    availableTypes: string[]
+  ): Promise<ImportRule[]> {
+    const prompt = `Convert the following user description into ImportRule[] entries for the board-import pipeline.
+
+Description: "${text}"
+Available component types: ${availableTypes.join(', ')}
+
+Return JSON array of:
+- componentType
+- category (one of: container, vehicle, path, region, equipment, io, marker, structure, unknown)
+- match.cad.blockNamePattern: regex source string (e.g. "^STK_")
+- match.cad.layer: optional regex source string
+- build.idStrategy: 'fromAttribute' or 'auto'`
+
+    const raw = await this.base.generateJSON<any[]>(prompt, { systemPrompt: SYSTEM_HINT })
+    return Array.isArray(raw) ? raw.map(hydrateRuleRegexes) : []
+  }
+}
+
+// ── 유틸 ─────────────────────────────────────────────────────────────
+
+const SYSTEM_HINT =
+  'You are a CAD/IFC drawing analysis assistant. Output strict JSON only — no commentary, no markdown.'
+
+/**
+ * LLM 응답의 regex pattern 문자열 → 실제 RegExp.
+ * 보통 "^STK_" 같은 source string 으로 응답.
+ */
+function hydrateRuleRegexes<T extends { match?: any }>(rule: T): T {
+  if (!rule || !rule.match) return rule
+  const cad = rule.match.cad
+  if (cad) {
+    const newCad = { ...cad }
+    if (typeof newCad.blockNamePattern === 'string') {
+      try {
+        newCad.blockNamePattern = new RegExp(newCad.blockNamePattern)
+      } catch {
+        // invalid regex — 패턴 무시
+        delete newCad.blockNamePattern
+      }
+    }
+    if (typeof newCad.layer === 'string') {
+      const m = newCad.layer.match(/^\/(.+)\/([a-z]*)$/)
+      if (m) {
+        try { newCad.layer = new RegExp(m[1], m[2]) } catch { /* keep as string */ }
+      }
+    }
+    rule.match = { ...rule.match, cad: newCad }
+  }
+  return rule
+}
+
+// ── Provider 등록 ──────────────────────────────────────────────────
+
+let currentClient: BoardImportAI | undefined
+
+export function setAIClient(client: BoardImportAI | undefined): void {
+  currentClient = client
+}
+
+export function getAIClient(): BoardImportAI | undefined {
+  return currentClient
+}
+
+/** Deprecated alias — 기존 코드 호환용. 새로 작성 시 BoardImportAI 사용. */
+export type AIClient = BoardImportAI

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

@@ -0,0 +1,98 @@
+/**
+ * GenericObject ↔ 도메인 컴포넌트 변환.
+ *
+ * Import 시 매칭되지 않은 entity 는 GenericObject 로 보드에 배치된다.
+ * 사용자가 사후에 모델러 UI 에서 "Convert to Stocker" 등 액션으로 호출.
+ *
+ * 변환 시:
+ *   - 좌표/크기/회전 보존
+ *   - source (원본 entity attribs) 보존
+ *   - 등록된 ImportRule.build 의 defaultState / idStrategy 적용
+ */
+import { find3DPreset, getImportRules } from '../registry/index.js'
+import type { BoardComponent } from '../pipeline/stage3-board.js'
+import type { ComponentCategory } from '../types/registry.js'
+import { GENERIC_OBJECT_TYPE } from '../pipeline/stage2-mapping.js'
+
+export interface ConvertOptions {
+  scopes?: string[]
+  /** 새 컴포넌트의 ID. 미지정 시 ImportRule 의 idStrategy 적용 또는 자동 생성 */
+  id?: string
+}
+
+/**
+ * GenericObject 를 지정된 도메인 type 으로 변환한다.
+ * 기존 좌표/크기/회전/source 보존.
+ */
+export function convertGenericTo(
+  generic: BoardComponent,
+  toType: string,
+  options: ConvertOptions = {}
+): BoardComponent {
+  if (generic.type !== GENERIC_OBJECT_TYPE) {
+    throw new Error(`Source component is not GenericObject (type=${generic.type})`)
+  }
+
+  const rules = getImportRules(options.scopes)
+  const rule = rules.find(r => r.componentType === toType)
+
+  const category: ComponentCategory = rule?.category ?? 'unknown'
+  const newId = options.id ?? generic.id
+
+  const preset = find3DPreset(toType, category, options.scopes)
+  const threeD = {
+    geometry: preset.geometry,
+    ...(preset.material && { material: preset.material }),
+    origin: preset.origin ?? 'bottom'
+  }
+
+  const { strokeStyle, strokeDashArray, fillStyle, label, ...preservedState } = generic
+
+  return {
+    ...preservedState,
+    category,
+    type: toType,
+    id: newId,
+    threeD,
+    ...(rule?.build.defaultState || {}),
+    /**
+     * 변환 추적 — 되돌리기 가능하게 source 보존.
+     * `convertedFrom` 키는 board-modeller UI 에서 "되돌리기" 액션 활성화 단서.
+     */
+    convertedFrom: {
+      type: GENERIC_OBJECT_TYPE,
+      previousState: { strokeStyle, strokeDashArray, fillStyle, label }
+    }
+  }
+}
+
+/**
+ * 변환된 컴포넌트를 다시 GenericObject 로 되돌린다.
+ * convertedFrom 정보가 있어야 가능.
+ */
+export function revertToGeneric(
+  component: BoardComponent,
+  options: ConvertOptions = {}
+): BoardComponent {
+  const previous = (component as any).convertedFrom?.previousState
+  if (!previous) {
+    throw new Error('이 컴포넌트는 GenericObject 에서 변환된 것이 아닙니다 (convertedFrom 없음).')
+  }
+
+  const preset = find3DPreset(GENERIC_OBJECT_TYPE, 'unknown', options.scopes)
+  const threeD = {
+    geometry: preset.geometry,
+    ...(preset.material && { material: preset.material }),
+    origin: preset.origin ?? 'bottom'
+  }
+
+  const { convertedFrom, ...rest } = component as any
+
+  return {
+    ...rest,
+    category: 'unknown',
+    type: GENERIC_OBJECT_TYPE,
+    threeD,
+    ...previous
+  }
+}