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

package/server/service/pipeline/stage3-board.test.ts

@@ -0,0 +1,133 @@
+/**
+ * Stage 3 — assembleBoard 의 컴포넌트 root 외곽 spill 방지 회귀 테스트.
+ *
+ * 검증 포인트:
+ *  - bbox 가 컴포넌트 position+size 보다 작아도 board 가 그것 cover
+ *  - normalizeOrigin + flipY 조합에서 컴포넌트 음수 좌표 회피 (root 위쪽 spill 방지)
+ *  - padding 으로 컴포넌트가 root 가장자리에 붙지 않음
+ *  - 빈 board 는 1000x1000 fallback
+ */
+import { assembleBoard } from './stage3-board'
+import type { ComponentDraft } from '../types/registry'
+import type { BoundingBox, UniversalEntity } from '../types/index'
+
+function entity(uid: string, x: number, y: number, w: number, h: number): UniversalEntity {
+  return {
+    uid,
+    kind: 'shape',
+    position: { x, y },
+    size: { width: w, height: h },
+    bbox: { min: { x, y }, max: { x: x + w, y: y + h } },
+    attribs: {}
+  }
+}
+
+function draft(src: UniversalEntity): ComponentDraft {
+  return {
+    category: 'unknown',
+    type: 'placeholder',
+    id: src.uid,
+    state: {},
+    source: src
+  }
+}
+
+describe('assembleBoard — board 크기 산정', () => {
+  test('컴포넌트 모두 root 안 — left/top 모두 0 이상, right/bottom 모두 board 크기 이하', () => {
+    const drafts = [draft(entity('a', 0, 0, 100, 80)), draft(entity('b', 200, 100, 60, 60))]
+    const bbox: BoundingBox = { min: { x: 0, y: 0 }, max: { x: 260, y: 160 } }
+    const board = assembleBoard(drafts, bbox, { normalizeOrigin: true, flipY: false, scale: 1 })
+
+    for (const c of board.components ?? []) {
+      expect(c.left).toBeGreaterThanOrEqual(0)
+      expect(c.top).toBeGreaterThanOrEqual(0)
+      expect(c.left + c.width).toBeLessThanOrEqual(board.width!)
+      expect(c.top + c.height).toBeLessThanOrEqual(board.height!)
+    }
+  })
+
+  test('bbox 가 컴포넌트 size 보다 작아도 board 가 컴포넌트 fully cover', () => {
+    // 의도적으로 bbox 를 entity 보다 작게 — VLM 이 lossy bbox 줬을 때 시뮬레이션
+    const drafts = [draft(entity('a', 0, 0, 500, 400))]
+    const tightBbox: BoundingBox = { min: { x: 0, y: 0 }, max: { x: 100, y: 100 } }
+    const board = assembleBoard(drafts, tightBbox, {
+      normalizeOrigin: true,
+      flipY: false,
+      scale: 1
+    })
+
+    const c = board.components![0]
+    expect(c.left + c.width).toBeLessThanOrEqual(board.width!)
+    expect(c.top + c.height).toBeLessThanOrEqual(board.height!)
+    // board 는 컴포넌트 (500x400) + padding 2개 = 580 / 480 이상이어야 함
+    expect(board.width!).toBeGreaterThanOrEqual(500)
+    expect(board.height!).toBeGreaterThanOrEqual(400)
+  })
+
+  test('flipY=true 일 때 모든 컴포넌트 top 이 0 이상 (root 위쪽 spill 방지)', () => {
+    const drafts = [
+      draft(entity('a', 0, 0, 100, 100)),
+      draft(entity('b', 50, 50, 100, 100)),
+      draft(entity('c', 100, 200, 100, 100))
+    ]
+    const bbox: BoundingBox = { min: { x: 0, y: 0 }, max: { x: 200, y: 300 } }
+    const board = assembleBoard(drafts, bbox, { normalizeOrigin: true, flipY: true, scale: 1 })
+
+    for (const c of board.components ?? []) {
+      expect(c.top).toBeGreaterThanOrEqual(0)
+      expect(c.top + c.height).toBeLessThanOrEqual(board.height!)
+    }
+  })
+
+  test('빈 drafts → board 1000x1000 fallback', () => {
+    const bbox: BoundingBox = { min: { x: 0, y: 0 }, max: { x: 0, y: 0 } }
+    const board = assembleBoard([], bbox, { normalizeOrigin: true, flipY: true, scale: 1 })
+    // 0 + padding 80 < 1000 fallback
+    expect(board.width).toBe(1000)
+    expect(board.height).toBe(1000)
+    expect(board.components).toEqual([])
+  })
+
+  test('padding 적용 — 컴포넌트 가장자리에 정확히 맞닿지 않고 약간의 여백', () => {
+    const drafts = [draft(entity('a', 0, 0, 100, 80))]
+    const bbox: BoundingBox = { min: { x: 0, y: 0 }, max: { x: 100, y: 80 } }
+    const board = assembleBoard(drafts, bbox, { normalizeOrigin: true, flipY: false, scale: 1 })
+
+    const c = board.components![0]
+    // 가장자리에 정확히 0 이 아니라 padding 만큼 안쪽
+    expect(c.left).toBeGreaterThan(0)
+    expect(c.top).toBeGreaterThan(0)
+    // 우측/하단도 padding 만큼 여유
+    expect(c.left + c.width).toBeLessThan(board.width!)
+    expect(c.top + c.height).toBeLessThan(board.height!)
+  })
+
+  test('normalizeOrigin=true 일 때 음수 entity 좌표도 root 안으로 끌어올림', () => {
+    // entity 가 음수 좌표 (e.g. CAD 의 임의 원점) — bbox 가 정확하면 normalizeOrigin 으로
+    // 0 이상으로 올려야 함.
+    const drafts = [draft(entity('a', -100, -50, 100, 100))]
+    const bbox: BoundingBox = { min: { x: -100, y: -50 }, max: { x: 0, y: 50 } }
+    const board = assembleBoard(drafts, bbox, { normalizeOrigin: true, flipY: false, scale: 1 })
+
+    const c = board.components![0]
+    expect(c.left).toBeGreaterThanOrEqual(0)
+    expect(c.top).toBeGreaterThanOrEqual(0)
+  })
+
+  test('scale 적용 — 모든 좌표/크기가 비율대로', () => {
+    const drafts = [draft(entity('a', 10, 20, 100, 80))]
+    const bbox: BoundingBox = { min: { x: 0, y: 0 }, max: { x: 200, y: 200 } }
+    const board = assembleBoard(drafts, bbox, {
+      normalizeOrigin: true,
+      flipY: false,
+      scale: 0.5
+    })
+
+    const c = board.components![0]
+    // scale=0.5 적용
+    expect(c.width).toBe(50)
+    expect(c.height).toBe(40)
+    // padding 은 scale 무관 (40 unit)
+    expect(c.left).toBe(10 * 0.5 + 40)
+  })
+})

package/server/service/pipeline/stage3-board.ts

@@ -2,9 +2,9 @@
  * Stage 3 — ComponentDraft → Board Model JSON.
  * 좌표/단위 변환 + 3D Preset 적용.
  */
-import { find3DPreset } from '../registry/index.js'
-import type { BoundingBox } from '../types/index.js'
-import type { ComponentCategory, ComponentDraft } from '../types/registry.js'
+import { find3DPreset } from '../registry/index'
+import type { BoundingBox } from '../types/index'
+import type { ComponentCategory, ComponentDraft } from '../types/registry'
 
 export interface BoardModel {
   width?: number
@@ -58,6 +58,18 @@ export interface AssembleOptions {
   importMeta?: BoardModel['importMeta']
 }
 
+/**
+ * 보드 외곽 padding (양쪽). 컴포넌트가 root 가장자리에 정확히 맞닿지 않도록 살짝 여백.
+ * 너무 크면 빈 공간 낭비, 너무 작으면 시각적으로 갑갑함 → 40 unit.
+ */
+const BOARD_PADDING = 40
+
+/**
+ * 빈 보드 / 너무 작은 컨텐츠일 때 fallback 크기.
+ * 최소 1000x1000 — things-scene 의 RootContainer 기본 크기에 맞춤.
+ */
+const MIN_BOARD_SIZE = 1000
+
 export function assembleBoard(
   drafts: ComponentDraft[],
   bbox: BoundingBox,
@@ -67,16 +79,69 @@ export function assembleBoard(
   const offsetX = options.normalizeOrigin ? -bbox.min.x : 0
   const offsetY = options.normalizeOrigin ? -bbox.min.y : 0
 
-  const boardWidth = (bbox.max.x - bbox.min.x) * scale
-  const boardHeight = (bbox.max.y - bbox.min.y) * scale
+  // 1단계: bbox 기반 가설 board 크기. 그러나 entity bbox 와 position+size 가 어긋나는 경우
+  // 컴포넌트가 root 외곽으로 spill 할 수 있어 2단계에서 컴포넌트 실제 edge 로 보정한다.
+  let boardWidth = (bbox.max.x - bbox.min.x) * scale
+  let boardHeight = (bbox.max.y - bbox.min.y) * scale
 
-  const components: BoardComponent[] = drafts.map(d => {
+  // 1.5단계: 컴포넌트 layout 1차 (flipY 미적용 — boardHeight 확정 전이라 미루기).
+  type Layout = {
+    d: ComponentDraft
+    src: ComponentDraft['source']
+    left: number
+    rawTop: number
+    width: number
+    height: number
+  }
+  const layouts: Layout[] = drafts.map(d => {
     const src = d.source
     const left = src ? (src.position.x + offsetX) * scale : 0
     const rawTop = src ? (src.position.y + offsetY) * scale : 0
-    const top = options.flipY ? boardHeight - rawTop - (src?.size?.height ?? 0) * scale : rawTop
     const width = (src?.size?.width ?? 1) * scale
     const height = (src?.size?.height ?? 1) * scale
+    return { d, src, left, rawTop, width, height }
+  })
+
+  // 2단계: 컴포넌트 실제 edge 로 board 크기 보정. bbox 보다 컴포넌트 right/bottom 이
+  // 크면 그것 기준. 모든 컴포넌트 left/top 도 음수 안 되도록 0 이상 보장 (있으면 offset 보정).
+  let computedRight = 0
+  let computedBottom = 0
+  let computedMinLeft = 0
+  let computedMinTop = 0
+  for (const l of layouts) {
+    if (l.left < computedMinLeft) computedMinLeft = l.left
+    if (l.rawTop < computedMinTop) computedMinTop = l.rawTop
+    if (l.left + l.width > computedRight) computedRight = l.left + l.width
+    if (l.rawTop + l.height > computedBottom) computedBottom = l.rawTop + l.height
+  }
+  // 음수 left/top 이 있으면 추가 offset 으로 0 으로 끌어올림.
+  const extraOffsetX = computedMinLeft < 0 ? -computedMinLeft : 0
+  const extraOffsetY = computedMinTop < 0 ? -computedMinTop : 0
+  if (extraOffsetX || extraOffsetY) {
+    for (const l of layouts) {
+      l.left += extraOffsetX
+      l.rawTop += extraOffsetY
+    }
+    computedRight += extraOffsetX
+    computedBottom += extraOffsetY
+  }
+
+  // 최종 board 크기 — bbox 와 컴포넌트 실제 max edge 중 큰 값 + padding.
+  // 컴포넌트 없으면 padding 의미 없고, fallback 으로 MIN_BOARD_SIZE.
+  boardWidth = Math.max(boardWidth, computedRight)
+  boardHeight = Math.max(boardHeight, computedBottom)
+  if (layouts.length > 0) {
+    boardWidth += BOARD_PADDING * 2
+    boardHeight += BOARD_PADDING * 2
+  }
+  boardWidth = Math.max(boardWidth, MIN_BOARD_SIZE)
+  boardHeight = Math.max(boardHeight, MIN_BOARD_SIZE)
+
+  // 3단계: padding 만큼 모든 컴포넌트 안쪽으로 평행이동 + flipY 적용.
+  const components: BoardComponent[] = layouts.map(({ d, src, left, rawTop, width, height }) => {
+    const finalLeft = left + BOARD_PADDING
+    const finalRawTop = rawTop + BOARD_PADDING
+    const finalTop = options.flipY ? boardHeight - finalRawTop - height : finalRawTop
     const rotation = src?.rotation
 
     const preset = find3DPreset(d.type, d.category, options.scopes)
@@ -86,8 +151,8 @@ export function assembleBoard(
       category: d.category,
       type: d.type,
       id: d.id,
-      left,
-      top,
+      left: finalLeft,
+      top: finalTop,
       width,
       height,
       ...(rotation !== undefined && { rotation: options.flipY ? -rotation : rotation }),
@@ -97,8 +162,8 @@ export function assembleBoard(
   })
 
   return {
-    width: boardWidth || 1000,
-    height: boardHeight || 1000,
+    width: boardWidth,
+    height: boardHeight,
     fillStyle: options.backgroundColor ?? '#ffffff',
     components,
     importMeta: options.importMeta

package/server/service/pipeline/stage4-binding.ts

@@ -2,8 +2,8 @@
  * Stage 4 — 보드 모델에 데이터 바인딩 자동 설정.
  * 컴포넌트 type 에 등록된 SubscriptionRule 을 찾아 subscriptionTag 등 부여.
  */
-import { findSubscriptionRule } from '../registry/index.js'
-import type { BoardComponent, BoardModel } from './stage3-board.js'
+import { findSubscriptionRule } from '../registry/index'
+import type { BoardComponent, BoardModel } from './stage3-board'
 
 export interface BindingOptions {
   scopes?: string[]

package/server/service/registry/index.ts

@@ -4,7 +4,7 @@
  *
  * 백엔드 단일 프로세스 안에서 in-memory 로 유지된다. 모듈 부트스트랩 시 등록.
  */
-import type { ComponentCategory, ImportRule, SubscriptionRule, ThreeDPreset } from '../types/registry.js'
+import type { ComponentCategory, ImportRule, SubscriptionRule, ThreeDPreset } from '../types/registry'
 
 /**
  * 코어가 제공하는 카테고리별 기본 3D Preset.

package/server/service/types/index.ts

@@ -63,6 +63,12 @@ export interface EntityAttribs {
   text?: string
   /** 도면 모양 종류 (rect/circle/polyline 등) */
   shape?: 'rect' | 'circle' | 'polyline' | 'polygon'
+  /**
+   * 카테고리 힌트 — AI 분류기 / 매처가 구체 type 까지는 못 정해도 카테고리만 줄 때 사용.
+   * Stage2 매핑이 ImportRule 매치에 실패하면 이 값을 보고 카테고리별 generic-* placeholder
+   * 로 폴백한다 (`MappingOptions.categoryFallback`).
+   */
+  categoryHint?: import('./registry').ComponentCategory
   /** 임의 추가 속성 */
   [k: string]: any
 }
@@ -75,6 +81,10 @@ export interface EntityRelation {
 
 /**
  * Adapter 결과 — 정규화된 entity 목록 + 메타데이터.
+ *
+ * 단일 변형이 default. AI/VLM 어댑터는 추가로 `variants` (다중 시안) 를 줄 수 있음 —
+ * 같은 도면을 다르게 해석한 후보들. 사용자가 review 단계에서 선택. variants[0] 와
+ * 최상위 entities 는 동일 (default 시안).
  */
 export interface ParseResult {
   entities: UniversalEntity[]
@@ -82,6 +92,32 @@ export interface ParseResult {
   bbox: BoundingBox
   /** 도면 단위 (mm/m/inch 등). 명시되지 않으면 'unknown' */
   units?: 'mm' | 'cm' | 'm' | 'inch' | 'unknown'
+  /**
+   * 다중 시안 (AI 가 같은 도면을 다른 관점으로 해석). 미지정 시 단일 변형 (default 만).
+   * 각 시안은 자기 entities + 자기 subjectName/Description + 자기 importStrategy.
+   */
+  variants?: ParseVariant[]
+}
+
+/**
+ * AI 가 제공하는 다중 해석 시안 — 같은 도면, 다른 관점/분류 전략.
+ * 예: "장비 중심" / "운송 중심" / "영역 중심" — 또는 "보수적" / "균형" / "공격적".
+ */
+export interface ParseVariant {
+  /** URL 친화적 short id — materialize 시 사용. */
+  id: string
+  /** 사용자에게 보여줄 한글 라벨. 예: "장비 중심", "운송 중심". */
+  label: string
+  /** 짧은 한 줄 설명 (선택) — 이 시안이 뭘 강조하는가. */
+  description?: string
+  entities: UniversalEntity[]
+  bbox?: BoundingBox
+  /** 도면 정체성 — 짧은 제목 (보드 name 추천 기반). */
+  subjectName?: string
+  /** 도면 정체성 — 1-2 문장 설명 (보드 description 추천 기반). */
+  subjectDescription?: string
+  /** AI 의 의도 narrative — 왜 이 시안을 이렇게 해석했나. review 카드 표시. */
+  importStrategy?: string
 }
 
 export interface AdapterMetadata {