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

package/server/service/import-session/import-session-resolver.ts

@@ -0,0 +1,113 @@
+/**
+ * ImportSession resolver + 비동기 worker.
+ *
+ * Mutation:
+ *   - importBoardAsync(attachmentId, options): ImportSession (즉시 반환, 백그라운드에서 처리)
+ *
+ * Query:
+ *   - importSession(id): ImportSession (진행 상황 polling)
+ *
+ * 비동기 worker 는 단일 프로세스 내 setImmediate 기반. 추후 큐(Redis/BullMQ) 로 이전 가능.
+ */
+import { Resolver, Query, Mutation, Arg, Ctx, Directive, Field, InputType } from 'type-graphql'
+import { GraphQLJSON } from 'graphql-scalars'
+import '@things-factory/auth-base'
+
+import { getRepository } from '@things-factory/shell'
+
+import { ImportSession } from './import-session.js'
+import { runImportJob } from './import-worker.js'
+
+@InputType()
+class ImportBoardAsyncInput {
+  @Field({ description: 'Attachment id of the source drawing file (uploaded via attachment-base).' })
+  attachmentId!: string
+
+  @Field({ nullable: true, description: 'ChatSession id when triggered from board-ai chat.' })
+  chatSessionId?: string
+
+  @Field(() => [String], { nullable: true, description: 'Registry scopes to use (board-import).' })
+  scopes?: string[]
+
+  @Field({ nullable: true, description: 'Normalize coordinates so minX,minY=0' })
+  normalizeOrigin?: boolean
+
+  @Field({ nullable: true, description: 'Flip Y axis (CAD Y-up → scene Y-down).' })
+  flipY?: boolean
+
+  @Field({ nullable: true, description: 'Scale factor (e.g. 1 for mm:1unit).' })
+  scale?: number
+
+  @Field({ nullable: true, description: 'Apply Stage 4 (data binding).' })
+  applyBinding?: boolean
+
+  @Field(() => GraphQLJSON, { nullable: true, description: 'Adapter parse options (excludeLayers, maxEntities, ...).' })
+  parseOptions?: any
+}
+
+@Resolver()
+export class ImportSessionResolver {
+  @Query(() => ImportSession, { nullable: true, description: 'Get import session progress.' })
+  @Directive('@privilege(category: "board-import", privilege: "query")')
+  async importSession(
+    @Arg('id') id: string,
+    @Ctx() context: ResolverContext
+  ): Promise<ImportSession | null> {
+    const { domain } = context.state
+    return (await getRepository(ImportSession).findOneBy({ id, domain: { id: domain.id } })) ?? null
+  }
+
+  @Query(() => [ImportSession], { description: 'List recent import sessions for a chat session.' })
+  @Directive('@privilege(category: "board-import", privilege: "query")')
+  async importSessionsByChatSession(
+    @Arg('chatSessionId') chatSessionId: string,
+    @Ctx() context: ResolverContext
+  ): Promise<ImportSession[]> {
+    const { domain } = context.state
+    return await getRepository(ImportSession).find({
+      where: { chatSessionId, domain: { id: domain.id } },
+      order: { createdAt: 'DESC' },
+      take: 50
+    })
+  }
+
+  @Mutation(() => ImportSession, {
+    description: '도면 → 보드 변환을 비동기로 시작. 즉시 ImportSession 반환, 백그라운드에서 처리.'
+  })
+  @Directive('@privilege(category: "board-import", privilege: "mutation")')
+  async importBoardAsync(
+    @Arg('input') input: ImportBoardAsyncInput,
+    @Ctx() context: ResolverContext
+  ): Promise<ImportSession> {
+    const { domain, user } = context.state
+    const repo = getRepository(ImportSession)
+
+    const session = await repo.save({
+      domain,
+      attachmentId: input.attachmentId,
+      chatSessionId: input.chatSessionId,
+      status: 'queued',
+      progress: 0,
+      message: 'Queued',
+      optionsJson: JSON.stringify({
+        scopes: input.scopes,
+        normalizeOrigin: input.normalizeOrigin,
+        flipY: input.flipY,
+        scale: input.scale,
+        applyBinding: input.applyBinding,
+        parseOptions: input.parseOptions
+      }),
+      creator: user
+    } as any)
+
+    // 비동기 worker 시작 — 응답은 이미 즉시 반환됨
+    setImmediate(() => {
+      runImportJob(session.id!).catch(err => {
+        // worker 내부에서 처리되지만 안전망
+        console.error('[board-import] runImportJob unhandled:', err)
+      })
+    })
+
+    return session
+  }
+}

package/server/service/import-session/import-session.ts

@@ -0,0 +1,141 @@
+/**
+ * ImportSession — 도면(Attachment) → BoardModel 변환 작업 단위.
+ *
+ * 비동기 워크플로우:
+ *   1) 클라이언트가 importBoardAsync(attachmentId) 호출 → ImportSession 즉시 반환 (status:'queued')
+ *   2) 백그라운드 worker 가 attachment 본문 → importBoard() 실행 → status 갱신
+ *   3) 클라이언트는 polling 또는 subscription 으로 진행 상황 추적
+ *   4) status='completed' 시 result 에 BoardModel + stats + warnings 포함
+ *
+ * board-ai 의 ChatSession 과 연결 가능 (chatSessionId) — chat 안에서 자동 발동되면 진행 메시지가
+ * 자동으로 ChatMessage(role:'system') 으로 기록되어 AI 컨텍스트에 흐름.
+ */
+import {
+  Column,
+  CreateDateColumn,
+  Entity,
+  Index,
+  ManyToOne,
+  PrimaryGeneratedColumn,
+  RelationId,
+  UpdateDateColumn
+} from 'typeorm'
+import { Field, Float, ID, Int, ObjectType } from 'type-graphql'
+import { GraphQLJSON } from 'graphql-scalars'
+
+import { Domain } from '@things-factory/shell'
+import { User } from '@things-factory/auth-base'
+import { config } from '@things-factory/env'
+
+const ORMCONFIG = config.get('ormconfig', {})
+const DATABASE_TYPE = ORMCONFIG.type
+
+@Entity()
+@Index('ix_import_session_1', (session: ImportSession) => [session.domain, session.createdAt])
+@Index('ix_import_session_2', (session: ImportSession) => [session.chatSessionId])
+@ObjectType({ description: '도면 → 보드 변환 작업의 영속 단위 (비동기 진행상태 추적).' })
+export class ImportSession {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(type => ID, { nullable: true })
+  readonly id?: string
+
+  @ManyToOne(type => Domain)
+  @Field(type => Domain, { nullable: true })
+  domain?: Domain
+
+  @RelationId((session: ImportSession) => session.domain)
+  domainId?: string
+
+  /** Attachment.id (도면 파일). attachment-base 의존이지만 직접 ManyToOne 대신 ID 만 보유. */
+  @Column()
+  @Field({ description: 'Attachment id (the source drawing file)' })
+  attachmentId!: string
+
+  /** 어느 ChatSession 에서 발동됐는지 (board-ai 와 연동). 없으면 직접 호출. */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'ChatSession id when triggered from chat (board-ai).' })
+  chatSessionId?: string
+
+  /** 'queued' | 'parsing' | 'mapping' | 'assembling' | 'binding' | 'completed' | 'failed' */
+  @Column({ type: 'varchar', length: 32, default: 'queued' })
+  @Field({ description: 'queued | parsing | mapping | assembling | binding | completed | failed' })
+  status!: string
+
+  /** 0..100 */
+  @Column({ type: 'float', default: 0 })
+  @Field(type => Float, { description: 'Progress percentage 0..100' })
+  progress!: number
+
+  /** 현재 단계 설명 또는 에러 메시지 */
+  @Column({ nullable: true, type: 'text' })
+  @Field({ nullable: true })
+  message?: string
+
+  /** import 옵션 (scopes, parseOptions, normalizeOrigin 등) */
+  @Column({
+    nullable: true,
+    type:
+      DATABASE_TYPE == 'mysql' || DATABASE_TYPE == 'mariadb'
+        ? 'longtext'
+        : DATABASE_TYPE == 'oracle'
+          ? 'clob'
+          : DATABASE_TYPE == 'mssql'
+            ? 'nvarchar'
+            : 'text',
+    length: DATABASE_TYPE == 'mssql' ? 'MAX' : undefined
+  })
+  optionsJson?: string
+
+  @Field(type => GraphQLJSON, { nullable: true, description: 'Options used (parsed JSON).' })
+  get options(): any {
+    try {
+      return this.optionsJson ? JSON.parse(this.optionsJson) : null
+    } catch {
+      return null
+    }
+  }
+
+  /** 결과: { boardModel, mapping: { stats, warnings } } */
+  @Column({
+    nullable: true,
+    type:
+      DATABASE_TYPE == 'mysql' || DATABASE_TYPE == 'mariadb'
+        ? 'longtext'
+        : DATABASE_TYPE == 'oracle'
+          ? 'clob'
+          : DATABASE_TYPE == 'mssql'
+            ? 'nvarchar'
+            : 'text',
+    length: DATABASE_TYPE == 'mssql' ? 'MAX' : undefined
+  })
+  resultJson?: string
+
+  @Field(type => GraphQLJSON, { nullable: true, description: 'Result (parsed JSON): { boardModel, stats, warnings }.' })
+  get result(): any {
+    try {
+      return this.resultJson ? JSON.parse(this.resultJson) : null
+    } catch {
+      return null
+    }
+  }
+
+  @Column({ nullable: true })
+  @Field(type => Int, { nullable: true, description: 'Total entities counted (when known).' })
+  totalEntities?: number
+
+  @ManyToOne(type => User)
+  @Field(type => User, { nullable: true })
+  creator?: User
+
+  @CreateDateColumn()
+  @Field({ nullable: true })
+  createdAt?: Date
+
+  @UpdateDateColumn()
+  @Field({ nullable: true })
+  updatedAt?: Date
+
+  @Column({ nullable: true })
+  @Field({ nullable: true })
+  completedAt?: Date
+}

package/server/service/import-session/import-worker.ts

@@ -0,0 +1,88 @@
+/**
+ * Background worker — ImportSession 처리.
+ *
+ * 흐름:
+ *   1) ImportSession 로드 (status: queued)
+ *   2) Attachment 본문 읽기 (attachment-base STORAGE.readFile)
+ *   3) importBoard() 실행 (단계별로 status/progress 갱신)
+ *   4) result 저장 + status='completed'
+ *   5) 실패 시 status='failed' + message
+ *
+ * 단일 프로세스 내 setImmediate 기반. 추후 외부 큐(Redis/BullMQ) 로 이전 가능.
+ */
+import { getRepository } from '@things-factory/shell'
+
+import { Attachment } from '@things-factory/attachment-base'
+import { STORAGE } from '@things-factory/attachment-base'
+
+import { importBoard } from '../pipeline/index.js'
+import { ImportSession } from './import-session.js'
+
+export async function runImportJob(sessionId: string): Promise<void> {
+  const repo = getRepository(ImportSession)
+  const session = await repo.findOneBy({ id: sessionId })
+  if (!session) {
+    console.error(`[board-import] ImportSession ${sessionId} not found`)
+    return
+  }
+
+  try {
+    await update(repo, sessionId, { status: 'parsing', progress: 5, message: 'Reading attachment' })
+
+    const attachment = await getRepository(Attachment).findOneBy({ id: session.attachmentId })
+    if (!attachment) {
+      throw new Error(`Attachment ${session.attachmentId} not found`)
+    }
+
+    // attachment-base STORAGE.readFile 으로 본문 로드 (Buffer)
+    const fileBuffer = STORAGE.readFile(attachment.path!, null) as Buffer
+
+    await update(repo, sessionId, { status: 'parsing', progress: 20, message: 'Parsing drawing' })
+
+    const opts = session.options || {}
+    const filename = attachment.name || attachment.path
+
+    // importBoard 는 내부에서 stage 1~4 모두 수행. 단계별 progress 는 우선 거시적 업데이트.
+    await update(repo, sessionId, { status: 'mapping', progress: 50, message: 'Mapping entities' })
+
+    const result = await importBoard({
+      file: fileBuffer,
+      filename,
+      scopes: opts.scopes,
+      normalizeOrigin: opts.normalizeOrigin,
+      flipY: opts.flipY,
+      scale: opts.scale,
+      applyBinding: opts.applyBinding,
+      parseOptions: opts.parseOptions
+    })
+
+    await update(repo, sessionId, { status: 'assembling', progress: 80, message: 'Assembling board' })
+
+    const resultJson = JSON.stringify({
+      boardModel: result.boardModel,
+      stats: result.mapping.stats,
+      warnings: result.mapping.warnings
+    })
+
+    await update(repo, sessionId, {
+      status: 'completed',
+      progress: 100,
+      message: `Completed: ${result.mapping.stats.matched} matched, ${result.mapping.stats.generic} generic`,
+      totalEntities: result.mapping.stats.total,
+      resultJson,
+      completedAt: new Date()
+    })
+  } catch (err) {
+    const message = (err as Error)?.message ?? String(err)
+    console.error(`[board-import] ImportSession ${sessionId} failed:`, err)
+    await update(repo, sessionId, {
+      status: 'failed',
+      message: `Failed: ${message}`,
+      completedAt: new Date()
+    })
+  }
+}
+
+async function update(repo: any, id: string, patch: Partial<ImportSession>): Promise<void> {
+  await repo.update(id, patch as any)
+}

package/server/service/import-session/index.ts

@@ -0,0 +1,8 @@
+import { ImportSession } from './import-session.js'
+import { ImportSessionResolver } from './import-session-resolver.js'
+
+export { ImportSession, ImportSessionResolver }
+export { runImportJob } from './import-worker.js'
+
+export const entities = [ImportSession]
+export const resolverClasses = [ImportSessionResolver]

package/server/service/index.ts

@@ -0,0 +1,96 @@
+// ImportSession (비동기 import) — things-factory 모듈 통합용
+import {
+  entities as ImportSessionEntities,
+  resolverClasses as ImportSessionResolverClasses
+} from './import-session/index.js'
+export * from './import-session/index.js'
+
+export const entities = [...ImportSessionEntities]
+export const schema = { resolverClasses: [...ImportSessionResolverClasses] }
+
+// Pipeline (high-level)
+export { importBoard } from './pipeline/index.js'
+export type { ImportOptions, ImportResult } from './pipeline/index.js'
+
+// Stage 별 (low-level)
+export { applyMapping, GENERIC_OBJECT_TYPE } from './pipeline/stage2-mapping.js'
+export { assembleBoard } from './pipeline/stage3-board.js'
+export { applyDataBinding } from './pipeline/stage4-binding.js'
+export type { BoardModel, BoardComponent, AssembleOptions } from './pipeline/stage3-board.js'
+export type { MappingOptions } from './pipeline/stage2-mapping.js'
+export type { BindingOptions } from './pipeline/stage4-binding.js'
+
+// Converters
+export { convertGenericTo, revertToGeneric } from './converters/generic-to.js'
+export type { ConvertOptions } from './converters/generic-to.js'
+
+// Adapters
+export { DxfAdapter } from './adapters/dxf-adapter.js'
+
+// Registry
+export {
+  registerImportRules,
+  registerSubscriptionRules,
+  register3DPresets,
+  getImportRules,
+  getSubscriptionRules,
+  get3DPresets,
+  find3DPreset,
+  findSubscriptionRule,
+  clearImportRules,
+  clearSubscriptionRules,
+  clear3DPresets,
+  clearAllRegistries
+} from './registry/index.js'
+
+// Types — Universal Entity
+export type {
+  EntityKind,
+  EntityAttribs,
+  EntityRelation,
+  Vec2,
+  Vec3,
+  Size2,
+  Size3,
+  BoundingBox,
+  UniversalEntity,
+  ParseResult,
+  AdapterMetadata,
+  ParseOptions,
+  AdapterInput,
+  FormatAdapter,
+  AdapterCapabilities
+} from './types/index.js'
+
+// Types — Registry
+export type {
+  ComponentCategory,
+  ImportRule,
+  ImportMatcher,
+  ImportBuildSpec,
+  IdStrategy,
+  ComponentDraft,
+  ThreeDPreset,
+  ThreeDGeometry,
+  ThreeDMaterial,
+  SubscriptionRule,
+  MappingResult,
+  MappingWarning
+} from './types/registry.js'
+
+// AI domain interface (Phase 3+) — provider 추상화는 @things-factory/ai-client-base
+export {
+  setAIClient,
+  getAIClient,
+  DefaultBoardImportAI
+} from './ai/types.js'
+export type {
+  BoardImportAI,
+  AIClient, // deprecated alias for BoardImportAI
+  ConventionInferenceOptions,
+  RuleSuggestion,
+  ClassificationOptions,
+  LabeledEntity,
+  EntityClassification,
+  ImageParseOptions
+} from './ai/types.js'

package/server/service/pipeline/index.ts

@@ -0,0 +1,89 @@
+/**
+ * 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.js'
+import type { AdapterInput, FormatAdapter, ParseOptions, ParseResult } from '../types/index.js'
+import type { MappingResult } from '../types/registry.js'
+import { applyMapping } from './stage2-mapping.js'
+import { assembleBoard, type AssembleOptions, type BoardModel } from './stage3-board.js'
+import { applyDataBinding } from './stage4-binding.js'
+
+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
+}
+
+const DEFAULT_ADAPTERS: FormatAdapter[] = [new DxfAdapter()]
+
+export async function importBoard(opts: ImportOptions): Promise<ImportResult> {
+  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 mapping = applyMapping(parsed, { scopes: opts.scopes })
+
+  const assembleOptions: AssembleOptions = {
+    scopes: opts.scopes,
+    normalizeOrigin: opts.normalizeOrigin ?? true,
+    flipY: opts.flipY ?? true,
+    scale: opts.scale ?? 1,
+    importMeta: {
+      format: adapter.format,
+      sourceBbox: parsed.bbox,
+      units: parsed.units,
+      importedAt: new Date().toISOString()
+    }
+  }
+  let boardModel = assembleBoard(mapping.components, parsed.bbox, assembleOptions)
+
+  if (opts.applyBinding !== false) {
+    boardModel = applyDataBinding(boardModel, { scopes: opts.scopes })
+  }
+
+  return { boardModel, 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.js'
+export { assembleBoard } from './stage3-board.js'
+export { applyDataBinding } from './stage4-binding.js'
+export type { BoardModel, BoardComponent, AssembleOptions } from './stage3-board.js'
+export type { MappingOptions } from './stage2-mapping.js'
+export type { BindingOptions } from './stage4-binding.js'