@things-factory/figure-ui 10.1.35 → 10.1.37

package/docs/v3-product-cutover.md

@@ -0,0 +1,35 @@
+# V3 제품 전환 현황
+
+기준일: 2026-09-21. **풀적용·배포 완료 문서가 아니다.** V3 단일 제품 경로가 목표이며 V2 병행 운영이 목표가 아니다.
+
+## 작성한 제품 코드
+
+- `client/modeller/v3-product-session.ts`: 모델 ID·로드·저장 경계를 V3 workspace에 연결한다. 다른 모델의 지연 응답을 버리며 로드 실패 시 이전 형상을 노출하지 않는다. UI/AI는 같은 리비전과 undo/redo를 사용한다. AI 편집은 요청 당시 context/revision을 필수로 받는다.
+- `client/modeller/v3-canvas.ts`: 평가된 V3 형상을 Three.js에 직접 전달한다. 이전 parts/base 형식으로 변환하지 않는다. 새 문맥에서 렌더링이 실패하면 이전 모델을 지운다.
+- `client/modeller/v3-editor.ts`: 빈 모델, 네 도형 추가, 선언된 수치 입력, 재질 토큰 변경, 실행 취소/다시 실행, 저장 연결. 관계·바인딩 편집, 이름 편집, 전체 재질 편집과 직접 조작 도구는 아직 부족하다.
+- `client/graphql/v3-store.ts`: 정본을 변환 없이 `saveFigureV3`로 보낸다.
+- figure-service의 `saveFigureV3`: 도메인 권한 검사, V3 검증, 정확한 이전 정본을 조건으로 하는 atomic UPDATE, 생성 요청 ID를 이용한 재시도. SQLite에서 지원하지 않는 행 잠금은 사용하지 않는다. 기존 V2 성능 점수/삼각형 수는 승계하지 않고 null로 둔다. 실제 운영 DB 저장 테스트는 아직 하지 않았다.
+- `client/pages/figure-v3-modeller-page.ts`: 위 요소를 묶는 페이지를 작성했다. **route.ts는 여전히 기존 페이지를 import한다. 이 새 페이지는 아직 사용자 진입점이 아니다.**
+
+## 데이터 확인
+
+로컬 `operato-application/packages/operato-figure/db.sqlite`를 read-only로 조사했다. 삭제되지 않은 모델 32개 모두 `version: 2`다. 부품 분포는 cube114, cylinder86, polygon4, rect79, sphere5, wall2다. DB와 발행 이력은 변경하지 않았다.
+
+V3의 네 렌더링 공급자만으로 기존 모델 전체가 보존된다고 주장할 수 없다. 구·일반 단면뿐 아니라 관절, 반복, 부품 간 배치 관계, capability, 기본 동작값을 검증해야 한다. 버전 숫자만 변경하거나 형상을 정적 메시로 평탄화하는 것은 전체 전환이 아니다.
+
+## 활성화 전에 끝낼 항목
+
+1. 기존 32개 자산과 발행 이력의 전환 계획·복구본·미지원 항목 보고. 형상 및 움직임을 비교 검증한다.
+2. 새 페이지의 저작 기능 누락을 채우고 실제 브라우저에서 생성·편집·로드·저장·전환을 확인한다.
+3. operato-figure의 AI-dock과 figure-service 도구/제안 생성기를 V3 정본 및 승인된 트랜잭션 계약으로 전환한다. 페이지 이벤트만 추가한 것은 AI 통합 완료가 아니다.
+4. 발행 게이트, 썸네일, 카탈로그/배치 소비처도 V3 평가 결과를 사용하도록 연결한다. V2 평가 함수에 V3 정본을 전달하지 않는다.
+5. 위 작업을 마친 뒤 기본 모델러 route를 새 페이지로 교체하고 이전 구현을 제거한다. 데이터 미전환 상태에서 route만 먼저 바꾸지 않는다.
+
+## 검증
+
+- figure-ui `npm test`: 241개 통과. 신규 세션/저장 검사와 기존 회귀 검사를 합친 수치다.
+- figure-ui client 및 figure-service `tsc --noEmit`: 통과.
+- SQLite in-memory 테스트: 테넌트 경계·이전 정본 비교·오래된 편집 거절. 실제 TypeORM 리졸버/제품 DB end-to-end 검증을 대체하지 않는다.
+- 이번 새 V3 페이지의 실제 브라우저 검증, 기본 route 변경, 패키지 발행·배포는 하지 않았다.
+
+배포는 사용자가 담당한다. 이 문서의 미완료 항목이 남은 채로 제품 전체 V3 전환 완료를 선언하지 않는다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/figure-ui",
-  "version": "10.1.35",
+  "version": "10.1.37",
   "publishConfig": {
     "access": "public",
     "@things-factory:registry": "https://registry.npmjs.org"
@@ -26,7 +26,7 @@
     "clean": "npm run clean:server && npm run clean:client"
   },
   "dependencies": {
-    "@hatiolab/figure-model": "^0.1.32",
+    "@hatiolab/figure-model": "^0.1.35",
     "@hatiolab/things-scene": "^10.1.22",
     "@material/web": "^2.0.0",
     "@operato/data-grist": "^10.0.0",
@@ -37,8 +37,8 @@
     "@operato/shell": "^10.0.0",
     "@operato/styles": "^10.0.0",
     "@operato/utils": "^10.0.0",
-    "@things-factory/figure-service": "^10.1.35",
+    "@things-factory/figure-service": "^10.1.37",
     "three": "^0.185.1"
   },
-  "gitHead": "396f43b648b704f1938a2d890ab2f6efa33fdb86"
+  "gitHead": "d8a69e5c8803a4b9d3289df0cf38e161a207db61"
 }

package/test/v3-product-session.test.ts

@@ -0,0 +1,133 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { createV3Asset, addV3Box, serializeV3Asset } from '@hatiolab/figure-model'
+import { createV3ProductSession, type V3ProductRecord } from '../client/modeller/v3-product-session.js'
+
+const source = (name = 'sample') =>
+  serializeV3Asset(
+    addV3Box(createV3Asset(name), {
+      id: 'body',
+      size: { x: 100, y: 100, z: 100 },
+      position: { x: 0, y: 50, z: 0 }
+    })
+  )
+function deferred<T>() {
+  let resolve!: (value: T) => void, reject!: (error: Error) => void
+  const promise = new Promise<T>((yes, no) => {
+    resolve = yes
+    reject = no
+  })
+  return { promise, resolve, reject }
+}
+const store = {
+  load: async (id: string) => ({ id, source: source(id) }),
+  save: async (q: { id?: string; source: string }) => ({ id: q.id ?? 'created', source: q.source })
+}
+
+test('existing model -> new clears geometry, ID, history and derived state', async () => {
+  const s = createV3ProductSession(store)
+  await s.open('A')
+  assert.equal(s.read().geometry.length, 1)
+  const v = s.startNew()
+  assert.equal(v.id, undefined)
+  assert.equal(v.geometry.length, 0)
+  assert.equal(v.canUndo, false)
+  assert.equal(v.dirty, false)
+  assert.equal(JSON.parse(s.source()).version, 'figure-v3-asset-1')
+})
+test('late load cannot overwrite another model or a new figure', async () => {
+  const pending = deferred<V3ProductRecord>()
+  const s = createV3ProductSession({ ...store, load: id => (id === 'A' ? pending.promise : store.load(id)) })
+  const first = s.open('A')
+  await s.open('B')
+  pending.resolve({ id: 'A', source: source('A') })
+  await first
+  assert.equal(s.read().id, 'B')
+  const p = deferred<V3ProductRecord>(),
+    t = createV3ProductSession({ ...store, load: () => p.promise })
+  const loading = t.open('A')
+  t.startNew()
+  p.resolve({ id: 'A', source: source() })
+  await loading
+  assert.equal(t.read().id, undefined)
+  assert.equal(t.read().geometry.length, 0)
+})
+test('failed load hides previous geometry and cannot save under the failed ID', async () => {
+  const s = createV3ProductSession({ ...store, load: async id => ({ id, source: id === 'bad' ? '{}' : source() }) })
+  await s.open('A')
+  await s.open('bad')
+  assert.equal(s.read().geometry.length, 0)
+  assert.equal(s.read().id, undefined)
+  assert.ok(s.read().error)
+  await assert.rejects(s.save())
+})
+test('UI and AI use a shared revision and history; stale/cross-model AI is rejected', async () => {
+  const s = createV3ProductSession(store)
+  await s.open('A')
+  const before = s.read(),
+    changes = [{ kind: 'set-design' as const, input: 'body.size.y', unit: 'mm' as const, value: 150 }]
+  assert.throws(() => s.apply(changes, 'ai'), /문맥/)
+  s.apply(changes, 'ai', before.revision!, before.context!)
+  assert.throws(() => s.apply(changes, 'ai', before.revision!, before.context!))
+  s.undo()
+  assert.equal(s.read().fields.find(i => i.id === 'body.size.y')?.value, 100)
+  await s.open('B')
+  assert.throws(() => s.apply(changes, 'ai', 0, before.context!))
+})
+test('save carries exact baseline and acknowledges only matching response', async () => {
+  let baseline: string | undefined
+  const s = createV3ProductSession({
+    ...store,
+    save: async q => {
+      baseline = q.expectedSource
+      return store.save(q)
+    }
+  })
+  await s.open('A')
+  const original = s.source()
+  s.apply([{ kind: 'set-design', input: 'body.size.y', unit: 'mm', value: 200 }])
+  await s.save()
+  assert.equal(baseline, original)
+  assert.equal(s.read().dirty, false)
+  s.undo()
+  assert.equal(s.read().dirty, true)
+})
+test('pending save locks edits/navigation and duplicate create', async () => {
+  const p = deferred<V3ProductRecord>(),
+    s = createV3ProductSession({ ...store, save: () => p.promise })
+  s.startNew()
+  const text = s.source(),
+    saving = s.save()
+  assert.throws(() => s.startNew())
+  assert.throws(() => s.undo())
+  await assert.rejects(s.save())
+  p.resolve({ id: 'new', source: text })
+  await saving
+  assert.equal(s.read().id, 'new')
+})
+test('save failure preserves edits and allows retry; wrong acknowledgement never clears dirty', async () => {
+  const s = createV3ProductSession({ ...store, save: async () => ({ id: 'wrong', source: source() }) })
+  await s.open('A')
+  s.apply([{ kind: 'set-design', input: 'body.size.y', unit: 'mm', value: 200 }])
+  await assert.rejects(s.save())
+  assert.equal(s.read().dirty, true)
+  assert.equal(s.read().saving, false)
+  assert.equal(s.read().id, 'A')
+})
+test('retry after a lost create response reuses the same creation identity', async () => {
+  const keys: string[] = []
+  const s = createV3ProductSession({
+    ...store,
+    save: async q => {
+      keys.push(q.creationId!)
+      if (keys.length === 1) throw Error('response lost')
+      return { id: q.creationId!, source: q.source }
+    }
+  })
+  s.startNew()
+  await assert.rejects(s.save())
+  await s.save()
+  assert.equal(keys.length, 2)
+  assert.equal(keys[0], keys[1])
+  assert.ok(keys[0])
+})

package/test/v3-product-write.test.ts

@@ -0,0 +1,48 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { createV3Asset, serializeV3Asset } from '@hatiolab/figure-model'
+import { prepareV3Write, compareAndSwapV3 } from '../../figure-service/server/service/figure/figure-v3-write.js'
+import { DatabaseSync } from 'node:sqlite'
+
+test('V3 saves preserve the graph and clear unmeasured previous scores', () => {
+  const source = serializeV3Asset(createV3Asset('빈 자산'))
+  const saved = prepareV3Write(source)
+  assert.equal(saved.source, source)
+  assert.equal(saved.name, '빈 자산')
+  assert.equal(saved.score, null)
+  assert.equal(saved.triangles, null)
+  assert.equal(saved.groups, 0)
+  assert.equal(saved.state, 'draft')
+})
+test('source concurrency check requires exact baseline; no implicit overwrite', () => {
+  const source = serializeV3Asset(createV3Asset('A'))
+  assert.throws(() => prepareV3Write(source, { source }))
+  assert.throws(() => prepareV3Write(source, { source }, 'changed'))
+  assert.equal(prepareV3Write(source, { source }, source).source, source)
+})
+test('old/invalid/duplicate-key sources never become a V3 saved draft', () => {
+  assert.throws(() => prepareV3Write('{"version":2,"parts":[]}'))
+  assert.throws(() => prepareV3Write('{"version":1,"version":2}'))
+  assert.throws(() => prepareV3Write('{'))
+})
+
+test('SQLite compare-and-swap rejects a stale editor and another tenant', async () => {
+  const db = new DatabaseSync(':memory:')
+  try {
+    db.exec('CREATE TABLE figures(id TEXT PRIMARY KEY,domain_id TEXT,source TEXT)')
+    db.prepare('INSERT INTO figures VALUES(?,?,?)').run('A', 'tenant-A', 'original')
+    const update = async (where: { id: string; domain: { id: string }; source: string }) => {
+      const result = db
+        .prepare('UPDATE figures SET source=? WHERE id=? AND domain_id=? AND source=?')
+        .run('next', where.id, where.domain.id, where.source)
+      return { affected: Number(result.changes) }
+    }
+    await assert.rejects(compareAndSwapV3(update, 'A', 'tenant-B', 'original'))
+    await compareAndSwapV3(update, 'A', 'tenant-A', 'original')
+    await assert.rejects(compareAndSwapV3(update, 'A', 'tenant-A', 'original'))
+    await assert.rejects(compareAndSwapV3(update, 'A', 'tenant-A', undefined))
+    assert.equal(db.prepare('SELECT source FROM figures WHERE id=?').get('A')!.source, 'next')
+  } finally {
+    db.close()
+  }
+})