@things-factory/board-import 10.0.0-beta.71 → 10.0.0-beta.73

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

@@ -1,43 +1,74 @@
 /**
- * GenericObject ↔ 도메인 컴포넌트 변환.
+ * Generic placeholder → 도메인 컴포넌트 변환.
  *
- * Import 시 매칭되지 않은 entity 는 GenericObject 로 보드에 배치된다.
- * 사용자가 사후에 모델러 UI 에서 "Convert to Stocker" 등 액션으로 호출.
+ * Import 시 매칭되지 않은 entity 는 `placeholder` 타입으로 보드에 배치된다.
+ * 사용자가 사후에 모델러 UI 에서 "Convert to ..." 액션으로 도메인 컴포넌트로 변환.
+ *
+ * 아키텍처 원칙:
+ *   - `placeholder` — 도메인 비종속 임시 추상. 다른 type 으로 변환하는 기능만.
+ *     GLB 지원 없음 (GltfComponent mixin 제거됨).
+ *   - 도메인 generic 추상 (GenericTransport, GenericFacility 등) — 영구 도메인 추상.
+ *     GLB 바디를 직접 채우는 방식으로 사용. 변환 대상 아님.
  *
  * 변환 시:
  *   - 좌표/크기/회전 보존
  *   - 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'
+import { find3DPreset, getImportRules } from '../registry/index'
+import type { BoardComponent } from '../pipeline/stage3-board'
+import type { ComponentCategory } from '../types/registry'
+import { GENERIC_OBJECT_TYPE } from '../pipeline/stage2-mapping'
 
 export interface ConvertOptions {
   scopes?: string[]
-  /** 새 컴포넌트의 ID. 미지정 시 ImportRule 의 idStrategy 적용 또는 자동 생성 */
+  /** 새 컴포넌트의 ID. 미지정 시 ImportRule 의 idStrategy 적용 또는 자동 생성. */
   id?: string
+  /**
+   * 코어 placeholder type ('placeholder') 외에 인정할 도메인 추상 type list.
+   * 예: ['GenericTransport', 'GenericFacility'].
+   * 호출자가 자기 도메인 패키지의 추상까지 변환 대상으로 포함하도록 명시.
+   */
+  extraPlaceholderTypes?: ReadonlyArray<string>
+}
+
+/** things-scene 코어가 등록한 도메인 비종속 placeholder type. */
+export const CORE_PLACEHOLDER_TYPES = [GENERIC_OBJECT_TYPE] as const
+
+export function isPlaceholderType(
+  type: string | undefined,
+  extraTypes: ReadonlyArray<string> = []
+): boolean {
+  if (!type) return false
+  if ((CORE_PLACEHOLDER_TYPES as readonly string[]).includes(type)) return true
+  return extraTypes.includes(type)
 }
 
+// ── 일반화된 변환 helper ─────────────────────────────────────────────
+
 /**
- * GenericObject 를 지정된 도메인 type 으로 변환한다.
- * 기존 좌표/크기/회전/source 보존.
+ * 추상 placeholder 를 지정된 도메인 type 으로 변환. 호환되는 모든 generic-* 수용 (코어 + 도메인).
+ *
+ * 기존 좌표/크기/회전/source 보존. placeholder 시각 메타 (placeholderLabel/Hint, fillStyle 등) 는 제거.
  */
-export function convertGenericTo(
-  generic: BoardComponent,
+export function convertPlaceholderTo(
+  placeholder: BoardComponent,
   toType: string,
   options: ConvertOptions = {}
 ): BoardComponent {
-  if (generic.type !== GENERIC_OBJECT_TYPE) {
-    throw new Error(`Source component is not GenericObject (type=${generic.type})`)
+  const extra = options.extraPlaceholderTypes ?? []
+  if (!isPlaceholderType(placeholder.type, extra)) {
+    throw new Error(
+      `Source component is not a generic placeholder (type=${placeholder.type}). ` +
+        `Expected one of: ${[...CORE_PLACEHOLDER_TYPES, ...extra].join(', ')}`
+    )
   }
 
   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 newId = options.id ?? placeholder.id
 
   const preset = find3DPreset(toType, category, options.scopes)
   const threeD = {
@@ -46,7 +77,16 @@ export function convertGenericTo(
     origin: preset.origin ?? 'bottom'
   }
 
-  const { strokeStyle, strokeDashArray, fillStyle, label, ...preservedState } = generic
+  // placeholder 시각/스타일 메타는 새 type 으로 옮길 때 의미 없음 — 제거.
+  const {
+    strokeStyle: _strokeStyle,
+    strokeDashArray: _strokeDashArray,
+    fillStyle: _fillStyle,
+    label: _label,
+    placeholderLabel: _placeholderLabel,
+    placeholderHint: _placeholderHint,
+    ...preservedState
+  } = placeholder as any
 
   return {
     ...preservedState,
@@ -54,45 +94,22 @@ export function convertGenericTo(
     type: toType,
     id: newId,
     threeD,
-    ...(rule?.build.defaultState || {}),
-    /**
-     * 변환 추적 — 되돌리기 가능하게 source 보존.
-     * `convertedFrom` 키는 board-modeller UI 에서 "되돌리기" 액션 활성화 단서.
-     */
-    convertedFrom: {
-      type: GENERIC_OBJECT_TYPE,
-      previousState: { strokeStyle, strokeDashArray, fillStyle, label }
-    }
+    ...(rule?.build.defaultState || {})
   }
 }
 
+// ── Backward-compat alias — 기존 호출처 호환 ──────────────────────
+
 /**
- * 변환된 컴포넌트를 다시 GenericObject 로 되돌린다.
- * convertedFrom 정보가 있어야 가능.
+ * @deprecated Use `convertPlaceholderTo`. Placeholder 한정 — 새 코드는 일반화된 helper.
  */
-export function revertToGeneric(
-  component: BoardComponent,
+export function convertGenericTo(
+  generic: BoardComponent,
+  toType: string,
   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
+  if (generic.type !== GENERIC_OBJECT_TYPE) {
+    throw new Error(`Source component is not Placeholder (type=${generic.type})`)
   }
+  return convertPlaceholderTo(generic, toType, options)
 }

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

@@ -0,0 +1,185 @@
+/**
+ * import-actions — 단위 테스트.
+ *
+ * ResolverContext 무관 service 함수의 동작 검증. mock SessionRepoLike 로 격리.
+ * 비동기 worker (runImportJob) 는 setImmediate side-effect 로 분리되어 있어
+ * 본 테스트 범위 밖 — startImportJobAsync 는 session 저장 후 즉시 return 만 검증.
+ */
+import {
+  startImportJobAsync,
+  fetchImportSession,
+  listImportSessionsByChatSession,
+  describeAdapter,
+  type ImportActionsContext,
+  type SessionRepoLike
+} from './import-actions'
+
+const DOMAIN = { id: 'domain-1', name: 'test' }
+const USER = { id: 'user-1' }
+const CTX: ImportActionsContext = { domain: DOMAIN, user: USER }
+
+function makeRepo(overrides: Partial<SessionRepoLike> = {}) {
+  const findOneByCalls: any[] = []
+  const saveCalls: any[] = []
+  const findCalls: any[] = []
+  const repo: any = {
+    findOneByCalls,
+    saveCalls,
+    findCalls,
+    findOneBy: async (criteria: any) => {
+      findOneByCalls.push(criteria)
+      return null
+    },
+    save: async (entity: any) => {
+      saveCalls.push(entity)
+      return { ...entity, id: 'session-' + (saveCalls.length) }
+    },
+    find: async (options: any) => {
+      findCalls.push(options)
+      return []
+    },
+    ...overrides
+  }
+  return repo
+}
+
+// ── startImportJobAsync ────────────────────────────────────────────
+
+describe('startImportJobAsync', () => {
+  test('session 을 status=queued / progress=0 으로 저장', async () => {
+    const repo = makeRepo()
+    await startImportJobAsync({ attachmentId: 'a1' }, CTX, repo, () => {})
+    expect(repo.saveCalls).toHaveLength(1)
+    expect(repo.saveCalls[0]).toMatchObject({
+      domain: DOMAIN,
+      attachmentId: 'a1',
+      status: 'queued',
+      progress: 0,
+      message: 'Queued',
+      creator: USER
+    })
+  })
+
+  test('options 가 optionsJson 으로 직렬화', async () => {
+    const repo = makeRepo()
+    await startImportJobAsync(
+      {
+        attachmentId: 'a1',
+        scopes: ['fmsim'],
+        normalizeOrigin: true,
+        flipY: false,
+        scale: 2,
+        applyBinding: false,
+        parseOptions: { excludeLayers: ['ANNO'] }
+      },
+      CTX,
+      repo,
+      () => {}
+    )
+    const json = JSON.parse(repo.saveCalls[0].optionsJson)
+    expect(json).toEqual({
+      scopes: ['fmsim'],
+      normalizeOrigin: true,
+      flipY: false,
+      scale: 2,
+      applyBinding: false,
+      parseOptions: { excludeLayers: ['ANNO'] }
+    })
+  })
+
+  test('chatSessionId 가 옵션이라 미지정 시 undefined 로 저장', async () => {
+    const repo = makeRepo()
+    await startImportJobAsync({ attachmentId: 'a1' }, CTX, repo, () => {})
+    expect(repo.saveCalls[0].chatSessionId).toBeUndefined()
+  })
+})
+
+// ── fetchImportSession ────────────────────────────────────────────
+
+describe('fetchImportSession', () => {
+  test('domain id 기반 격리 조회', async () => {
+    const repo = makeRepo()
+    await fetchImportSession('s1', CTX, repo)
+    expect(repo.findOneByCalls[0]).toEqual({
+      id: 's1',
+      domain: { id: DOMAIN.id }
+    })
+  })
+
+  test('미존재 시 null', async () => {
+    const repo = makeRepo()
+    const r = await fetchImportSession('s1', CTX, repo)
+    expect(r).toBeNull()
+  })
+
+  test('존재 시 session 그대로 반환', async () => {
+    const session = { id: 's1', status: 'completed' } as any
+    const repo = makeRepo({ findOneBy: async () => session })
+    const r = await fetchImportSession('s1', CTX, repo)
+    expect(r).toBe(session)
+  })
+})
+
+// ── listImportSessionsByChatSession ────────────────────────────────
+
+describe('listImportSessionsByChatSession', () => {
+  test('chatSessionId + domain 기반, 최신순 50개', async () => {
+    const repo = makeRepo()
+    await listImportSessionsByChatSession('chat-1', CTX, repo)
+    expect(repo.findCalls[0]).toEqual({
+      where: { chatSessionId: 'chat-1', domain: { id: DOMAIN.id } },
+      order: { createdAt: 'DESC' },
+      take: 50
+    })
+  })
+})
+
+// ── describeAdapter ───────────────────────────────────────────────
+
+describe('describeAdapter', () => {
+  test('FormatAdapter 의 능력을 직렬화 가능 평면 객체로', () => {
+    const adapter = {
+      format: 'dxf',
+      supportedExtensions: ['.dxf'],
+      capabilities: {
+        has2D: true,
+        has3D: false,
+        hasSemanticLabels: false,
+        hasTextLabels: true,
+        hasAttributes: true
+      }
+    }
+    expect(describeAdapter(adapter)).toEqual({
+      format: 'dxf',
+      supportedExtensions: ['.dxf'],
+      capabilities: {
+        has2D: true,
+        has3D: false,
+        hasSemanticLabels: false,
+        hasTextLabels: true,
+        hasAttributes: true
+      }
+    })
+  })
+
+  test('falsy capability 도 false 로 정규화', () => {
+    const adapter = {
+      format: 'image',
+      supportedExtensions: ['.png'],
+      capabilities: {
+        has2D: 1, // truthy non-bool
+        has3D: undefined,
+        hasSemanticLabels: 'yes',
+        hasTextLabels: 0,
+        hasAttributes: null
+      }
+    }
+    expect(describeAdapter(adapter as any).capabilities).toEqual({
+      has2D: true,
+      has3D: false,
+      hasSemanticLabels: true,
+      hasTextLabels: false,
+      hasAttributes: false
+    })
+  })
+})

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

@@ -0,0 +1,164 @@
+/**
+ * board-import 의 ResolverContext 무관 service-level 함수.
+ *
+ * import-session-resolver 의 mutation/query 핵심 로직을 typeorm getRepository /
+ * ResolverContext 외부 의존성을 인자로 분리해 단위 테스트 + LLM tool builder 에서
+ * 재사용 가능하도록 추출. materializeFromSession 의 패턴 동일.
+ *
+ * 호출자 책임:
+ *   - resolver: getRepository / context.state 에서 도메인/유저 추출 후 deps 채워 호출
+ *   - import-tools.ts: ToolDispatchHelpers 가 builder 호출 시 ctx 에서 추출
+ */
+
+// type-only import — module level 에서 typeorm decorator chain 을 평가하지 않는다.
+// 단위 테스트 환경이 typeorm DataSource init 전에도 service 함수 검증할 수 있게 함.
+import type { ImportSession } from './import-session'
+
+// ── 입력/의존성 타입 ──────────────────────────────────────────────────
+
+export interface SessionRepoLike {
+  findOneBy(criteria: any): Promise<ImportSession | null>
+  save(entity: any): Promise<ImportSession>
+  find(options: any): Promise<ImportSession[]>
+}
+
+export interface ImportActionsContext {
+  domain: { id: string; [k: string]: any }
+  user: any
+}
+
+export interface StartImportJobInput {
+  attachmentId: string
+  chatSessionId?: string
+  scopes?: string[]
+  normalizeOrigin?: boolean
+  flipY?: boolean
+  scale?: number
+  applyBinding?: boolean
+  parseOptions?: any
+  /**
+   * 사용자 자유서술 — 도면 설명 / 강조 부분 / 분류 힌트 등.
+   * VLM 이 view type 분류 + entity 추출 양쪽 패스에 모두 추가 컨텍스트로 사용.
+   */
+  userPrompt?: string
+}
+
+// ── service 함수들 ────────────────────────────────────────────────────
+
+/**
+ * 비동기 import job 시작. ImportSession 즉시 반환, 백그라운드에서 worker 실행.
+ *
+ * resolver 와 LLM tool builder 양쪽이 공유하는 진입점. side-effect 인 worker 가동도
+ * 본 함수에 묶음 — 사용자 입장에선 "단일 호출 = import 시작" 의미.
+ *
+ * `startWorker` 는 의존성 주입 — default 는 setImmediate(runImportJob). 단위 테스트는
+ * noop 주입해 worker chain 이 jest 환경에서 평가되지 않도록 한다 (typeorm DataSource init
+ * 안 된 환경에서 entity decorator 평가 시 fail 회피).
+ */
+export async function startImportJobAsync(
+  input: StartImportJobInput,
+  context: ImportActionsContext,
+  sessionRepo: SessionRepoLike,
+  startWorker: (sessionId: string) => void = defaultStartWorker
+): Promise<ImportSession> {
+  const session = await sessionRepo.save({
+    domain: context.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,
+      userPrompt: input.userPrompt
+    }),
+    creator: context.user
+  } as any)
+
+  // 백그라운드 worker 시작 — 의존성 주입으로 분리 (테스트 격리 + lazy require).
+  startWorker(session.id!)
+  return session
+}
+
+/**
+ * Default startWorker — setImmediate(runImportJob). worker module 은 lazy require 로
+ * module-level 평가 chain (attachment-base STORAGE, pipeline 의 adapters 등) 을 회피.
+ */
+function defaultStartWorker(sessionId: string): void {
+  setImmediate(() => {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { runImportJob } = require('./import-worker')
+    runImportJob(sessionId).catch((err: Error) => {
+      console.error('[board-import] runImportJob unhandled:', err)
+    })
+  })
+}
+
+/**
+ * 단일 ImportSession 조회 (도메인 격리). 미존재면 null.
+ */
+export async function fetchImportSession(
+  sessionId: string,
+  context: ImportActionsContext,
+  sessionRepo: SessionRepoLike
+): Promise<ImportSession | null> {
+  return await sessionRepo.findOneBy({
+    id: sessionId,
+    domain: { id: context.domain.id }
+  })
+}
+
+/**
+ * 한 ChatSession 안에서 발동된 ImportSession 목록 (최신순 50개). board-ai 의 chat 흐름이
+ * "이 chat 의 import 들 보여줘" 같은 호출에서 사용.
+ */
+export async function listImportSessionsByChatSession(
+  chatSessionId: string,
+  context: ImportActionsContext,
+  sessionRepo: SessionRepoLike
+): Promise<ImportSession[]> {
+  return await sessionRepo.find({
+    where: { chatSessionId, domain: { id: context.domain.id } },
+    order: { createdAt: 'DESC' },
+    take: 50
+  })
+}
+
+/**
+ * 등록된 FormatAdapter 들의 능력 정보. context 무관 (인스턴스만 inspect).
+ * 외부 RPC 의존성도 없어 LLM 이 안전하게 호출 가능한 read tool.
+ */
+export interface AdapterInfo {
+  format: string
+  supportedExtensions: string[]
+  capabilities: {
+    has2D: boolean
+    has3D: boolean
+    hasSemanticLabels: boolean
+    hasTextLabels: boolean
+    hasAttributes: boolean
+  }
+}
+
+export function describeAdapter(adapter: {
+  format: string
+  supportedExtensions: string[]
+  capabilities: any
+}): AdapterInfo {
+  return {
+    format: adapter.format,
+    supportedExtensions: [...adapter.supportedExtensions],
+    capabilities: {
+      has2D: !!adapter.capabilities.has2D,
+      has3D: !!adapter.capabilities.has3D,
+      hasSemanticLabels: !!adapter.capabilities.hasSemanticLabels,
+      hasTextLabels: !!adapter.capabilities.hasTextLabels,
+      hasAttributes: !!adapter.capabilities.hasAttributes
+    }
+  }
+}