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

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/types.ts

@@ -0,0 +1,138 @@
+/**
+ * Board AI — 자연어 채팅 인터페이스 타입 정의.
+ *
+ * 핵심 개념:
+ *   - 단일 진입점 `chat()`. 의도 분류(생성/편집/스타일/질문)는 AI 의 일.
+ *   - 출력은 항상 `ChatResponse`. 보드 변경이 있으면 `patch` 동봉.
+ *   - patch 의 op 는 직교 4 종 (add / remove / modify / replace).
+ *     style/move 등은 modify.patch 안에 흡수.
+ */
+import type { BoardComponent, BoardModel } from '@things-factory/board-import'
+
+export interface LLMMessage {
+  role: 'user' | 'assistant'
+  content: string
+}
+
+export interface ChatOptions {
+  /** board-import 의 registry scope — 등록된 ImportRule 에서 type/category 후보 추출 */
+  scopes?: string[]
+  /** 사용 가능한 도메인 type (override). 미지정 시 scopes 에서 자동 추출 */
+  knownTypes?: string[]
+  /** 사용 가능한 카테고리 (override). 미지정 시 scopes 에서 자동 추출 */
+  categories?: string[]
+  /**
+   * 컴포넌트 type 별 유효 속성 스킴.
+   * LLM 이 정확한 컴포넌트 생성을 하도록 type 의 description, group, default model 키 전달.
+   *
+   * 예:
+   *   [{ type: 'rect', description: 'Rectangle', group: 'shape',
+   *      properties: { fillStyle: '#fff', strokeStyle: '#000' } }, ...]
+   */
+  componentSchemas?: ComponentSchema[]
+  /**
+   * 사용자가 모델러에서 현재 선택한 컴포넌트의 `refid` 목록.
+   *
+   * refid 는 things-scene 이 모든 컴포넌트에 자동 발급하는 universal numeric handle.
+   * id (데이터 바인딩 이름, unique 아님) 와는 다른 개념 — 선택은 항상 refid 로 표현.
+   */
+  selectedRefids?: number[]
+  /** LLM 모델 override */
+  model?: string
+  /** LLM 옵션 */
+  temperature?: number
+  maxTokens?: number
+}
+
+export interface ComponentSchema {
+  type: string
+  description?: string
+  group?: string
+  /**
+   * 좌표/크기/경로 관련 키들 — type 마다 다름.
+   * 예) ['left', 'top', 'width', 'height']  vs  ['cx', 'cy', 'radius']  vs  ['points']
+   * LLM 이 type 별 정확한 좌표 키를 사용하도록 명시.
+   */
+  geometryKeys?: string[]
+  /**
+   * 좌표 외 type 특화 속성 (style, value, min/max 등).
+   * default 값 또는 keys 만 — LLM 의 token 절감을 위해 호출자가 적절히 압축.
+   */
+  properties?: Record<string, any>
+}
+
+/**
+ * AI 가 응답을 만드는 동안 호출한 도구의 시간순 trace.
+ *
+ * UX 목적 — 사용자가 "왜 이렇게 답했지" 의문 가질 때 fold-able 박스에서 확인.
+ * 디버그용 + 신뢰도 향상.
+ */
+export interface ToolUsage {
+  /** 도구 이름 (예: 'getSelection', 'modifyBoard', 'addComponent') */
+  name: string
+  /** 호출 인자 JSON */
+  arguments: any
+  /** 도구 결과 — read tool 은 실제 값 (truncated 가능), write tool 은 queued 마커 */
+  result: any
+  /** read tool / write tool 분류 */
+  kind: 'read' | 'write' | 'unknown'
+}
+
+export interface ChatResponse {
+  /** 사용자에게 보여줄 텍스트 응답 */
+  reply: string
+  /** 보드 변경이 있으면 patch */
+  patch?: BoardEditPatch
+  /** 모호한 입력 시 명확화 질문 (patch 없음) */
+  followUp?: string
+  /** AI 가 응답 만드는 과정에서 호출한 도구들 (시간순). UI fold-able 박스용. */
+  toolUsages?: ToolUsage[]
+}
+
+export interface BoardEditPatch {
+  ops: BoardEditOp[]
+  /** 사용자 검수용 1-2 문장 요약 */
+  summary: string
+  /** 0..1 신뢰도 */
+  confidence: number
+}
+
+/**
+ * 보드 변경 op.
+ *
+ * 식별자 정책 — 기존 컴포넌트 타깃팅은 `refid` (number) 만 사용.
+ * things-scene 의 모든 컴포넌트는 `refid` 를 자동 발급받는다 (universal).
+ * `model.id` 는 optional metadata 일 뿐 — 항상 존재하지 않으므로 targeting 에는
+ * 부적합. 별개 개념이므로 BoardEditOp / tool 인자에서도 별개 식별자로 분리하지
+ * 않고 refid 단일 채널로 일원화.
+ *
+ * 계층 — 보드는 **최상위 부모** 이고 그 자체로 자기 속성 (fillStyle, width, height,
+ * name 등) 을 갖는다. 자식 컴포넌트와 별개. 보드 속성 변경은 `modifyBoard`,
+ * 자식 변경은 `modify` (refid 기반).
+ *
+ * style 변경 / 이동 / 크기 변경 등 자식 컴포넌트의 변경은 모두 `modify.patch` 안에
+ * 흡수. 보드 root 속성 변경은 `modifyBoard.patch` 로.
+ */
+export type BoardEditOp =
+  | { op: 'add'; component: BoardComponent }
+  | { op: 'remove'; refid: number }
+  | { op: 'modify'; refid: number; patch: Partial<BoardComponent> }
+  | { op: 'modifyBoard'; patch: Partial<BoardModel> }
+  | { op: 'replace'; board: BoardModel }
+
+/**
+ * BoardAIAssistant — 자연어 채팅으로 보드를 다루는 단일 인터페이스.
+ *
+ * 사용:
+ *   const ai = new DefaultBoardAIAssistant(baseClient, { scopes: ['fmsim'] })
+ *   const r = await ai.chat([{ role: 'user', content: 'AGV 3대 추가' }], currentBoard)
+ *   if (r.patch) currentBoard = applyBoardEditPatch(currentBoard, r.patch)
+ */
+export interface BoardAIAssistant {
+  readonly id: string
+  chat(
+    messages: LLMMessage[],
+    currentBoard: BoardModel | undefined,
+    options?: ChatOptions
+  ): Promise<ChatResponse>
+}

package/things-factory.config.js

@@ -0,0 +1 @@
+export default {}

package/translations/en.json

@@ -0,0 +1,39 @@
+{
+  "board-ai.label.ai": "operato",
+  "board-ai.label.create": "Create",
+  "board-ai.label.edit": "Edit",
+  "board-ai.label.style": "Style",
+  "board-ai.label.korean-supported": "Korean / English",
+  "board-ai.label.multi-command": "Batch commands",
+  "board-ai.label.review-able": "Reviewable",
+
+  "board-ai.text.empty-title": "Design a board together with AI",
+  "board-ai.text.empty-subtitle": "Describe in natural language and AI will create, edit, and style the board. Click an example below to begin.",
+  "board-ai.text.empty-footer-notice": "AI responses are previewed on the board and can be reverted before final apply.",
+  "board-ai.text.input-placeholder": "Describe what you want (Shift+Enter newline, Enter to send)",
+  "board-ai.text.send-tooltip": "Send (Enter)",
+  "board-ai.text.clear-chat-tooltip": "Clear chat (server history kept)",
+  "board-ai.text.show-examples-tooltip": "Show common command examples",
+  "board-ai.text.applied-changes": "Applied.",
+  "board-ai.text.reverted": "Reverted",
+  "board-ai.text.failed-to-load-history": "Failed to load history",
+  "board-ai.text.empty-response": "Empty response.",
+
+  "board-ai.example.create-monitoring-dashboard": "Monitoring dashboard with 3 gauges (utilization, temperature, pressure) and a 24-hour line chart",
+  "board-ai.example.create-welcome-screen": "Welcome screen with a large 'OPERATO' title, a clock, and a subtitle",
+  "board-ai.example.edit-align-distribute": "Center-align the selected components and distribute evenly",
+  "board-ai.example.edit-resize-board": "Resize the board to 1920x1080 and center the components",
+  "board-ai.example.style-dark-mode": "Dark mode — deep navy background, white text, teal accents",
+  "board-ai.example.style-rounded-shadow": "Round all shape corners and add a soft card shadow",
+
+  "board-ai.button.new-conversation": "New chat",
+  "board-ai.button.examples": "Examples",
+  "board-ai.button.close": "Close",
+  "board-ai.button.revert": "Revert",
+  "board-ai.button.retry": "Retry",
+  "board-ai.button.copy": "Copy",
+  "board-ai.button.regenerate": "Regenerate",
+  "board-ai.button.edit": "Edit",
+
+  "board-ai.text.copied": "Copied"
+}

package/translations/ja.json

@@ -0,0 +1,39 @@
+{
+  "board-ai.label.ai": "operato",
+  "board-ai.label.create": "作成",
+  "board-ai.label.edit": "編集",
+  "board-ai.label.style": "スタイル",
+  "board-ai.label.korean-supported": "多言語対応",
+  "board-ai.label.multi-command": "複数命令",
+  "board-ai.label.review-able": "レビュー可能",
+
+  "board-ai.text.empty-title": "AI と一緒にボードを作成しましょう",
+  "board-ai.text.empty-subtitle": "自然言語で指示すると AI がボードを作成・編集・スタイリングします。下の例をクリックして始めてください。",
+  "board-ai.text.empty-footer-notice": "AI の応答は適用前にプレビューで確認でき、元に戻すこともできます。",
+  "board-ai.text.input-placeholder": "自然言語で指示してください (Shift+Enter で改行、Enter で送信)",
+  "board-ai.text.send-tooltip": "送信 (Enter)",
+  "board-ai.text.clear-chat-tooltip": "会話をクリア (サーバー履歴は保持)",
+  "board-ai.text.show-examples-tooltip": "よく使う指示の例を表示",
+  "board-ai.text.applied-changes": "変更しました。",
+  "board-ai.text.reverted": "戻しました",
+  "board-ai.text.failed-to-load-history": "履歴の読み込みに失敗",
+  "board-ai.text.empty-response": "応答が空です。",
+
+  "board-ai.example.create-monitoring-dashboard": "稼働率・温度・圧力の 3 ゲージと 24 時間のラインチャートで監視ダッシュボード",
+  "board-ai.example.create-welcome-screen": "大きな「OPERATO」タイトルと時計、サブタイトルでウェルカム画面",
+  "board-ai.example.edit-align-distribute": "選択したコンポーネントを中央揃えし均等配置",
+  "board-ai.example.edit-resize-board": "ボードを 1920x1080 にしてコンポーネントを中央寄せ",
+  "board-ai.example.style-dark-mode": "ダークモード — 濃紺の背景、白文字、ティール アクセント",
+  "board-ai.example.style-rounded-shadow": "すべての図形を角丸にしてカード風の柔らかい影を追加",
+
+  "board-ai.button.new-conversation": "新しい会話",
+  "board-ai.button.examples": "例",
+  "board-ai.button.close": "閉じる",
+  "board-ai.button.revert": "元に戻す",
+  "board-ai.button.retry": "再試行",
+  "board-ai.button.copy": "コピー",
+  "board-ai.button.regenerate": "再生成",
+  "board-ai.button.edit": "編集",
+
+  "board-ai.text.copied": "コピーしました"
+}

package/translations/ko.json

@@ -0,0 +1,40 @@
+{
+  "board-ai.label.ai": "operato",
+  "board-ai.label.create": "생성",
+  "board-ai.label.edit": "편집",
+  "board-ai.label.style": "스타일",
+  "board-ai.label.korean-supported": "한국어 자유",
+  "board-ai.label.multi-command": "다중 명령",
+  "board-ai.label.review-able": "검수 가능",
+
+  "board-ai.text.empty-title": "AI 와 함께 보드를 만들어보세요",
+  "board-ai.text.empty-subtitle": "자연어로 명령하시면 AI 가 보드를 생성·편집·스타일링합니다. 아래 예시를 클릭해 시작해보세요.",
+  "board-ai.text.empty-footer-notice": "AI 응답은 항상 보드에 적용 전 미리보기로 확인 가능합니다.",
+  "board-ai.text.input-placeholder": "자연어로 명령하세요 (Shift+Enter 줄바꿈, Enter 전송)",
+  "board-ai.text.send-tooltip": "전송 (Enter)",
+  "board-ai.text.clear-chat-tooltip": "대화 초기화 (서버 이력은 유지)",
+  "board-ai.text.show-examples-tooltip": "자주 쓰는 명령 예시 보기",
+  "board-ai.text.applied-changes": "변경했습니다.",
+  "board-ai.text.reverted": "되돌려짐",
+  "board-ai.text.failed-to-load-history": "이력 로드 실패",
+  "board-ai.text.empty-response": "응답이 비어있습니다.",
+  "board-ai.text.tools-used": "도구 사용",
+
+  "board-ai.example.create-monitoring-dashboard": "가동률·온도·압력 3개 게이지와 24시간 라인 차트로 모니터링 대시보드",
+  "board-ai.example.create-welcome-screen": "큰 'OPERATO' 제목과 시계, 부제로 환영 화면",
+  "board-ai.example.edit-align-distribute": "선택한 컴포넌트들을 가운데 정렬하고 일정 간격으로 분산",
+  "board-ai.example.edit-resize-board": "보드 크기를 1920x1080 으로 변경하고 컴포넌트 중앙 정렬",
+  "board-ai.example.style-dark-mode": "다크 모드 — 짙은 남색 배경, 흰색 텍스트, 청록 강조",
+  "board-ai.example.style-rounded-shadow": "모든 도형 모서리 둥글게 + 카드형 옅은 그림자",
+
+  "board-ai.button.new-conversation": "새 대화",
+  "board-ai.button.examples": "예시",
+  "board-ai.button.close": "닫기",
+  "board-ai.button.revert": "되돌리기",
+  "board-ai.button.retry": "다시 시도",
+  "board-ai.button.copy": "복사",
+  "board-ai.button.regenerate": "재생성",
+  "board-ai.button.edit": "편집",
+
+  "board-ai.text.copied": "복사됨"
+}

package/translations/ms.json

@@ -0,0 +1,39 @@
+{
+  "board-ai.label.ai": "operato",
+  "board-ai.label.create": "Cipta",
+  "board-ai.label.edit": "Edit",
+  "board-ai.label.style": "Gaya",
+  "board-ai.label.korean-supported": "Pelbagai bahasa",
+  "board-ai.label.multi-command": "Arahan kumpulan",
+  "board-ai.label.review-able": "Boleh disemak",
+
+  "board-ai.text.empty-title": "Reka papan bersama AI",
+  "board-ai.text.empty-subtitle": "Terangkan dalam bahasa biasa dan AI akan mencipta, mengedit dan menggayakan papan. Klik contoh di bawah untuk bermula.",
+  "board-ai.text.empty-footer-notice": "Respons AI dipratonton sebelum diterapkan dan boleh dibatalkan.",
+  "board-ai.text.input-placeholder": "Terangkan dalam bahasa biasa (Shift+Enter baris baharu, Enter hantar)",
+  "board-ai.text.send-tooltip": "Hantar (Enter)",
+  "board-ai.text.clear-chat-tooltip": "Kosongkan sembang (sejarah pelayan kekal)",
+  "board-ai.text.show-examples-tooltip": "Tunjuk contoh arahan biasa",
+  "board-ai.text.applied-changes": "Diterapkan.",
+  "board-ai.text.reverted": "Dibatalkan",
+  "board-ai.text.failed-to-load-history": "Gagal memuatkan sejarah",
+  "board-ai.text.empty-response": "Respons kosong.",
+
+  "board-ai.example.create-monitoring-dashboard": "Papan pemantauan dengan 3 tolok (penggunaan, suhu, tekanan) dan carta garis 24 jam",
+  "board-ai.example.create-welcome-screen": "Skrin selamat datang dengan tajuk besar 'OPERATO', jam dan sari kata",
+  "board-ai.example.edit-align-distribute": "Jajarkan komponen terpilih ke tengah dan agih sama rata",
+  "board-ai.example.edit-resize-board": "Ubah saiz papan kepada 1920x1080 dan tengahkan komponen",
+  "board-ai.example.style-dark-mode": "Mod gelap — latar biru tua, teks putih, aksen teal",
+  "board-ai.example.style-rounded-shadow": "Bulatkan sudut semua bentuk + bayang kad lembut",
+
+  "board-ai.button.new-conversation": "Sembang baharu",
+  "board-ai.button.examples": "Contoh",
+  "board-ai.button.close": "Tutup",
+  "board-ai.button.revert": "Batalkan",
+  "board-ai.button.retry": "Cuba lagi",
+  "board-ai.button.copy": "Salin",
+  "board-ai.button.regenerate": "Jana semula",
+  "board-ai.button.edit": "Edit",
+
+  "board-ai.text.copied": "Disalin"
+}

package/translations/zh.json

@@ -0,0 +1,39 @@
+{
+  "board-ai.label.ai": "operato",
+  "board-ai.label.create": "创建",
+  "board-ai.label.edit": "编辑",
+  "board-ai.label.style": "样式",
+  "board-ai.label.korean-supported": "多语言",
+  "board-ai.label.multi-command": "批量命令",
+  "board-ai.label.review-able": "可审核",
+
+  "board-ai.text.empty-title": "与 AI 一起设计看板",
+  "board-ai.text.empty-subtitle": "用自然语言描述,AI 将创建、编辑和样式化看板。点击下方示例开始。",
+  "board-ai.text.empty-footer-notice": "AI 的响应在应用前会先预览,并可以撤销。",
+  "board-ai.text.input-placeholder": "用自然语言描述 (Shift+Enter 换行, Enter 发送)",
+  "board-ai.text.send-tooltip": "发送 (Enter)",
+  "board-ai.text.clear-chat-tooltip": "清除对话 (保留服务器历史)",
+  "board-ai.text.show-examples-tooltip": "显示常用命令示例",
+  "board-ai.text.applied-changes": "已应用。",
+  "board-ai.text.reverted": "已撤销",
+  "board-ai.text.failed-to-load-history": "加载历史失败",
+  "board-ai.text.empty-response": "响应为空。",
+
+  "board-ai.example.create-monitoring-dashboard": "用稼动率、温度、压力 3 个仪表 + 24 小时折线图制作监控看板",
+  "board-ai.example.create-welcome-screen": "用大号 'OPERATO' 标题、时钟、副标题做欢迎画面",
+  "board-ai.example.edit-align-distribute": "将所选组件居中对齐并均匀分布",
+  "board-ai.example.edit-resize-board": "看板调整为 1920x1080 并将组件居中",
+  "board-ai.example.style-dark-mode": "深色模式 — 深蓝背景、白色文字、青色强调",
+  "board-ai.example.style-rounded-shadow": "所有图形圆角 + 柔和卡片阴影",
+
+  "board-ai.button.new-conversation": "新对话",
+  "board-ai.button.examples": "示例",
+  "board-ai.button.close": "关闭",
+  "board-ai.button.revert": "撤销",
+  "board-ai.button.retry": "重试",
+  "board-ai.button.copy": "复制",
+  "board-ai.button.regenerate": "重新生成",
+  "board-ai.button.edit": "编辑",
+
+  "board-ai.text.copied": "已复制"
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../tsconfig-base.json",
+  "compilerOptions": {
+    "outDir": "./dist-server",
+    "baseUrl": "./"
+  },
+  "include": ["./server/**/*"],
+  "exclude": ["**/*.spec.ts", "**/*.test.ts"]
+}