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

package/server/service/patch-entry/patch-entry.ts

@@ -0,0 +1,89 @@
+/**
+ * PatchEntry — 보드의 한 변경 단위 (영구 이력).
+ *
+ * source 별:
+ *   - 'ai': AI 가 chat 응답에서 생성
+ *   - 'user-direct': 사용자가 모델러에서 직접 편집 — 변경 이벤트로 자동 기록
+ *   - 'import': ImportSession 결과 (도면 → 보드)
+ *
+ * AI 컨텍스트 유지의 핵심: 사용자 직접 편집도 PatchEntry 로 기록되어
+ * 다음 chat 호출 시 system 메시지로 자동 합류 → AI 가 모든 변경을 인지.
+ */
+import {
+  Column,
+  CreateDateColumn,
+  Entity,
+  Index,
+  ManyToOne,
+  PrimaryGeneratedColumn,
+  RelationId
+} from 'typeorm'
+import { Field, ID, Float, ObjectType } from 'type-graphql'
+import { GraphQLJSON } from 'graphql-scalars'
+
+import { config } from '@things-factory/env'
+
+import { ChatSession } from '../chat-session/chat-session.js'
+
+const ORMCONFIG = config.get('ormconfig', {})
+const DATABASE_TYPE = ORMCONFIG.type
+
+@Entity()
+@Index('ix_patch_entry_1', (patch: PatchEntry) => [patch.session, patch.createdAt])
+@ObjectType({ description: 'One board edit operation history (cascade-deleted with ChatSession).' })
+export class PatchEntry {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(type => ID, { nullable: true })
+  readonly id?: string
+
+  @ManyToOne(type => ChatSession, session => session.patches, { onDelete: 'CASCADE' })
+  session?: ChatSession
+
+  @RelationId((patch: PatchEntry) => patch.session)
+  sessionId?: string
+
+  /** 'ai' | 'user-direct' | 'import' */
+  @Column({ type: 'varchar', length: 32 })
+  @Field({ description: "'ai' | 'user-direct' | 'import'" })
+  source!: string
+
+  /** BoardEditOp[] JSON-stringified — column 으로는 long text. */
+  @Column({
+    type:
+      DATABASE_TYPE == 'mysql' || DATABASE_TYPE == 'mariadb'
+        ? 'longtext'
+        : DATABASE_TYPE == 'oracle'
+          ? 'clob'
+          : DATABASE_TYPE == 'mssql'
+            ? 'nvarchar'
+            : 'text',
+    length: DATABASE_TYPE == 'mssql' ? 'MAX' : undefined
+  })
+  ops!: string
+
+  /** GraphQL 노출용 — JSON 객체로 변환. */
+  @Field(type => GraphQLJSON, { description: 'BoardEditOp[] (parsed JSON array).' })
+  get opsJson(): any {
+    try {
+      return JSON.parse(this.ops || '[]')
+    } catch {
+      return []
+    }
+  }
+
+  @Column({ type: 'text', nullable: true })
+  @Field({ nullable: true, description: 'Short human summary of this patch.' })
+  summary?: string
+
+  @Column({ type: 'float', nullable: true })
+  @Field(type => Float, { nullable: true, description: 'AI confidence 0..1 (null for user-direct).' })
+  confidence?: number
+
+  @Column({ default: false })
+  @Field({ description: 'Whether this patch was reverted.' })
+  reverted!: boolean
+
+  @CreateDateColumn()
+  @Field({ nullable: true })
+  createdAt?: Date
+}

package/server/service/prefab-registry.test.ts

@@ -0,0 +1,172 @@
+/**
+ * prefab-registry.ts 단위 테스트.
+ *
+ * 핵심 보호:
+ *   - register / find / list 의 기본 CRUD
+ *   - 같은 name 으로 등록 시 덮어쓰기 (호스트 커스터마이징 의도)
+ *   - 검색 (category / keywordPattern) 동작
+ *   - 자체 등록된 default prefab 3종 (monitor-card / gauge-panel / stat-tile) 의 build()
+ *     출력 형태 — group 컴포넌트 + components 자식 리스트
+ */
+import {
+  registerBoardPrefab,
+  findBoardPrefab,
+  listBoardPrefabs,
+  clearBoardPrefabsForTest,
+  type BoardPrefab
+} from './prefab-registry'
+
+describe('registerBoardPrefab — 입력 검증', () => {
+  test('name 누락 시 throw', () => {
+    expect(() => registerBoardPrefab({} as any)).toThrow(/name.*required/)
+  })
+
+  test('build 누락 시 throw', () => {
+    expect(() => registerBoardPrefab({ name: 'x', description: 'd' } as any)).toThrow(
+      /build.*required/
+    )
+  })
+})
+
+describe('default prefabs — 자동 등록', () => {
+  // 모듈 로드만 해도 default 3종 이 등록되어 있어야 함 (register call 이 위 import 로 발동)
+  test('monitor-card / gauge-panel / stat-tile 등록 확인', () => {
+    expect(findBoardPrefab('monitor-card')).toBeDefined()
+    expect(findBoardPrefab('gauge-panel')).toBeDefined()
+    expect(findBoardPrefab('stat-tile')).toBeDefined()
+  })
+
+  test('list 결과에 이름·카테고리·기본 크기 포함', () => {
+    const all = listBoardPrefabs()
+    const monitor = all.find(p => p.name === 'monitor-card')
+    expect(monitor).toBeDefined()
+    expect(monitor!.category).toBe('monitoring')
+    expect(monitor!.defaultSize?.width).toBeGreaterThan(0)
+    expect(monitor!.description).toBeTruthy()
+  })
+
+  test('list 결과에 build 함수 미포함 (직렬화 친화)', () => {
+    const all = listBoardPrefabs()
+    for (const p of all) {
+      expect((p as any).build).toBeUndefined()
+    }
+  })
+})
+
+describe('listBoardPrefabs — 필터', () => {
+  test('category 필터', () => {
+    const monitoring = listBoardPrefabs({ category: 'monitoring' })
+    expect(monitoring.every(p => p.category === 'monitoring')).toBe(true)
+    expect(monitoring.length).toBeGreaterThanOrEqual(1)
+    const kpi = listBoardPrefabs({ category: 'kpi' })
+    expect(kpi.every(p => p.category === 'kpi')).toBe(true)
+  })
+
+  test('keywordPattern — case-insensitive 매칭', () => {
+    const r = listBoardPrefabs({ keywordPattern: 'GAUGE' })
+    expect(r.find(p => p.name === 'gauge-panel')).toBeDefined()
+  })
+
+  test('keywordPattern — 한글 매칭', () => {
+    const r = listBoardPrefabs({ keywordPattern: '게이지' })
+    expect(r.find(p => p.name === 'gauge-panel')).toBeDefined()
+  })
+
+  test('keywordPattern — description 에서 매칭', () => {
+    const r = listBoardPrefabs({ keywordPattern: 'KPI' })
+    expect(r.find(p => p.name === 'stat-tile')).toBeDefined()
+  })
+})
+
+describe('default prefab.build() — 형태 검증', () => {
+  test('monitor-card 의 build — group 컴포넌트 + 4 자식', () => {
+    const prefab = findBoardPrefab('monitor-card')!
+    const c = prefab.build({ left: 50, top: 30, title: '온도', value: '23.5°C' })
+    expect((c as any).type).toBe('group')
+    expect((c as any).left).toBe(50)
+    expect((c as any).top).toBe(30)
+    expect((c as any).components).toHaveLength(4)
+    // 자식 중에 옵션이 반영됐는지 (title / value 텍스트)
+    const texts = (c as any).components
+      .filter((cc: any) => cc.type === 'text')
+      .map((cc: any) => cc.text)
+    expect(texts).toContain('온도')
+    expect(texts).toContain('23.5°C')
+  })
+
+  test('monitor-card defaultSize 적용 (width/height 미지정)', () => {
+    const prefab = findBoardPrefab('monitor-card')!
+    const c = prefab.build({ left: 0, top: 0 })
+    expect((c as any).width).toBe(prefab.defaultSize!.width)
+    expect((c as any).height).toBe(prefab.defaultSize!.height)
+  })
+
+  test('gauge-panel — gauge-circle 자식 포함, value/min/max 전달', () => {
+    const prefab = findBoardPrefab('gauge-panel')!
+    const c = prefab.build({
+      left: 0,
+      top: 0,
+      value: 75,
+      min: 0,
+      max: 100,
+      title: 'CPU'
+    })
+    const gauge = (c as any).components.find((cc: any) => cc.type === 'gauge-circle')
+    expect(gauge).toBeDefined()
+    expect(gauge.value).toBe(75)
+    expect(gauge.max).toBe(100)
+    const labels = (c as any).components
+      .filter((cc: any) => cc.type === 'text')
+      .map((cc: any) => cc.text)
+    expect(labels).toContain('CPU')
+  })
+
+  test('stat-tile — fillStyle 옵션 적용', () => {
+    const prefab = findBoardPrefab('stat-tile')!
+    const c = prefab.build({ left: 0, top: 0, fillStyle: '#ff0000', value: '42' })
+    const bg = (c as any).components.find((cc: any) => cc.type === 'rect')
+    expect(bg.fillStyle).toBe('#ff0000')
+  })
+
+  test('width/height override — defaultSize 무시', () => {
+    const prefab = findBoardPrefab('monitor-card')!
+    const c = prefab.build({ left: 0, top: 0, width: 400, height: 200 })
+    expect((c as any).width).toBe(400)
+    expect((c as any).height).toBe(200)
+    // children 의 좌표 / 크기도 상대적으로 따라가야 함 (배경 rect 가 기둥)
+    const bg = (c as any).components.find((cc: any) => cc.type === 'rect')
+    expect(bg.width).toBe(400)
+    expect(bg.height).toBe(200)
+  })
+})
+
+describe('register — 같은 name 덮어쓰기 (호스트 커스터마이징 시나리오)', () => {
+  // default 등록 상태를 보존하기 위해 새 임시 prefab 으로만 검증.
+  test('동일 name 두 번 register → 두 번째가 활성', () => {
+    const v1: BoardPrefab = {
+      name: 'temp-test',
+      description: 'v1',
+      build: () => ({ type: 'rect' } as any)
+    }
+    const v2: BoardPrefab = {
+      name: 'temp-test',
+      description: 'v2',
+      build: () => ({ type: 'circle' } as any)
+    }
+    registerBoardPrefab(v1)
+    expect(findBoardPrefab('temp-test')!.description).toBe('v1')
+    registerBoardPrefab(v2)
+    expect(findBoardPrefab('temp-test')!.description).toBe('v2')
+    expect((findBoardPrefab('temp-test')!.build({ left: 0, top: 0 }) as any).type).toBe(
+      'circle'
+    )
+  })
+})
+
+// clearBoardPrefabsForTest 자체 동작은 격리된 테스트에서만 — 다른 테스트의 default 사용을
+// 망가뜨리지 않도록 마지막에 두고 직접 호출하지 않음.
+describe('clearBoardPrefabsForTest', () => {
+  test('함수 export 확인 (시그니처)', () => {
+    expect(typeof clearBoardPrefabsForTest).toBe('function')
+  })
+})

package/server/service/prefab-registry.ts

@@ -0,0 +1,332 @@
+/**
+ * Board Prefab Registry — 고품질 복합 컴포넌트 프리셋 카탈로그.
+ *
+ * 의도:
+ *   - 보드 설계자가 실제로 원하는 단위는 rect/circle 같은 원시 도형이 아닌
+ *     "온도 모니터링 카드", "AGV 배터리 상태판", "공정 KPI 타일" 같은 디자인된
+ *     복합 모듈. 이 layer 가 그 단위를 시스템 차원에서 제공.
+ *   - LLM 은 자유 작곡하지 않고 검증된 prefab 카탈로그에서 고름 → 결과 일관성 ↑,
+ *     비용 ↓, 진입 장벽 낮춤.
+ *
+ * 통합:
+ *   - 호스트 (operato 등) 가 패키지 로드 시 `registerBoardPrefab` 으로 자기 prefab
+ *     등록. board-ai 는 registry 만 관리. 초기 예시 prefab 몇 개를 자체 등록 — 진짜
+ *     디자인된 prefab 은 별도 패키지에서 추가.
+ *   - LLM 도구 통합:
+ *       getAvailablePrefabs (read)  → registry 의 메타데이터 반환
+ *       addPrefab (write)           → name + 좌표/옵션 → 단일 BoardComponent (group)
+ *
+ * 식별자:
+ *   - `name` 은 unique. 같은 name 으로 register 시 override (호스트가 자기 prefab 을
+ *     커스터마이징할 수 있도록 의도적 허용).
+ *   - 카테고리는 free-form string — registry 가 강제하지 않음. 사용자/운영 자율.
+ */
+import type { BoardComponent } from '@things-factory/board-import'
+
+export interface BoardPrefab {
+  /** Unique 식별자 — 'kebab-case' 권장 */
+  name: string
+
+  /** 자유 분류 — 'monitoring' | 'control' | 'decoration' | 'kpi' 등 */
+  category?: string
+
+  /** 사용자 / LLM 이 이해할 한 문장 설명 */
+  description: string
+
+  /**
+   * 자연어 매칭 힌트 — '온도', '게이지', '카드' 등.
+   * findComponents 같은 검색이 아니라 LLM 의 의도 매칭용 메타데이터.
+   */
+  keywords?: string[]
+
+  /** 권장 기본 크기 — options 에 width/height 미지정 시 사용 */
+  defaultSize?: { width: number; height: number }
+
+  /**
+   * Prefab 의 컴포넌트 트리를 만든다. 단일 `BoardComponent` 반환 — 보통 group 타입이며
+   * `components` 자식을 가진다. 단일 add op 으로 매핑되어 undo 도 한 단위.
+   *
+   * options:
+   *   - left/top: anchor 좌표 (top-left 원점)
+   *   - width/height: 크기 (없으면 defaultSize)
+   *   - 추가 키: prefab 별 자유 (title 텍스트, 색상 등)
+   */
+  build(options: PrefabBuildOptions): BoardComponent
+}
+
+export interface PrefabBuildOptions {
+  left: number
+  top: number
+  width?: number
+  height?: number
+  /** prefab 별 커스터마이징 — 자유 형태 */
+  [k: string]: any
+}
+
+const REGISTRY = new Map<string, BoardPrefab>()
+
+/**
+ * Prefab 등록. 같은 name 은 덮어씀 (호스트가 자기 prefab 으로 default 를 교체 가능).
+ */
+export function registerBoardPrefab(prefab: BoardPrefab): void {
+  if (!prefab || typeof prefab.name !== 'string' || prefab.name.length === 0) {
+    throw new Error('registerBoardPrefab: prefab.name is required')
+  }
+  if (typeof prefab.build !== 'function') {
+    throw new Error(`registerBoardPrefab(${prefab.name}): build() is required`)
+  }
+  REGISTRY.set(prefab.name, prefab)
+}
+
+/** 이름으로 조회. 없으면 undefined. */
+export function findBoardPrefab(name: string): BoardPrefab | undefined {
+  return REGISTRY.get(name)
+}
+
+/** 등록된 prefab 의 메타데이터 (build 함수 제외) — getAvailablePrefabs 결과용. */
+export function listBoardPrefabs(filter?: {
+  category?: string
+  keywordPattern?: string
+}): Array<Omit<BoardPrefab, 'build'>> {
+  const items: Array<Omit<BoardPrefab, 'build'>> = []
+  for (const p of REGISTRY.values()) {
+    if (filter?.category && p.category !== filter.category) continue
+    if (filter?.keywordPattern) {
+      const needle = filter.keywordPattern.toLowerCase()
+      const haystack = [
+        p.name,
+        p.description,
+        ...(p.keywords ?? [])
+      ]
+        .join(' ')
+        .toLowerCase()
+      if (!haystack.includes(needle)) continue
+    }
+    items.push({
+      name: p.name,
+      category: p.category,
+      description: p.description,
+      keywords: p.keywords,
+      defaultSize: p.defaultSize
+    })
+  }
+  return items
+}
+
+/** 테스트용 — 등록 상태 초기화. */
+export function clearBoardPrefabsForTest(): void {
+  REGISTRY.clear()
+}
+
+// ── 초기 예시 prefab ─────────────────────────────────────────────
+//
+// 패키지 차원 default — 진짜 polished 디자인은 operato / 도메인 패키지에서 register.
+// 여기서는 architecture 데모 + LLM 이 선택할 후보가 0 이 되지 않도록 최소 set.
+
+/**
+ * monitor-card — 라벨 + 큰 숫자값 + 부제 의 모니터링 타일.
+ * 가장 흔한 대시보드 단위. AGV 배터리 / 온도 / 가동률 등 한 줄 KPI 표시.
+ */
+const MONITOR_CARD: BoardPrefab = {
+  name: 'monitor-card',
+  category: 'monitoring',
+  description:
+    'KPI 모니터링 카드 — 상단에 라벨, 중앙에 큰 값, 하단에 부제. 단일 수치 한 줄 표시 (온도/가동률/배터리 등).',
+  keywords: ['모니터링', 'kpi', '카드', '값', 'value', 'card'],
+  defaultSize: { width: 200, height: 120 },
+  build(opts) {
+    const w = opts.width ?? 200
+    const h = opts.height ?? 120
+    const title = typeof opts.title === 'string' ? opts.title : 'Label'
+    const value = typeof opts.value === 'string' ? opts.value : '0'
+    const subtitle = typeof opts.subtitle === 'string' ? opts.subtitle : ''
+    const fill = typeof opts.fillStyle === 'string' ? opts.fillStyle : '#1a2332'
+    const accent = typeof opts.accent === 'string' ? opts.accent : '#4fc3f7'
+
+    return {
+      type: 'group',
+      left: opts.left,
+      top: opts.top,
+      width: w,
+      height: h,
+      name: 'monitor-card',
+      components: [
+        {
+          type: 'rect',
+          left: 0,
+          top: 0,
+          width: w,
+          height: h,
+          fillStyle: fill,
+          strokeStyle: '#2a3a52',
+          strokeWidth: 1
+        },
+        {
+          type: 'text',
+          left: 12,
+          top: 10,
+          width: w - 24,
+          height: 16,
+          text: title,
+          fillStyle: '#94a3b8',
+          fontSize: 12
+        },
+        {
+          type: 'text',
+          left: 12,
+          top: 32,
+          width: w - 24,
+          height: h - 60,
+          text: value,
+          fillStyle: accent,
+          fontSize: 32,
+          fontWeight: 'bold'
+        },
+        {
+          type: 'text',
+          left: 12,
+          top: h - 22,
+          width: w - 24,
+          height: 14,
+          text: subtitle,
+          fillStyle: '#64748b',
+          fontSize: 11
+        }
+      ]
+    } as any as BoardComponent
+  }
+}
+
+/**
+ * gauge-panel — 라벨 붙은 원형 게이지 패널.
+ * gauge-circle 컴포넌트가 things-scene에 있음을 전제. 진짜 게이지가 없으면 폴백으로 circle.
+ */
+const GAUGE_PANEL: BoardPrefab = {
+  name: 'gauge-panel',
+  category: 'monitoring',
+  description:
+    '원형 게이지 + 라벨. 0~100 (또는 min/max) 범위의 단일 값 시각화 (CPU, 압력, 충전 등).',
+  keywords: ['게이지', 'gauge', '원형', '미터', 'meter', '센서'],
+  defaultSize: { width: 180, height: 200 },
+  build(opts) {
+    const w = opts.width ?? 180
+    const h = opts.height ?? 200
+    const title = typeof opts.title === 'string' ? opts.title : 'Gauge'
+    const value = typeof opts.value === 'number' ? opts.value : 50
+    const min = typeof opts.min === 'number' ? opts.min : 0
+    const max = typeof opts.max === 'number' ? opts.max : 100
+    const fill = typeof opts.fillStyle === 'string' ? opts.fillStyle : '#1a2332'
+
+    return {
+      type: 'group',
+      left: opts.left,
+      top: opts.top,
+      width: w,
+      height: h,
+      name: 'gauge-panel',
+      components: [
+        {
+          type: 'rect',
+          left: 0,
+          top: 0,
+          width: w,
+          height: h,
+          fillStyle: fill,
+          strokeStyle: '#2a3a52',
+          strokeWidth: 1
+        },
+        {
+          // gauge-circle 이 등록되어 있을 때 사용. 미등록 환경에서는 정상 추가는 되나
+          // render 가 fallback. operato 패키지에서 normalizeComponent 가 default 채움.
+          type: 'gauge-circle',
+          left: 20,
+          top: 20,
+          width: w - 40,
+          height: w - 40, // 정사각형 게이지
+          value,
+          min,
+          max
+        },
+        {
+          type: 'text',
+          left: 12,
+          top: h - 28,
+          width: w - 24,
+          height: 18,
+          text: title,
+          fillStyle: '#94a3b8',
+          fontSize: 13
+        }
+      ]
+    } as any as BoardComponent
+  }
+}
+
+/**
+ * stat-tile — 컬러 타일 + 큰 숫자. monitor-card 보다 강조된 단일 수치 표시.
+ * 사용자 시선이 가장 먼저 가는 위치에 배치.
+ */
+const STAT_TILE: BoardPrefab = {
+  name: 'stat-tile',
+  category: 'kpi',
+  description:
+    '강조 컬러 타일 + 큰 숫자값 + 작은 라벨. monitor-card 보다 시각적 무게가 강함 — 핵심 KPI 1~3 개에만 사용.',
+  keywords: ['타일', 'tile', 'kpi', '강조', 'highlight'],
+  defaultSize: { width: 220, height: 140 },
+  build(opts) {
+    const w = opts.width ?? 220
+    const h = opts.height ?? 140
+    const title = typeof opts.title === 'string' ? opts.title : 'Total'
+    const value = typeof opts.value === 'string' ? opts.value : '0'
+    const fill = typeof opts.fillStyle === 'string' ? opts.fillStyle : '#0ea5e9'
+    const textColor = typeof opts.textColor === 'string' ? opts.textColor : '#ffffff'
+
+    return {
+      type: 'group',
+      left: opts.left,
+      top: opts.top,
+      width: w,
+      height: h,
+      name: 'stat-tile',
+      components: [
+        {
+          type: 'rect',
+          left: 0,
+          top: 0,
+          width: w,
+          height: h,
+          fillStyle: fill,
+          strokeStyle: 'transparent',
+          strokeWidth: 0
+        },
+        {
+          type: 'text',
+          left: 16,
+          top: 16,
+          width: w - 32,
+          height: 18,
+          text: title,
+          fillStyle: textColor,
+          fontSize: 13,
+          opacity: 0.85
+        },
+        {
+          type: 'text',
+          left: 16,
+          top: 40,
+          width: w - 32,
+          height: h - 56,
+          text: value,
+          fillStyle: textColor,
+          fontSize: 40,
+          fontWeight: 'bold'
+        }
+      ]
+    } as any as BoardComponent
+  }
+}
+
+// 모듈 로드 시 자동 등록 (idempotent — 다시 register 해도 덮어쓰기)
+registerBoardPrefab(MONITOR_CARD)
+registerBoardPrefab(GAUGE_PANEL)
+registerBoardPrefab(STAT_TILE)