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

package/server/service/import-tools.ts

@@ -0,0 +1,255 @@
+/**
+ * board-import 의 LLM tool 카테고리 등록.
+ *
+ * board-ai 의 chat 흐름 안에서 사용자가 "이 도면을 보드로 만들어줘" / "import 결과 검수
+ * 후 이 이름으로 저장" 같은 자연어를 발화하면 LLM 이 본 카테고리의 tool 들을 호출한다.
+ *
+ * 노출되는 tool:
+ *   - listImportAdapters       (read)     : 등록된 FormatAdapter 능력 조회
+ *   - importBoardAsync         (external) : Attachment → ImportSession 비동기 시작
+ *   - getImportSession         (read)     : ImportSession 진행/결과 조회
+ *   - materializeImportSession (external) : ImportSession.result → 새 Board entity
+ *
+ * dispatch wiring:
+ *   board-ai 의 chat 메서드가 ToolCallContext (resolver state — domain/user/tx) 를 closure 로
+ *   주입한다. builder 는 ctx.state 에서 typeorm getRepository / domain / user 를 추출해
+ *   service-level 함수 (import-actions, materialize-from-session) 를 호출한다.
+ *
+ *   이 layer 가 없으면 builder 가 typeorm 에 직접 의존해야 했고, board-ai 가 typeorm 까지
+ *   알게 되는 leakage 가 생겼을 것 — 의도적으로 builder 가 ctx.state.typeorm 같은 식으로
+ *   접근하지 않고 things-factory 표준 getRepository 를 호출.
+ */
+import { getRepository } from '@things-factory/shell'
+import {
+  registerToolCategory,
+  type ToolCategory,
+  type ToolSpec
+} from '@things-factory/ai-client-base'
+
+// 모든 server-side 의존성 (entity / service 함수 / 외부 패키지) 은 module-level import
+// 없이 lazy require — module load 만으로 typeorm decorator / 외부 controllers chain
+// (예: board-service 의 puppeteer pool) 이 평가되어 jest 환경에서 깨지는 것을 회피.
+// 운영에서는 builder 첫 호출 시 cache 채워져 이후 호출은 직접 dispatch.
+//
+// 이 패턴은 LLM tool layer 의 일반 정책으로 가져갈 수 있다 — registerToolCategory 가
+// 평가되는 시점은 server bootstrap 의 매우 이른 단계라, 그때 typeorm DataSource init 이
+// 아직 끝나지 않았을 가능성이 있다.
+let _depsCache: any | undefined
+function getDeps(): any {
+  if (!_depsCache) {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const isMod = require('./import-session/import-session')
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const bsMod = require('@things-factory/board-service')
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const actionsMod = require('./import-session/import-actions')
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const materializeMod = require('./import-session/materialize-from-session')
+    _depsCache = {
+      ImportSession: isMod.ImportSession,
+      Board: bsMod.Board,
+      Group: bsMod.Group,
+      startImportJobAsync: actionsMod.startImportJobAsync,
+      fetchImportSession: actionsMod.fetchImportSession,
+      describeAdapter: actionsMod.describeAdapter,
+      materializeFromSession: materializeMod.materializeFromSession
+    }
+  }
+  return _depsCache
+}
+
+/**
+ * tool builder 의 ctx.state 가 도메인 식별을 갖는지 검증. 미설정이면 명확한 에러로 실패 —
+ * board-ai 의 toolCallContext wiring 누락 / 비인증 호출 등을 빠르게 찾기 위해.
+ */
+function requireDomainContext(state: any): { domain: any; user: any } {
+  if (!state || !state.domain) {
+    throw new Error(
+      '[board-import] tool builder 의 ctx.state.domain 미설정. ' +
+        'board-ai 의 ChatOptions.toolCallContext 에 ResolverContext.state 가 전달됐는지 확인.'
+    )
+  }
+  return { domain: state.domain, user: state.user }
+}
+
+const importToolsCategory: ToolCategory = {
+  name: 'board-import',
+  description: 'Drawing/CAD/IFC/image → Board 변환 파이프라인 (zero-to-twin).',
+  specs: [
+    {
+      kind: 'read',
+      name: 'listImportAdapters',
+      description:
+        '등록된 도면 import 어댑터 (DXF / Image / 향후 IFC, glTF 등) 의 능력 조회. ' +
+        '사용자가 어떤 형식 import 가 가능한지 묻거나, LLM 이 적절한 어댑터 선택을 inspect 할 때 사용.',
+      schema: { type: 'object', properties: {} },
+      builder: async () => {
+        // 동적 import — pipeline 모듈의 DEFAULT_ADAPTERS 를 inspect.
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const pipelineModule = require('./pipeline/index')
+        const adapters: any[] = pipelineModule.DEFAULT_ADAPTERS ?? []
+        return adapters.map(getDeps().describeAdapter)
+      }
+    },
+    {
+      kind: 'external',
+      name: 'importBoardAsync',
+      description:
+        'Attachment(도면/조감도/사진) 을 비동기로 보드 모델로 변환 시작. 즉시 ImportSession 을 ' +
+        '반환하고 백그라운드에서 진행. status 가 completed 가 될 때까지 getImportSession 으로 ' +
+        'polling 해서 결과를 확인. 형식은 자동 감지 — DXF / GLTF / image 등.',
+      schema: {
+        type: 'object',
+        properties: {
+          attachmentId: {
+            type: 'string',
+            description: 'Attachment id (attachment-base 에 미리 업로드된 도면 파일).'
+          },
+          chatSessionId: {
+            type: 'string',
+            description: 'board-ai chat session id (선택). 진행 메시지가 chat 흐름에 합류.'
+          },
+          scopes: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'ImportRule 의 scope (예: ["fmsim"]). 도메인별 매핑 규칙 활성화.'
+          },
+          parseOptions: {
+            type: 'object',
+            description: 'Adapter 파싱 옵션 (excludeLayers / maxEntities / context 등).',
+            additionalProperties: true
+          }
+        },
+        required: ['attachmentId']
+      },
+      builder: async (args, ctx) => {
+        const { domain, user } = requireDomainContext(ctx?.state)
+        const session = await getDeps().startImportJobAsync(
+          {
+            attachmentId: args.attachmentId,
+            chatSessionId: args.chatSessionId,
+            scopes: args.scopes,
+            parseOptions: args.parseOptions
+          },
+          { domain, user },
+          getRepository(getDeps().ImportSession) as any
+        )
+        return {
+          sessionId: session.id,
+          status: session.status,
+          progress: session.progress,
+          message: session.message
+        }
+      }
+    },
+    {
+      kind: 'read',
+      name: 'getImportSession',
+      description:
+        'ImportSession 의 진행/결과 조회. status 가 queued/parsing/mapping/assembling/binding 인 ' +
+        '동안은 progress 와 message 를 반환, completed 면 result.boardModel 까지 포함. failed 면 ' +
+        'message 에 에러 사유.',
+      schema: {
+        type: 'object',
+        properties: {
+          sessionId: { type: 'string', description: 'ImportSession id (importBoardAsync 가 반환).' }
+        },
+        required: ['sessionId']
+      },
+      builder: async (args, ctx) => {
+        const { domain, user } = requireDomainContext(ctx?.state)
+        const session = await getDeps().fetchImportSession(
+          args.sessionId,
+          { domain, user },
+          getRepository(getDeps().ImportSession) as any
+        )
+        if (!session) return { found: false }
+        return {
+          found: true,
+          sessionId: session.id,
+          status: session.status,
+          progress: session.progress,
+          message: session.message,
+          // result 는 큰 boardModel 을 포함할 수 있어 status 가 completed 일 때만.
+          result: session.status === 'completed' ? session.result : undefined,
+          totalEntities: session.totalEntities,
+          completedAt: session.completedAt
+        }
+      }
+    },
+    {
+      kind: 'external',
+      name: 'materializeImportSession',
+      description:
+        '완료된 ImportSession 의 결과 boardModel 을 새 Board entity 로 영속화. status 가 ' +
+        'completed 인 세션만 처리. 결과 Board 는 state="draft" 로 생성되므로 사용자가 검수 후 ' +
+        '발행해야 한다.',
+      themeNote:
+        '⚠ 사용자의 명시적 confirm 후에만 호출. import 결과 미리보기를 보여주고 "이 이름으로 ' +
+        '저장하시겠어요?" 같은 확인 받은 다음 발동.',
+      schema: {
+        type: 'object',
+        properties: {
+          sessionId: { type: 'string' },
+          name: { type: 'string', description: '새 Board 이름 — 같은 도메인 내 unique.' },
+          description: { type: 'string' },
+          groupId: { type: 'string' },
+          type: { type: 'string', enum: ['main', 'sub', 'popup'] },
+          thumbnail: {
+            type: 'string',
+            description: 'Base64 thumbnail. 미지정 시 빈 placeholder 사용 (별도 thumbnail 생성 호출).'
+          }
+        },
+        required: ['sessionId', 'name']
+      },
+      builder: async (args, ctx) => {
+        const { domain, user } = requireDomainContext(ctx?.state)
+        const session = await getDeps().fetchImportSession(
+          args.sessionId,
+          { domain, user },
+          getRepository(getDeps().ImportSession) as any
+        )
+        const { Board, Group, materializeFromSession } = getDeps()
+        const board = await materializeFromSession(
+          session as any,
+          {
+            sessionId: args.sessionId,
+            name: args.name,
+            description: args.description,
+            groupId: args.groupId,
+            type: args.type,
+            thumbnail: args.thumbnail
+          },
+          { domain, user },
+          {
+            boardRepo: getRepository(Board) as any,
+            groupRepo: getRepository(Group) as any
+          }
+        )
+        // 큰 model 본문은 LLM 회신에서 제외 — id 와 메타만.
+        return {
+          boardId: (board as any).id,
+          name: (board as any).name,
+          state: (board as any).state,
+          sourceImportSessionId: (board as any).sourceImportSessionId
+        }
+      }
+    }
+  ] as ToolSpec[]
+}
+
+// 등록 — module 로드 시 side-effect.
+registerToolCategory(importToolsCategory)
+
+/**
+ * 명시적 register 함수 — 테스트나 lazy bootstrap 에서 import 만으로 발동되는 side-effect 가
+ * 부담스러울 때 import 후 명시 호출 가능.
+ */
+export function registerBoardImportTools(): void {
+  registerToolCategory(importToolsCategory)
+}
+
+/**
+ * 테스트용 — registerToolCategory 의 입력으로 사용된 카테고리 객체. 외부에서 inspect 가능.
+ */
+export const BOARD_IMPORT_TOOL_CATEGORY = importToolsCategory

package/server/service/index.ts

@@ -0,0 +1,117 @@
+// ImportSession (비동기 import) — things-factory 모듈 통합용
+import {
+  entities as ImportSessionEntities,
+  resolverClasses as ImportSessionResolverClasses
+} from './import-session/index'
+export * from './import-session/index'
+
+export const entities = [...ImportSessionEntities]
+export const schema = { resolverClasses: [...ImportSessionResolverClasses] }
+
+// Pipeline (high-level)
+export { importBoard } from './pipeline/index'
+export type { ImportOptions, ImportResult } from './pipeline/index'
+
+// Stage 별 (low-level)
+export {
+  applyMapping,
+  GENERIC_OBJECT_TYPE,
+  DEFAULT_CATEGORY_FALLBACK
+} from './pipeline/stage2-mapping'
+export { assembleBoard } from './pipeline/stage3-board'
+export { applyDataBinding } from './pipeline/stage4-binding'
+export type { BoardModel, BoardComponent, AssembleOptions } from './pipeline/stage3-board'
+export type { MappingOptions } from './pipeline/stage2-mapping'
+export type { BindingOptions } from './pipeline/stage4-binding'
+
+// Converters
+export {
+  convertGenericTo,         // deprecated alias — keep for backward-compat
+  convertPlaceholderTo,
+  isPlaceholderType,
+  CORE_PLACEHOLDER_TYPES
+} from './converters/generic-to'
+export type { ConvertOptions } from './converters/generic-to'
+
+// Adapters
+export { DxfAdapter } from './adapters/dxf-adapter'
+export { ImageAdapter } from './adapters/image-adapter'
+
+// Registry
+export {
+  registerImportRules,
+  registerSubscriptionRules,
+  register3DPresets,
+  getImportRules,
+  getSubscriptionRules,
+  get3DPresets,
+  find3DPreset,
+  findSubscriptionRule,
+  clearImportRules,
+  clearSubscriptionRules,
+  clear3DPresets,
+  clearAllRegistries
+} from './registry/index'
+
+// Types — Universal Entity
+export type {
+  EntityKind,
+  EntityAttribs,
+  EntityRelation,
+  Vec2,
+  Vec3,
+  Size2,
+  Size3,
+  BoundingBox,
+  UniversalEntity,
+  ParseResult,
+  AdapterMetadata,
+  ParseOptions,
+  AdapterInput,
+  FormatAdapter,
+  AdapterCapabilities
+} from './types/index'
+
+// Types — Registry
+export type {
+  ComponentCategory,
+  ImportRule,
+  ImportMatcher,
+  ImportBuildSpec,
+  IdStrategy,
+  ComponentDraft,
+  ThreeDPreset,
+  ThreeDGeometry,
+  ThreeDMaterial,
+  SubscriptionRule,
+  MappingResult,
+  MappingWarning
+} from './types/registry'
+
+// AI domain interface (Phase 3+) — provider 추상화는 @things-factory/ai-client-base
+export {
+  setAIClient,
+  getAIClient,
+  DefaultBoardImportAI
+} from './ai/types'
+
+// LLM tool 노출 — board-ai 의 chat 흐름이 자동 dispatch 가능하도록 등록.
+// import 시 module side-effect 로 registerToolCategory 발동. 명시 호출도 가능.
+export {
+  registerBoardImportTools,
+  BOARD_IMPORT_TOOL_CATEGORY
+} from './import-tools'
+export type {
+  BoardImportAI,
+  AIClient, // deprecated alias for BoardImportAI
+  ConventionInferenceOptions,
+  RuleSuggestion,
+  ClassificationOptions,
+  LabeledEntity,
+  EntityClassification,
+  ImageParseOptions
+} from './ai/types'
+
+// 하이브리드 추출 모듈 (Phase Board-AI §3.8) — 순수 추가. 네임스페이스로 묶어 충돌 회피.
+// 기존 어댑터/파이프라인(ImageAdapter, stage1-4) 무변경. 본격 테스트 단계에서 stub → 실 impl 교체.
+export * as extraction from './extraction'

package/server/service/pipeline/index.ts

@@ -0,0 +1,184 @@
+/**
+ * High-level Pipeline — 도면 한 장 → 운영 가능한 Board Model.
+ *
+ * 백엔드에서 호출:
+ * ```ts
+ * import { importBoard } from '@things-factory/board-import'
+ *
+ * const buf = await fs.promises.readFile(path)
+ * const result = await importBoard({ file: buf, filename: 'plant.dxf', scopes: ['fmsim'] })
+ * ```
+ */
+import { DxfAdapter } from '../adapters/dxf-adapter'
+import { ImageAdapter } from '../adapters/image-adapter'
+import type { AdapterInput, BoundingBox, FormatAdapter, ParseOptions, ParseResult } from '../types/index'
+import type { MappingResult } from '../types/registry'
+import { applyMapping } from './stage2-mapping'
+import { assembleBoard, type AssembleOptions, type BoardModel } from './stage3-board'
+import { applyDataBinding } from './stage4-binding'
+
+export interface ImportOptions {
+  file: AdapterInput
+  filename?: string
+  /** 등록된 매핑 규칙의 어느 scope 를 사용할지 */
+  scopes?: string[]
+  /** 어댑터 옵션 (excludeLayers 등) */
+  parseOptions?: ParseOptions
+  /** 좌표 normalize (좌상단 0,0) */
+  normalizeOrigin?: boolean
+  /** Y 축 뒤집기 (CAD Y-up → scene Y-down) */
+  flipY?: boolean
+  /** scene unit 변환 배율 */
+  scale?: number
+  /** 데이터 바인딩 stage 적용 여부 */
+  applyBinding?: boolean
+  /** 사용자 정의 어댑터 (있으면 디폴트 검색 대신 사용) */
+  adapter?: FormatAdapter
+}
+
+export interface ImportResult {
+  boardModel: BoardModel
+  mapping: MappingResult
+  parse: ParseResult
+}
+
+/**
+ * 변환 시안 (variant) — AI 가 같은 도면을 다른 관점으로 해석한 결과. 사용자가 review 단계에서
+ * 시각 비교 후 선택. parse 가 multi-variant 응답하면 (현재 ImageAdapter), 각 variant 마다
+ * 독립 mapping + assemble. DXF 같은 single-variant adapter 는 1 boardModel 만.
+ */
+export interface VariantResult {
+  id: string
+  label: string
+  description?: string
+  /** 보드 정체성 — name 자동 추천 기반. */
+  subjectName?: string
+  /** 보드 정체성 — description 자동 추천 기반. */
+  subjectDescription?: string
+  /** AI 의 의도 narrative — review 카드 표시 (transient). */
+  importStrategy?: string
+  boardModel: BoardModel
+  /** mapping 통계 (시안별 — entities 가 다르므로 stats 도 다름). */
+  stats: MappingResult['stats']
+}
+
+export interface ImportVariantsResult {
+  variants: VariantResult[]
+  /** 각 시안의 mapping 결과 묶음. variants[i] 와 같은 인덱스. */
+  mappings: MappingResult[]
+  parse: ParseResult
+}
+
+// Adapter detection 순서가 중요: 정밀 형식 (DXF) 먼저, 폴백 / 비정형 (Image) 나중.
+// detect() 가 filename 확장자 우선이라 충돌은 거의 없지만, 시그니처 모호한 경우 (예:
+// 확장자 없는 binary stream) 도 정밀 형식이 먼저 잡히는 게 안전.
+//
+// import-tools.ts 의 listImportAdapters builder 가 본 배열을 inspect — 외부 export.
+export const DEFAULT_ADAPTERS: FormatAdapter[] = [new DxfAdapter(), new ImageAdapter()]
+
+export async function importBoard(opts: ImportOptions): Promise<ImportResult> {
+  // 단일 변형 — multi-variant adapter 라도 첫 시안만 반환. back-compat.
+  const result = await importBoardVariants(opts)
+  const first = result.variants[0]
+  if (!first) {
+    throw new Error('Import produced no variants.')
+  }
+  return {
+    boardModel: first.boardModel,
+    mapping: result.mappings[0],
+    parse: result.parse
+  }
+}
+
+/**
+ * 다중 시안 import — parse 1번 (비싼 VLM/DXF), 시안별 mapping + assemble.
+ *
+ * AI multi-variant adapter (ImageAdapter) 는 parse.variants 에 N 시안 반환 → 각각 mapping +
+ * assemble. Single-variant adapter (DxfAdapter) 는 parse.variants 미존재 → 단일 시안 1 boardModel.
+ */
+export async function importBoardVariants(opts: ImportOptions): Promise<ImportVariantsResult> {
+  const adapter = opts.adapter ?? (await pickAdapter(opts.file, opts.filename))
+  if (!adapter) throw new Error('지원되지 않는 도면 형식이거나 어댑터를 식별할 수 없습니다.')
+
+  const parsed = await adapter.parse(opts.file, opts.parseOptions)
+  const importMeta = {
+    format: adapter.format,
+    sourceBbox: parsed.bbox,
+    units: parsed.units,
+    importedAt: new Date().toISOString()
+  }
+  const assembleOptions: AssembleOptions = {
+    scopes: opts.scopes,
+    normalizeOrigin: opts.normalizeOrigin ?? true,
+    flipY: opts.flipY ?? true,
+    scale: opts.scale ?? 1,
+    importMeta
+  }
+
+  // multi-variant adapter — parse.variants 가 존재
+  if (Array.isArray(parsed.variants) && parsed.variants.length > 0) {
+    const variants: VariantResult[] = []
+    const mappings: MappingResult[] = []
+    for (const v of parsed.variants) {
+      // 각 시안의 entities 로 mapping (시안별로 다름)
+      const variantParsed: ParseResult = {
+        ...parsed,
+        entities: v.entities,
+        bbox: v.bbox ?? parsed.bbox
+      }
+      const mapping = applyMapping(variantParsed, { scopes: opts.scopes })
+      mappings.push(mapping)
+      let boardModel = assembleBoard(mapping.components, variantParsed.bbox, assembleOptions)
+      if (opts.applyBinding !== false) {
+        boardModel = applyDataBinding(boardModel, { scopes: opts.scopes })
+      }
+      variants.push({
+        id: v.id,
+        label: v.label,
+        description: v.description,
+        subjectName: v.subjectName,
+        subjectDescription: v.subjectDescription,
+        importStrategy: v.importStrategy,
+        boardModel,
+        stats: mapping.stats
+      })
+    }
+    return { variants, mappings, parse: parsed }
+  }
+
+  // single-variant adapter (DXF 등) — 단일 boardModel
+  const mapping = applyMapping(parsed, { scopes: opts.scopes })
+  let boardModel = assembleBoard(mapping.components, parsed.bbox, assembleOptions)
+  if (opts.applyBinding !== false) {
+    boardModel = applyDataBinding(boardModel, { scopes: opts.scopes })
+  }
+  return {
+    variants: [
+      {
+        id: 'default',
+        label: 'default',
+        boardModel,
+        stats: mapping.stats
+      }
+    ],
+    mappings: [mapping],
+    parse: parsed
+  }
+}
+
+async function pickAdapter(
+  file: AdapterInput,
+  filename?: string
+): Promise<FormatAdapter | undefined> {
+  for (const a of DEFAULT_ADAPTERS) {
+    if (await a.detect(file, filename)) return a
+  }
+  return undefined
+}
+
+export { applyMapping } from './stage2-mapping'
+export { assembleBoard } from './stage3-board'
+export { applyDataBinding } from './stage4-binding'
+export type { BoardModel, BoardComponent, AssembleOptions } from './stage3-board'
+export type { MappingOptions } from './stage2-mapping'
+export type { BindingOptions } from './stage4-binding'