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

package/server/service/types.ts

@@ -0,0 +1,235 @@
+/**
+ * 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[]
+  /**
+   * popup 에서 사용자가 명시 선택한 #mention 매핑 — {token, refid}.
+   * server 가 mention 해석 시 이 매핑을 우선 사용. 본문엔 #token 만 남고
+   * refid 는 사용자에게 노출되지 않음 (LLM mention map 에만 첨부).
+   */
+  mentionPicks?: Array<{ token: string; refid: number }>
+  /** LLM 모델 override */
+  model?: string
+  /** LLM 옵션 */
+  temperature?: number
+  maxTokens?: number
+  /**
+   * Tool 카테고리 (read/external) builder 가 사용할 컨텍스트.
+   *
+   * board-ai 자체는 ResolverContext / typeorm 을 직접 알지 않지만, 외부 도메인 패키지가
+   * 등록한 tool (예: board-import 의 importBoardAsync) 은 server-side 의존성 (도메인,
+   * 사용자, 트랜잭션) 이 필요할 수 있다. board-ai-resolver 가 ResolverContext.state 등을
+   * 이 필드로 전달하면, dispatch 시 closure 로 builder 의 ctx.state 에 주입.
+   *
+   * 미지정이면 외부 builder 는 ctx.state === undefined — 빈 응답이나 에러를 반환할 책임.
+   */
+  toolCallContext?: any
+}
+
+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
+  /**
+   * Scene 조작 action (ephemeral — 모델 변경 없음 / undo 영향 없음).
+   * 시간순 시퀀스로 호스트가 things-scene API 직접 실행.
+   */
+  actions?: BoardActionOp[]
+  /** 모호한 입력 시 명확화 질문 (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 단일 채널로 일원화.
+ *
+ * 계층 — 보드는 **최상위 부모** (things-scene 의 model-layer) 이고 그 자체로 자기
+ * 속성을 갖는다 (fillStyle, width, height, fitMode, translate, scale, sky, skyColor,
+ * exposure, hemi/dirLight 계열, camera 계열). 자식 컴포넌트와 별개. 보드 속성 변경은
+ * `modifyBoard`, 자식 변경은 `modify` (refid 기반).
+ *
+ * 주의 — `name` 은 보드 *엔티티* (DB row) 의 컬럼이지 scene MODEL 의 필드가 아니다.
+ * things-scene 의 model-layer 가 인식 안 함. modifyBoard 로 name 을 보내면 model
+ * JSON 에 죽은 필드로 박힐 뿐 렌더링/동작에 영향 없음. 보드 라벨 변경은 GraphQL
+ * boardPatch (BoardPatch input 의 name 필드) 영역.
+ *
+ * style 변경 / 이동 / 크기 변경 등 자식 컴포넌트의 변경은 모두 `modify.patch` 안에
+ * 흡수. 보드 root 속성 변경은 `modifyBoard.patch` 로.
+ */
+/**
+ * Phase 2 — Scene 조작 op 들. 모델 차원 (좌표 / 부모-자식 관계 / z-order) 변경이지만
+ * things-scene 의 자체 API (align/distribute/group/ungroup/zorder) 가 일관된 결과를
+ * 보장하므로 호스트가 직접 호출. 모델 차원 시뮬레이션 (apply-patch) 은 단순화 —
+ * scene 호출 결과가 정본.
+ */
+export type AlignDirection =
+  | 'left'
+  | 'right'
+  | 'center'
+  | 'top'
+  | 'middle'
+  | 'bottom'
+
+export type DistributeAxis = 'horizontal' | 'vertical'
+
+export type ZorderDirection = 'front' | 'back' | 'forward' | 'backward'
+
+/**
+ * Sugar layout — `arrange` op 의 layout 종류.
+ *
+ * 의도: align/distribute 위에 얹는 high-level 의도 표현. AI 가 "3x2 그리드로",
+ * "한 줄로", "세로로 일렬" 같은 자연어를 픽셀 노가다 없이 단일 op 로 표현.
+ *
+ * left/top 만 변경 — width/height 는 유지. AI 가 사이즈도 바꾸려면 별도 modify.
+ *
+ * 위치 계산은 호스트 (things-scene 측) 가 담당 — 각 컴포넌트의 현재 width/height 를
+ * 정확히 알아야 하므로 model 차원 시뮬레이션은 SCENE_ONLY (apply-patch noop).
+ */
+export type ArrangeLayout =
+  | { type: 'grid'; cols: number; gap?: number; anchor?: { left: number; top: number } }
+  | {
+      type: 'row'
+      gap?: number
+      anchor?: { left: number; top: number }
+      align?: 'start' | 'center' | 'end'
+    }
+  | {
+      type: 'column'
+      gap?: number
+      anchor?: { left: number; top: number }
+      align?: 'start' | 'center' | 'end'
+    }
+
+/**
+ * C-1 — Scene 조작 action 들 (ephemeral). 모델 변경 X, 따라서 BoardEditOp 와 별개
+ * 채널 (board-action-execute 이벤트). undo 히스토리 미영향, dirty flag 미영향.
+ *
+ * 종류:
+ *   - selectComponents: scene.selected 직접 set (사용자 선택 변경)
+ *   - centerToComponent: 특정 컴포넌트로 view 이동
+ *   - fitToView: 보드 전체가 보이도록 fit
+ *   - setSceneMode: edit / view 모드 전환
+ */
+export type BoardActionOp =
+  | { action: 'selectComponents'; refids: number[] }
+  | { action: 'centerToComponent'; refid: number; animated?: boolean }
+  | { action: 'fitToView'; mode?: 'fit' | 'ratio' | 'width' | 'height' }
+  | { action: 'setSceneMode'; mode: 'edit' | 'view' }
+  /** 다중 컴포넌트 outline highlight — search/finder UX 의 "이게 모두 매칭이다" 시각화.
+   *  things-scene 의 highlightSearchResults API 위임 (2D/3D 모두 지원). */
+  | { action: 'highlightComponents'; refids: number[] }
+
+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 }
+  | { op: 'align'; refids: number[]; direction: AlignDirection }
+  | { op: 'distribute'; refids: number[]; axis: DistributeAxis }
+  | { op: 'group'; refids: number[] }
+  | { op: 'ungroup'; refid: number }
+  | { op: 'zorder'; refid: number; direction: ZorderDirection }
+  | { op: 'arrange'; refids: number[]; layout: ArrangeLayout }
+
+/**
+ * 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>
+}