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

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
+    }
+  }
+}

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

@@ -0,0 +1,245 @@
+/**
+ * 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,
+  ID,
+  InputType,
+  ObjectType
+} from 'type-graphql'
+import { GraphQLJSON } from 'graphql-scalars'
+import { Like } from 'typeorm'
+import '@things-factory/auth-base'
+
+import { getRepository } from '@things-factory/shell'
+import { Board, Group } from '@things-factory/board-service'
+import { Attachment } from '@things-factory/attachment-base'
+
+import { ImportSession } from './import-session'
+import { materializeFromSession } from './materialize-from-session'
+import {
+  suggestBoardName,
+  suggestBoardMeta,
+  type SuggestBoardMetaResult,
+  type SuggestBoardRepoLike
+} from './suggest-board-name'
+import {
+  startImportJobAsync,
+  fetchImportSession,
+  listImportSessionsByChatSession
+} from './import-actions'
+
+@InputType()
+class MaterializeImportSessionInput {
+  @Field(() => ID, { description: 'ImportSession id (must be in completed state).' })
+  sessionId!: string
+
+  @Field({ description: 'New Board name.' })
+  name!: string
+
+  @Field({ nullable: true, description: 'Optional Board description.' })
+  description?: string
+
+  @Field(() => ID, { nullable: true, description: 'Optional Group id to attach the Board to.' })
+  groupId?: string
+
+  @Field({ nullable: true, description: "Board type — 'main' | 'sub' | 'popup'. Default 'main'." })
+  type?: 'main' | 'sub' | 'popup'
+
+  @Field({ nullable: true, description: 'Base64 thumbnail. If omitted, board-service default empty thumbnail is used.' })
+  thumbnail?: string
+
+  @Field({
+    nullable: true,
+    description:
+      "ImportSession 의 결과 시안 중 하나의 id. 'as-is' / 'scene' / 'auto-fit'. " +
+      '미지정 시 default variant (보통 \'scene\') 사용.'
+  })
+  variantId?: string
+}
+
+@ObjectType()
+class BoardMetaSuggestion {
+  @Field({ description: 'Suggested short board name (collision-free with current domain).' })
+  name!: string
+
+  @Field({
+    description:
+      'Suggested detailed description — combines user prompt, AI importStrategy narrative, and category distribution stats.'
+  })
+  description!: string
+}
+
+@InputType()
+class SuggestBoardNameInput {
+  @Field(() => ID, {
+    nullable: true,
+    description: 'ImportSession id — 있으면 거기서 userPrompt / VLM reasoning / attachment.name 추출.'
+  })
+  sessionId?: string
+
+  @Field({
+    nullable: true,
+    description: '명시 hint. session 정보보다 우선. 사용자가 직접 적은 메모를 기반으로 추천받고 싶을 때.'
+  })
+  hint?: string
+}
+
+@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
+
+  @Field({
+    nullable: true,
+    description:
+      'User-provided context / hints about the drawing — passed to VLM as additional guidance. ' +
+      'e.g. "fab lithography zone, central rectangles are stockers, thin lines are OHT rails."'
+  })
+  userPrompt?: string
+}
+
+@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 fetchImportSession(id, { domain, user: context.state.user }, getRepository(ImportSession) as any)
+  }
+
+  @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, user } = context.state
+    return await listImportSessionsByChatSession(chatSessionId, { domain, user }, getRepository(ImportSession) as any)
+  }
+
+  @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
+    return await startImportJobAsync(input, { domain, user }, getRepository(ImportSession) as any)
+  }
+
+  @Query(() => String, {
+    description:
+      '@deprecated suggestBoardMeta 사용 권장. 단순 string name 만 반환하는 구버전 query.'
+  })
+  @Directive('@privilege(category: "board-import", privilege: "query")')
+  async suggestBoardName(
+    @Arg('input') input: SuggestBoardNameInput,
+    @Ctx() context: ResolverContext
+  ): Promise<string> {
+    const { domain } = context.state
+    const deps = this._buildSuggestDeps()
+    return await suggestBoardName(input, { domain }, deps)
+  }
+
+  @Query(() => BoardMetaSuggestion, {
+    description:
+      '도메인 안에서 충돌하지 않는 Board name + 상세 description 제안. ' +
+      'name 은 짧고 심플 (30자 이내, 충돌 회피 (n) suffix), description 은 자세히 ' +
+      '(사용자 prompt + AI importStrategy + 카테고리 분포 통계 합성).'
+  })
+  @Directive('@privilege(category: "board-import", privilege: "query")')
+  async suggestBoardMeta(
+    @Arg('input') input: SuggestBoardNameInput,
+    @Ctx() context: ResolverContext
+  ): Promise<SuggestBoardMetaResult> {
+    const { domain } = context.state
+    const deps = this._buildSuggestDeps()
+    return await suggestBoardMeta(input, { domain }, deps)
+  }
+
+  /** 두 query 가 공유하는 deps wiring — typeorm find idiomatic 패턴 (distinctAlias 회귀 회피). */
+  private _buildSuggestDeps() {
+    const sessionRepo = getRepository(ImportSession) as any
+    const attachmentRepo = getRepository(Attachment) as any
+    const boardRepo: SuggestBoardRepoLike = {
+      findExistingNames: async ({ domainId, basePrefix }) => {
+        // 도메인 격리 + 'basePrefix' 로 시작하는 name 후보 한 번에 조회.
+        // 단순 find({ where, select }) — take 없음 → DISTINCT 서브쿼리 미발생.
+        const escaped = basePrefix.replace(/[%_\\]/g, ch => '\\' + ch)
+        const items = await getRepository(Board).find({
+          select: ['name'],
+          where: { domain: { id: domainId }, name: Like(`${escaped}%`) }
+        })
+        return items.map(b => b.name as string)
+      }
+    }
+    return { sessionRepo, attachmentRepo, boardRepo }
+  }
+
+  @Mutation(() => Board, {
+    description:
+      '완료된 ImportSession 의 결과 boardModel 을 새 Board entity 로 영속화한다. ' +
+      '검수 단계 (사용자/AI 가 import 결과를 확인 후 명시적으로 호출) 에서 사용. ' +
+      'Board.state="draft" 로 생성되므로 release mutation 으로 별도 발행 필요.'
+  })
+  @Directive('@privilege(category: "board-import", privilege: "mutation")')
+  async materializeImportSession(
+    @Arg('input') input: MaterializeImportSessionInput,
+    @Ctx() context: ResolverContext
+  ): Promise<Board> {
+    const { domain, user } = context.state
+    const sessionRepo = getRepository(ImportSession)
+    const boardRepo = getRepository(Board)
+    const groupRepo = getRepository(Group)
+
+    const session = await sessionRepo.findOneBy({ id: input.sessionId, domain: { id: domain.id } })
+
+    return (await materializeFromSession(
+      session as any,
+      input,
+      { domain, user },
+      { boardRepo: boardRepo as any, groupRepo: groupRepo as any }
+    )) as Board
+  }
+}

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,132 @@
+/**
+ * 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 { importBoardVariants } from '../pipeline/index'
+import { ImportSession } from './import-session'
+
+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).
+    // file storage 는 sync, db/s3/azure 는 async — await 으로 양쪽 다 흡수.
+    const fileBuffer = (await 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' })
+
+    // userPrompt 는 parseOptions 로 합류 — image-adapter 가 VLM 프롬프트에 사용.
+    // 다른 adapter (DXF) 에는 무해 (몰라도 무시).
+    const mergedParseOptions = {
+      ...(opts.parseOptions || {}),
+      ...(opts.userPrompt ? { userPrompt: opts.userPrompt } : {})
+    }
+    // AI 가 같은 도면을 다른 관점으로 해석한 multi-variant. parse 한 번, 시안별 mapping + assemble.
+    // DXF 등 single-variant adapter 는 1 boardModel 만.
+    const result = await importBoardVariants({
+      file: fileBuffer,
+      filename,
+      scopes: opts.scopes,
+      normalizeOrigin: opts.normalizeOrigin,
+      flipY: opts.flipY,
+      scale: opts.scale,
+      applyBinding: opts.applyBinding,
+      parseOptions: mergedParseOptions
+    })
+
+    await update(repo, sessionId, { status: 'assembling', progress: 80, message: 'Assembling boards' })
+
+    // 시안별 카테고리 분포 — 각 variant 의 entities 가 다르므로.
+    const variantsWithStats = result.variants.map((v, i) => {
+      const dist: Record<string, number> = {}
+      for (const c of v.boardModel.components ?? []) {
+        const k = c.category ?? 'unknown'
+        dist[k] = (dist[k] ?? 0) + 1
+      }
+      return { variant: v, mapping: result.mappings[i], categoryDistribution: dist }
+    })
+
+    // default variantId — 첫 variant.
+    const defaultVariantId = result.variants[0]?.id
+
+    // resultJson 구조:
+    //   - variants: 풀 시안 데이터 (선택용 — boardModel + subject + importStrategy + stats + categoryDist)
+    //   - boardModel: default variant 의 boardModel (back-compat)
+    //   - defaultVariantId: 첫 variant 의 id
+    //   - metadata: viewType / aiClientId / userPrompt 등 시안 무관 공통
+    const defaultVariant = variantsWithStats[0]
+    const resultJson = JSON.stringify({
+      variants: variantsWithStats.map(({ variant, mapping, categoryDistribution }) => ({
+        id: variant.id,
+        label: variant.label,
+        description: variant.description,
+        subjectName: variant.subjectName,
+        subjectDescription: variant.subjectDescription,
+        importStrategy: variant.importStrategy,
+        boardModel: variant.boardModel,
+        stats: mapping.stats,
+        warnings: mapping.warnings,
+        categoryDistribution
+      })),
+      defaultVariantId,
+      boardModel: defaultVariant?.variant.boardModel,
+      stats: defaultVariant?.mapping.stats,
+      warnings: defaultVariant?.mapping.warnings,
+      metadata: result.parse.metadata,
+      categoryDistribution: defaultVariant?.categoryDistribution
+    })
+
+    const totalAcross = result.mappings.reduce((s, m) => s + (m.stats.total ?? 0), 0)
+    await update(repo, sessionId, {
+      status: 'completed',
+      progress: 100,
+      message: `Completed: ${result.variants.length} variants, ${totalAcross} entities total`,
+      totalEntities: defaultVariant?.mapping.stats.total ?? 0,
+      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)
+}