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

package/server/service/ai/types.ts

@@ -16,9 +16,13 @@
  *
  * 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'
+import {
+  getDefaultAIClient,
+  parseJSONResponse,
+  type AIClient as BaseAIClient
+} from '@things-factory/ai-client-base'
+import type { ComponentCategory, ImportRule } from '../types/registry'
+import type { UniversalEntity } from '../types/index'
 
 export interface BoardImportAI {
   /** 식별자 — 보통 base.id 와 동일 (provider:model) */
@@ -45,12 +49,19 @@ export interface BoardImportAI {
 
   /**
    * 도면 이미지(PNG/JPG/PDF 페이지) 에서 객체를 검출하여 UniversalEntity 로 변환.
+   *
+   * 1-pass structured response 를 권장 — view type 자동 분류 + entity 추출을 단일 vision
+   * 호출로 처리해 토큰 비용을 절반으로 줄인다. 응답 형태:
+   *   - **`ImageAnalysis`** 객체: `{ viewType, confidence, entities, reasoning? }`
+   *   - 또는 **`UniversalEntity[]`** 직접 (구버전 호환).
+   * ImageAdapter 는 양쪽을 모두 정규화 처리.
+   *
    * Phase 3 (이미지 어댑터) 에서 사용.
    */
   parseFromImage?(
     image: Buffer | Uint8Array,
     options?: ImageParseOptions
-  ): Promise<UniversalEntity[]>
+  ): Promise<ImageAnalysis | UniversalEntity[]>
 
   /**
    * 자연어 매핑 정의 ("STK는 stocker, BUF는 buffer") → ImportRule[] 로 변환.
@@ -103,12 +114,105 @@ export interface ImageParseOptions {
   /** 자연어 컨텍스트. 예: "factory floor plan with AGV paths" */
   context?: string
   categories?: ComponentCategory[]
+  /**
+   * 사용자 자유서술 hint — 도면 설명 / 강조 / 카테고리 가이드 등.
+   * 1-pass VLM 프롬프트에 합류해 view type 분류 + entity 추출 양쪽에 영향.
+   */
+  userPrompt?: string
+  /** 이미지 dimension — 픽셀 좌표계 명시용 (top-down 모드에서). */
+  imageWidth?: number
+  imageHeight?: number
+  /**
+   * View type 강제. 미지정 시 VLM 이 자동 분류.
+   * - 'top-down': 픽셀 좌표 그대로
+   * - 'perspective-3d' / 'photo': floor plan 좌표 추정 (0..1000 단위)
+   */
+  viewType?: 'top-down' | 'perspective-3d' | 'photo'
+}
+
+/**
+ * 1-pass VLM 응답의 구조화된 결과 — **다중 시안 (variants)** 포함.
+ *
+ * 같은 도면을 AI 가 3 가지 다른 관점으로 해석. 사용자가 review 에서 선택.
+ *
+ * 시안 축 (프롬프트가 제시) 예시:
+ *   - 장비(equipment) 중심 / 운송(transport) 중심 / 영역(region) 중심
+ *   - 보수적(conservative) / 균형(balanced) / 공격적(aggressive)
+ *
+ * 각 시안은 독립적인 entities + subjectName/subjectDescription + importStrategy.
+ * viewType / confidence / reasoning 은 시안 무관 공통 (도면 자체의 특성).
+ */
+export interface ImageAnalysis {
+  /** 자동 분류된 view type — 시안 무관 공통. */
+  viewType: 'top-down' | 'perspective-3d' | 'photo'
+  /** 분류 신뢰도 (0..1). LLM 자기보고. */
+  confidence: number
+  /** 분류 근거 한 줄 (왜 이 viewType 인가). */
+  reasoning?: string
+  /** 시안 풀세트. 보통 3 개 — variants[0] 가 default. */
+  variants: ImageAnalysisVariant[]
+}
+
+/**
+ * 한 시안의 풀데이터 — entities + 정체성 + 의도.
+ * 각 시안은 같은 도면이지만 다른 해석.
+ */
+export interface ImageAnalysisVariant {
+  /** URL 친화적 short id. */
+  id: string
+  /** 사용자에게 보여줄 한글 라벨. 예: "장비 중심" */
+  label: string
+  /** 짧은 한 줄 설명 — 이 시안의 강조점. */
+  description?: string
+  /** 추출된 entity 목록. 좌표 의미는 ImageAnalysis.viewType 에 따름. */
+  entities: UniversalEntity[]
+  /**
+   * 보드 정체성 — 도면이 무엇을 나타내는가의 짧은 제목 (≤30자). 보드 name 자동 추천 기반.
+   * 처리 과정이 아니라 **컨텐츠 정체성** 만.
+   */
+  subjectName?: string
+  /**
+   * 보드 정체성 — 도면이 나타내는 시설/배치/구성 1-2 문장. 보드 description 자동 추천 기반.
+   * 처리 과정 X (importStrategy 와 분리).
+   */
+  subjectDescription?: string
+  /**
+   * AI 의 의도 narrative — "왜 이 시안에서 이렇게 해석했나". 3-5 문장.
+   * **transient — wizard review 카드 전시용. 영속 description 에는 사용 X.**
+   */
+  importStrategy?: string
 }
 
 // ── 기본 구현 — base AIClient 위에 LLM 프롬프트로 ────────────────────
 
+interface SingleVariantResult {
+  viewType: 'top-down' | 'perspective-3d' | 'photo'
+  confidence: number
+  reasoning?: string
+  variant: ImageAnalysisVariant
+}
+
 export class DefaultBoardImportAI implements BoardImportAI {
   readonly id: string
+
+  private static readonly VARIANT_AXES = [
+    {
+      id: 'equipment-focus',
+      label: '장비 중심',
+      instruction: '장비/설비(machine/stocker/facility) 식별 우선. 이동체/경로는 보조.'
+    },
+    {
+      id: 'transport-focus',
+      label: '운송 중심',
+      instruction: '차량/경로(AGV/forklift/conveyor) 식별 우선. 정적 장비는 영역으로 묶음.'
+    },
+    {
+      id: 'region-focus',
+      label: '구역 중심',
+      instruction: '영역/구획(zone/wall/structure) 식별 우선. 개별 장비는 generic placeholder.'
+    }
+  ] as const
+
   constructor(private base: BaseAIClient) {
     this.id = base.id
   }
@@ -192,26 +296,115 @@ ${JSON.stringify(targets, null, 2)}`
   async parseFromImage(
     image: Buffer | Uint8Array,
     options: ImageParseOptions = {}
-  ): Promise<UniversalEntity[]> {
+  ): Promise<ImageAnalysis> {
     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(', ') : ''
+
+    const results = await Promise.allSettled(
+      DefaultBoardImportAI.VARIANT_AXES.map(axis => this._callOneVariant(image, axis, options))
+    )
+
+    const succeeded = results
+      .filter((r): r is PromiseFulfilledResult<SingleVariantResult> => r.status === 'fulfilled')
+      .map(r => r.value)
+
+    if (succeeded.length === 0) {
+      const errors = (results as PromiseRejectedResult[]).map(r => r.reason?.message ?? String(r.reason))
+      throw new Error(`All variant calls failed: ${errors.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 forcedVT = options.viewType
+    const viewType = forcedVT ?? consensusViewType(succeeded.map(r => r.viewType))
+    const confidence = succeeded.reduce((s, r) => s + r.confidence, 0) / succeeded.length
+    const reasoning = succeeded.find(r => r.reasoning)?.reasoning
 
-    const text = await this.base.vision(image as Buffer, prompt)
-    return parseJSONResponse<UniversalEntity[]>(text)
+    return { viewType, confidence, reasoning, variants: succeeded.map(r => r.variant) }
+  }
+
+  private async _callOneVariant(
+    image: Buffer | Uint8Array,
+    axis: { id: string; label: string; instruction: string },
+    options: ImageParseOptions
+  ): Promise<SingleVariantResult> {
+    const w = options.imageWidth
+    const h = options.imageHeight
+    const userHint = options.userPrompt?.trim()
+    const forcedViewType = options.viewType
+
+    const dimsLine =
+      Number.isFinite(w) && Number.isFinite(h)
+        ? `\nImage dimensions: ${w} x ${h} pixels.`
+        : ''
+
+    const viewTypeInstruction = forcedViewType
+      ? `\nThe view type is GIVEN: "${forcedViewType}". Do not classify; use it as-is.`
+      : `\nFirst, classify the view type:
+  - "top-down": orthographic floor plan / 2D engineering drawing seen from directly above
+  - "perspective-3d": 3D rendering / isometric / bird's-eye view with visible depth
+  - "photo": photograph of a physical space`
+
+    const coordRule = `\nCoordinate convention by viewType:
+  - "top-down": INTEGER PIXEL coordinates (origin top-left, x →, y ↓)${
+    Number.isFinite(w) && Number.isFinite(h) ? ` in [0, ${w}] x [0, ${h}]` : ''
+  }. Each entity ≥ 16x16 pixels.
+  - "perspective-3d" / "photo": INFER the FLOOR PLAN layout (where each object would be on a flat floor seen from above, NOT screen positions). Use arbitrary plan units in [0, 1000] x [0, 1000]. Object size in plan units (e.g. 50x80 for a stocker).
+NEVER use normalized 0..1 coordinates.`
+
+    const prompt = `Analyze this drawing image and provide ONE interpretation with focus axis: "${axis.id}".
+Focus: ${axis.instruction}${
+      userHint ? '\n\nUser hints (highest priority): ' + userHint : ''
+    }${options.context ? '\nContext: ' + options.context : ''}${
+      options.categories ? '\nPossible categories: ' + options.categories.join(', ') : ''
+    }${dimsLine}${viewTypeInstruction}${coordRule}
+
+Return STRICT JSON (no markdown, no commentary) with this shape:
+{
+  "viewType": "top-down" | "perspective-3d" | "photo",
+  "confidence": 0..1,
+  "reasoning": "brief one-sentence explanation of view type classification",
+  "variant": {
+    "id": "${axis.id}",
+    "label": "한글 라벨 (예: ${axis.label})",
+    "description": "한 줄 — 이 시안의 강조점",
+    "subjectName": "≤30 char short title — what the depicted facility is",
+    "subjectDescription": "1-2 sentences in Korean — what is depicted (NOT how you analyzed)",
+    "importStrategy": "3-5 sentence narrative explaining YOUR INTENT for this variant",
+    "entities": [
+      {
+        "uid": "string",
+        "kind": "shape" | "path" | "text",
+        "position": { "x": number, "y": number },
+        "size": { "width": number, "height": number },
+        "bbox": { "min": {"x": number, "y": number}, "max": {"x": number, "y": number} },
+        "attribs": {
+          "name": "string?",
+          "semanticType": "string?",
+          "text": "string?",
+          "layer": "string?",
+          "categoryHint": "container | vehicle | path | region | equipment | io | marker | structure"
+        }
+      }
+    ]
+  }
+}
+
+categoryHint should be one of the listed categories; omit only if highly uncertain.
+Provide 10-30 distinct entities clearly identifiable under the "${axis.id}" axis.
+
+attribs.name — IMPORTANT for component identity / data binding:
+  - If you see a TEXT LABEL on/near the entity in the drawing (e.g. "STK_001", "AGV-3", "CV1"), use that EXACTLY as the name.
+  - DO NOT invent labels not in the drawing — leave attribs.name empty if uncertain.
+  - Keep alphanumeric + hyphens / underscores. No spaces. ≤24 chars. UNIQUE within the variant.
+
+subjectName + subjectDescription — describe WHAT the board depicts (its identity), NOT what you did.
+  These become the board's persistent name + description if the user picks this variant.
+
+importStrategy — Korean 3-5 sentences: what this variant emphasizes, how you decided categories, areas of uncertainty.
+Used in the wizard review card only; transient — separate from board description.`
+
+    const raw = await this.base.vision!(image as Buffer, prompt, { maxTokens: 4096 })
+    return parseSingleVariantResponse(raw, axis.id, axis.label, forcedViewType)
   }
 
   async parseNaturalLanguageMapping(
@@ -240,6 +433,132 @@ Return JSON array of:
 const SYSTEM_HINT =
   'You are a CAD/IFC drawing analysis assistant. Output strict JSON only — no commentary, no markdown.'
 
+const VIEW_TYPES = ['top-down', 'perspective-3d', 'photo'] as const
+
+function parseSingleVariantResponse(
+  rawText: string,
+  axisId: string,
+  axisLabel: string,
+  forcedViewType?: 'top-down' | 'perspective-3d' | 'photo'
+): SingleVariantResult {
+  const parsed = parseJSONResponse<any>(rawText)
+  const trimmed = (s: any) => (typeof s === 'string' && s.trim() ? s.trim() : undefined)
+
+  const rawVT = parsed?.viewType
+  const viewType: 'top-down' | 'perspective-3d' | 'photo' =
+    forcedViewType ??
+    ((VIEW_TYPES as readonly string[]).includes(rawVT)
+      ? (rawVT as 'top-down' | 'perspective-3d' | 'photo')
+      : 'top-down')
+  const confidence =
+    typeof parsed?.confidence === 'number' && parsed.confidence >= 0 && parsed.confidence <= 1
+      ? parsed.confidence
+      : 0.5
+
+  const v = parsed?.variant ?? {}
+  const variant: ImageAnalysisVariant = {
+    id: typeof v.id === 'string' && v.id ? v.id : axisId,
+    label: typeof v.label === 'string' && v.label ? v.label : axisLabel,
+    description: trimmed(v.description),
+    entities: Array.isArray(v.entities) ? v.entities : [],
+    subjectName: trimmed(v.subjectName),
+    subjectDescription: trimmed(v.subjectDescription),
+    importStrategy: trimmed(v.importStrategy)
+  }
+
+  return { viewType, confidence, reasoning: trimmed(parsed?.reasoning), variant }
+}
+
+function consensusViewType(
+  viewTypes: Array<'top-down' | 'perspective-3d' | 'photo'>
+): 'top-down' | 'perspective-3d' | 'photo' {
+  const counts = new Map<string, number>()
+  for (const vt of viewTypes) counts.set(vt, (counts.get(vt) ?? 0) + 1)
+  let best: 'top-down' | 'perspective-3d' | 'photo' = 'top-down'
+  let max = 0
+  for (const [vt, count] of counts) {
+    if (count > max) {
+      max = count
+      best = vt as 'top-down' | 'perspective-3d' | 'photo'
+    }
+  }
+  return best
+}
+
+/**
+ * VLM 의 JSON 응답을 ImageAnalysis 형태로 정규화 — 다중 시안 (variants) 지원.
+ *
+ * 허용 입력 형태:
+ *  - `{ viewType, confidence, reasoning?, variants: [...] }` — **최신 권장** (multi-variant)
+ *  - `{ viewType, ..., entities }` — 구버전 single-variant (자동으로 variants:[default] 으로 감쌈)
+ *  - `[ entity, ... ]` — 가장 구버전 (entities 만)
+ *
+ * 결손 / 비정상 viewType 은 'top-down' fallback. forcedViewType 이 주어지면 그 값 강제.
+ */
+export function normalizeImageAnalysisResponse(
+  rawText: string,
+  forcedViewType?: 'top-down' | 'perspective-3d' | 'photo'
+): ImageAnalysis {
+  const parsed = parseJSONResponse<any>(rawText)
+  const trimmed = (s: any) => (typeof s === 'string' && s.trim() ? s.trim() : undefined)
+
+  if (Array.isArray(parsed)) {
+    return {
+      viewType: forcedViewType ?? 'top-down',
+      confidence: 0.5,
+      variants: [{ id: 'default', label: 'default', entities: parsed }]
+    }
+  }
+  if (!parsed || typeof parsed !== 'object') {
+    return {
+      viewType: forcedViewType ?? 'top-down',
+      confidence: 0,
+      variants: [{ id: 'default', label: 'default', entities: [] }]
+    }
+  }
+  const rawVT = parsed.viewType
+  const viewType =
+    forcedViewType ??
+    ((VIEW_TYPES as readonly string[]).includes(rawVT) ? rawVT : 'top-down')
+  const confidence =
+    typeof parsed.confidence === 'number' && parsed.confidence >= 0 && parsed.confidence <= 1
+      ? parsed.confidence
+      : 0.5
+
+  // variants 배열 정규화 — 최신 권장 형태
+  let variants: ImageAnalysisVariant[]
+  if (Array.isArray(parsed.variants) && parsed.variants.length > 0) {
+    variants = parsed.variants.map((v: any, i: number) => ({
+      id: typeof v?.id === 'string' && v.id ? v.id : `variant-${i + 1}`,
+      label: typeof v?.label === 'string' && v.label ? v.label : `Variant ${i + 1}`,
+      description: trimmed(v?.description),
+      entities: Array.isArray(v?.entities) ? v.entities : [],
+      subjectName: trimmed(v?.subjectName),
+      subjectDescription: trimmed(v?.subjectDescription),
+      importStrategy: trimmed(v?.importStrategy)
+    }))
+  } else {
+    // 구버전 호환 — top-level entities + subjectName 등을 단일 variant 로 감쌈
+    variants = [
+      {
+        id: 'default',
+        label: 'default',
+        entities: Array.isArray(parsed.entities) ? parsed.entities : [],
+        subjectName: trimmed(parsed.subjectName),
+        subjectDescription: trimmed(parsed.subjectDescription),
+        importStrategy: trimmed(parsed.importStrategy)
+      }
+    ]
+  }
+
+  return {
+    viewType,
+    confidence,
+    reasoning: trimmed(parsed.reasoning),
+    variants
+  }
+}
+
 /**
  * LLM 응답의 regex pattern 문자열 → 실제 RegExp.
  * 보통 "^STK_" 같은 source string 으로 응답.
@@ -271,13 +590,29 @@ function hydrateRuleRegexes<T extends { match?: any }>(rule: T): T {
 // ── Provider 등록 ──────────────────────────────────────────────────
 
 let currentClient: BoardImportAI | undefined
+let defaultBackedClient: BoardImportAI | undefined
+let defaultBackedFor: BaseAIClient | undefined
 
 export function setAIClient(client: BoardImportAI | undefined): void {
   currentClient = client
 }
 
+/**
+ * 등록된 BoardImportAI 가 있으면 그걸 반환.
+ * 없으면 ai-client-base 의 default AIClient (config.aiClient) 를 `DefaultBoardImportAI` 로
+ * 감싸서 반환 — board-ai 와 동일한 1회 설정만으로 image import 도 동작하게 한다.
+ *
+ * default base 가 바뀌면 (테스트 등) 캐시를 무효화하고 다시 감싼다.
+ */
 export function getAIClient(): BoardImportAI | undefined {
-  return currentClient
+  if (currentClient) return currentClient
+  const base = getDefaultAIClient()
+  if (!base) return undefined
+  if (defaultBackedFor !== base) {
+    defaultBackedFor = base
+    defaultBackedClient = new DefaultBoardImportAI(base)
+  }
+  return defaultBackedClient
 }
 
 /** Deprecated alias — 기존 코드 호환용. 새로 작성 시 BoardImportAI 사용. */

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

@@ -0,0 +1,91 @@
+/**
+ * convertPlaceholderTo / attachGlbToPlaceholder — 단위 테스트.
+ *
+ * 코어 placeholder type (placeholder) + 도메인 추상 (GenericTransport 등 호출자 명시)
+ * 모두 변환 가능한지 검증. 좌표/크기/source 보존, GLB attach morph 정책 회귀 방지.
+ */
+import {
+  convertPlaceholderTo,
+  isPlaceholderType,
+  CORE_PLACEHOLDER_TYPES
+} from './generic-to'
+
+// 호출자가 도메인 추상까지 인정하는 경우의 fixtures.
+const EXTRA = ['GenericTransport', 'GenericFacility'] as const
+
+describe('isPlaceholderType', () => {
+  test('코어 type 들은 인정', () => {
+    for (const t of CORE_PLACEHOLDER_TYPES) {
+      expect(isPlaceholderType(t)).toBe(true)
+    }
+  })
+
+  test('extra list 의 도메인 추상도 인정', () => {
+    expect(isPlaceholderType('GenericTransport', EXTRA)).toBe(true)
+    expect(isPlaceholderType('GenericFacility', EXTRA)).toBe(true)
+  })
+
+  test('미등록 type 은 거부', () => {
+    expect(isPlaceholderType('Stocker')).toBe(false)
+    expect(isPlaceholderType(undefined)).toBe(false)
+  })
+
+  test('extra 미지정 시 도메인 추상 거부', () => {
+    expect(isPlaceholderType('GenericTransport')).toBe(false)
+  })
+})
+
+describe('convertPlaceholderTo', () => {
+  const base = {
+    type: 'placeholder',
+    id: 'src-1',
+    left: 100,
+    top: 200,
+    width: 80,
+    height: 60,
+    rotation: 0.5,
+    fillStyle: 'rgba(180,180,180,0.18)',
+    placeholderLabel: 'maybe stocker',
+    placeholderHint: 'STK_001'
+  }
+
+  test('placeholder 가 아닌 type 은 throw', () => {
+    expect(() =>
+      convertPlaceholderTo({ ...base, type: 'rect' } as any, 'Stocker')
+    ).toThrow(/not a generic placeholder/)
+  })
+
+  test('좌표/크기/회전/id 보존', () => {
+    const r = convertPlaceholderTo(base as any, 'Stocker') as any
+    expect(r.left).toBe(100)
+    expect(r.top).toBe(200)
+    expect(r.width).toBe(80)
+    expect(r.height).toBe(60)
+    expect(r.rotation).toBe(0.5)
+    expect(r.id).toBe('src-1')
+  })
+
+  test('새 type 으로 변환 + category=unknown (rule 미등록)', () => {
+    const r = convertPlaceholderTo(base as any, 'Stocker') as any
+    expect(r.type).toBe('Stocker')
+    expect(r.category).toBe('unknown')
+  })
+
+  test('placeholder 시각 메타 (fillStyle / placeholderLabel) 는 제거', () => {
+    const r = convertPlaceholderTo(base as any, 'Stocker') as any
+    expect(r.fillStyle).toBeUndefined()
+    expect(r.placeholderLabel).toBeUndefined()
+    expect(r.placeholderHint).toBeUndefined()
+    expect(r.convertedFrom).toBeUndefined()
+  })
+
+  test('도메인 추상 (extraPlaceholderTypes 명시) 도 변환 가능', () => {
+    const transport = { ...base, type: 'GenericTransport', id: 'tx-1' }
+    const r = convertPlaceholderTo(transport as any, 'Forklift', {
+      extraPlaceholderTypes: ['GenericTransport']
+    }) as any
+    expect(r.type).toBe('Forklift')
+    expect(r.convertedFrom).toBeUndefined()
+  })
+})
+