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

package/server/service/apply-patch.ts

@@ -0,0 +1,250 @@
+/**
+ * BoardEditPatch 를 BoardModel 에 적용하는 표준 helper.
+ *
+ * 호출자가 patch 응답을 받아 보드에 반영할 때 사용.
+ * Pure function — 입력을 mutate 하지 않음.
+ */
+import type { BoardComponent, BoardModel } from '@things-factory/board-import'
+import type { BoardEditOp, BoardEditPatch } from './types.js'
+
+const EMPTY_BOARD: BoardModel = {
+  width: 1000,
+  height: 600,
+  components: []
+}
+
+export interface PatchApplyReport {
+  /** 패치 적용 후 보드. 모든 op 가 noop 이어도 입력 그대로 반환. */
+  board: BoardModel
+  /** 실제로 보드를 바꾼 op 들. */
+  applied: BoardEditOp[]
+  /** id 매칭 실패 등으로 noop 이 된 op 들 — 호출자가 사용자에게 알릴 단서. */
+  missed: BoardEditOp[]
+}
+
+export function applyBoardEditPatch(
+  board: BoardModel | undefined,
+  patch: BoardEditPatch
+): BoardModel {
+  return applyBoardEditPatchVerbose(board, patch).board
+}
+
+/**
+ * Verbose 변형 — 각 op 의 적용 여부를 보고.
+ *
+ * `modify` 와 `remove` 는 id 가 보드에 없으면 silent no-op 이 된다 (patch 함수의
+ * 의도적 단순화). LLM 이 잘못된 id 를 만들어 보내면 사용자에게 "수정했습니다"
+ * 라고 답하지만 실제로는 아무 변화도 없는 상황이 발생 — 호스트가 missed 를
+ * 보고 사용자에게 경고할 수 있도록 별도 entry point 제공.
+ */
+export function applyBoardEditPatchVerbose(
+  board: BoardModel | undefined,
+  patch: BoardEditPatch
+): PatchApplyReport {
+  let result: BoardModel = board ?? EMPTY_BOARD
+  const applied: BoardEditOp[] = []
+  const missed: BoardEditOp[] = []
+
+  for (const op of patch.ops) {
+    const next = applyOp(result, op)
+    if (next === result || componentsUnchanged(result, next)) {
+      missed.push(op)
+    } else {
+      applied.push(op)
+      result = next
+    }
+  }
+
+  return { board: result, applied, missed }
+}
+
+function componentsUnchanged(prev: BoardModel, next: BoardModel): boolean {
+  // applyOp 는 항상 새 객체를 만든다 (`{ ...board, components: ... }`). 따라서 reference
+  // 비교가 안 되고 내용 비교가 필요. components 는 map/filter 결과 reference 도 다를 수
+  // 있으므로 length + JSON 깊이 비교.
+  const a = prev.components ?? []
+  const b = next.components ?? []
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false
+  }
+  // root meta (width/height/...) 비교
+  return prev.width === next.width && prev.height === next.height && prev.fillStyle === next.fillStyle
+}
+
+/**
+ * 주어진 board 상태에서 op 의 inverse 를 계산.
+ *
+ * Revert 기능의 코어 — patch 적용 직전 board 와 op 만 알면 그 op 의 역연산을
+ * 만들 수 있으므로, 호스트가 in-place 적용하면서 함께 누적해 두면 나중에
+ * 역순 실행만으로 복원 가능.
+ *
+ * 반환:
+ *   - inverse op 또는 null (unsupported / 데이터 부족)
+ *   - add 의 inverse 는 add 후 발급되는 refid 가 필요해서 모델 단계에서 계산 불가 →
+ *     호스트가 scene.add 직후 refid 를 캡처해 직접 만들 것 (이 함수는 pre-applied
+ *     board 만 보고 만들 수 있는 종류만 처리: remove / modify / modifyBoard / replace)
+ */
+export function computeInverseOp(
+  board: BoardModel | undefined,
+  op: BoardEditOp
+): BoardEditOp | null {
+  if (!board) return null
+  const components = board.components ?? []
+
+  switch (op.op) {
+    case 'add':
+      // add 의 inverse 는 새로 발급될 refid 를 알아야 → 호스트 측에서 처리
+      return null
+
+    case 'remove': {
+      const target = components.find(c => (c as any)?.refid === op.refid)
+      if (!target) return null // 매칭 실패 — silent no-op 이라 inverse 도 없음
+      return { op: 'add', component: JSON.parse(JSON.stringify(target)) }
+    }
+
+    case 'modify': {
+      const target = components.find(c => (c as any)?.refid === op.refid)
+      if (!target) return null
+      // patch 가 건드린 키만 보관. nested 는 통째로.
+      const oldValues: any = {}
+      for (const k of Object.keys(op.patch || {})) {
+        const v = (target as any)[k]
+        oldValues[k] = v === undefined ? null : JSON.parse(JSON.stringify(v))
+      }
+      return { op: 'modify', refid: op.refid, patch: oldValues }
+    }
+
+    case 'modifyBoard': {
+      const oldValues: any = {}
+      const patch = op.patch || {}
+      for (const k of Object.keys(patch)) {
+        if (k === 'components') continue
+        const v = (board as any)[k]
+        oldValues[k] = v === undefined ? null : JSON.parse(JSON.stringify(v))
+      }
+      return { op: 'modifyBoard', patch: oldValues }
+    }
+
+    case 'replace':
+      // 이전 보드 통째로 보관 — replace 의 자연스러운 inverse 는 또 다른 replace
+      return { op: 'replace', board: JSON.parse(JSON.stringify(board)) }
+
+    default:
+      return null
+  }
+}
+
+export function applyOp(board: BoardModel, op: BoardEditOp): BoardModel {
+  const components = board.components ?? []
+  switch (op.op) {
+    case 'replace':
+      return op.board
+
+    case 'add':
+      return { ...board, components: [...components, op.component] }
+
+    case 'remove':
+      return { ...board, components: components.filter(c => (c as any)?.refid !== op.refid) }
+
+    case 'modify':
+      return {
+        ...board,
+        components: components.map(c =>
+          (c as any)?.refid === op.refid ? mergeComponent(c, op.patch) : c
+        )
+      }
+
+    case 'modifyBoard': {
+      // 루트 속성 (fillStyle / width / height / name 등) 만 deep merge.
+      // components 키는 무시 — 자식 변경은 add/remove/modify 별도 op 로.
+      const patch = { ...op.patch } as any
+      delete patch.components
+      return mergeBoardRoot(board, patch)
+    }
+
+    default:
+      return board
+  }
+}
+
+function mergeBoardRoot(board: BoardModel, patch: any): BoardModel {
+  const out: any = { ...board }
+  for (const key of Object.keys(patch)) {
+    const bv = (board as any)[key]
+    const pv = patch[key]
+    if (
+      bv !== null &&
+      pv !== null &&
+      typeof bv === 'object' &&
+      typeof pv === 'object' &&
+      !Array.isArray(bv) &&
+      !Array.isArray(pv)
+    ) {
+      out[key] = deepMergeRoot(bv, pv)
+    } else {
+      out[key] = pv
+    }
+  }
+  return out
+}
+
+function deepMergeRoot(a: any, b: any): any {
+  const out: any = { ...a }
+  for (const key of Object.keys(b)) {
+    const av = a[key]
+    const bv = b[key]
+    if (
+      av !== null &&
+      bv !== null &&
+      typeof av === 'object' &&
+      typeof bv === 'object' &&
+      !Array.isArray(av) &&
+      !Array.isArray(bv)
+    ) {
+      out[key] = deepMergeRoot(av, bv)
+    } else {
+      out[key] = bv
+    }
+  }
+  return out
+}
+
+/**
+ * 컴포넌트에 부분 patch 를 적용.
+ * threeD 등 nested object 는 deep merge — 호출자가 색만 바꾸려고 했을 때 geometry 까지 사라지지 않도록.
+ */
+export function mergeComponent(base: BoardComponent, patch: Partial<BoardComponent>): BoardComponent {
+  const out: any = { ...base }
+  for (const key of Object.keys(patch)) {
+    const baseVal = (base as any)[key]
+    const patchVal = (patch as any)[key]
+    if (
+      isPlainObject(baseVal) &&
+      isPlainObject(patchVal)
+    ) {
+      out[key] = deepMerge(baseVal, patchVal)
+    } else {
+      out[key] = patchVal
+    }
+  }
+  return out as BoardComponent
+}
+
+function deepMerge(a: any, b: any): any {
+  const out: any = { ...a }
+  for (const key of Object.keys(b)) {
+    const av = a[key]
+    const bv = b[key]
+    if (isPlainObject(av) && isPlainObject(bv)) {
+      out[key] = deepMerge(av, bv)
+    } else {
+      out[key] = bv
+    }
+  }
+  return out
+}
+
+function isPlainObject(v: any): boolean {
+  return v !== null && typeof v === 'object' && !Array.isArray(v)
+}