@things-factory/figure-service 10.1.13 → 10.1.16

package/logs/.08636eb59927f12972f6774f5947c8507b3564c2-audit.json

@@ -0,0 +1,15 @@
+{
+    "keep": {
+        "days": true,
+        "amount": 2
+    },
+    "auditLog": "logs/.08636eb59927f12972f6774f5947c8507b3564c2-audit.json",
+    "files": [
+        {
+            "date": 1789397538290,
+            "name": "logs/application-2026-09-14-23.log",
+            "hash": "69c3188e63ed8031b901bd7314adfe3a91152378397ce14edd2f4fafb5a8770e"
+        }
+    ],
+    "hashType": "sha256"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/figure-service",
-  "version": "10.1.13",
+  "version": "10.1.16",
   "publishConfig": {
     "access": "public",
     "@things-factory:registry": "https://registry.npmjs.org"
@@ -23,14 +23,15 @@
     "migration:create": "node ../../node_modules/typeorm/cli.js migration:create ./server/migrations/migration"
   },
   "dependencies": {
-    "@hatiolab/figure-model": "^0.1.16",
+    "@hatiolab/figure-model": "^0.1.17",
     "@operato/typeorm-history": "^10.0.0",
     "@things-factory/ai-client-base": "^10.1.8",
-    "@things-factory/auth-base": "^10.1.7",
+    "@things-factory/auth-base": "^10.1.16",
     "@things-factory/env": "^10.1.3",
-    "@things-factory/shell": "^10.1.7",
+    "@things-factory/shell": "^10.1.16",
+    "graphql-scalars": "^1.22.4",
     "graphql-upload": "^15.0.2",
     "koa-router": "^7.4.0"
   },
-  "gitHead": "f2cd3d27e32e71cca1d3af5499ef54249b1cc111"
+  "gitHead": "aff86bc162b42c1d933711f7bc85a073f1ddcd29"
 }

package/server/service/figure/figure-blueprint-query.test.ts

@@ -0,0 +1,207 @@
+import type { DataSource } from 'typeorm'
+
+const { DataSource: TypeOrmDataSource } = require('typeorm')
+const shell = require('@things-factory/shell')
+const authBase = require('@things-factory/auth-base')
+
+let dataSource: DataSource | null = null
+let Figure: any
+let FigureHistory: any
+let FigureQuery: any
+let testDomain: any
+
+function loadCompiled(modulePath: string): any {
+  const { existsSync } = require('fs')
+  const { join } = require('path')
+  const resolved = join(__dirname, '..', '..', '..', 'dist-server', `${modulePath}.js`)
+
+  if (!existsSync(resolved)) {
+    throw new Error(
+      `figure-service 산출물이 없다: ${resolved}\n` +
+        `이 시험은 tsc 산출물을 든다. 먼저 빌드할 것:\n` +
+        `  yarn workspace @things-factory/figure-service build:server`
+    )
+  }
+
+  return require(resolved)
+}
+
+const sampleSource = JSON.stringify({
+  version: 1,
+  type: 'TEST_BOX',
+  base: { x: 100, y: 100, z: 100 },
+  parts: [
+    {
+      name: 'box-1',
+      primitive: 'cube',
+      transform: { position: { x: 0, y: 0, z: 0 }, size: { x: 100, y: 100, z: 100 } },
+      material: { token: 'palette.primary' }
+    }
+  ]
+})
+
+beforeAll(async () => {
+  Figure = loadCompiled('service/figure/figure').Figure
+  FigureHistory = loadCompiled('service/figure/figure-history').FigureHistory
+  FigureQuery = loadCompiled('service/figure/figure-query').FigureQuery
+
+  dataSource = new TypeOrmDataSource({
+    type: 'sqlite',
+    database: ':memory:',
+    synchronize: true,
+    dropSchema: true,
+    namingStrategy: new shell.NamingStrategy(),
+    entities: [...shell.entities, ...authBase.entities, Figure, FigureHistory],
+    logging: false
+  })
+
+  await dataSource.initialize()
+  shell.addDataSource('default', dataSource)
+  shell.addDataSource('tx', dataSource)
+})
+
+beforeEach(async () => {
+  await dataSource!.synchronize(true)
+  testDomain = await dataSource!.getRepository(shell.Domain).save({
+    name: 'test-domain',
+    subdomain: 'test-domain'
+  })
+})
+
+afterAll(async () => {
+  if (!dataSource) return
+  shell.removeDataSource('default')
+  shell.removeDataSource('tx')
+  await dataSource.destroy()
+  dataSource = null
+})
+
+function makeContext() {
+  return {
+    state: {
+      domain: testDomain,
+      user: { id: 'user-1' }
+    }
+  } as any
+}
+
+describe('figureBlueprint 질의 — 소비처(board, twin, things-scene)를 위한 청사진 전달', () => {
+  it('존재하지 않는 타입은 null을 반환한다', async () => {
+    const query = new FigureQuery()
+    const result = await query.figureBlueprint('NON_EXISTENT', makeContext())
+    expect(result).toBeNull()
+  })
+
+  it('초안(draft) 상태이고 발행 이력이 없는 Figure는 null을 반환한다 (초안 유출 차단)', async () => {
+    const repo = dataSource!.getRepository(Figure)
+    await repo.save({
+      domain: testDomain,
+      type: 'DRAFT_FIGURE',
+      name: '초안 도형',
+      state: 'draft',
+      source: sampleSource,
+      version: 0
+    })
+
+    const query = new FigureQuery()
+    const result = await query.figureBlueprint('DRAFT_FIGURE', makeContext())
+    expect(result).toBeNull()
+  })
+
+  it('발행된(released) Figure는 올바르게 컴파일된 Blueprint를 반환한다', async () => {
+    const repo = dataSource!.getRepository(Figure)
+    await repo.save({
+      domain: testDomain,
+      type: 'RELEASED_FIGURE',
+      name: '발행 도형',
+      state: 'released',
+      source: sampleSource,
+      version: 1
+    })
+
+    const query = new FigureQuery()
+    const result = await query.figureBlueprint('RELEASED_FIGURE', makeContext())
+    expect(result).not.toBeNull()
+    expect(result.type).toBe('TEST_BOX')
+    expect(result.groups).toBeDefined()
+    expect(result.groups.length).toBe(1)
+    expect(result.groups[0].members[0].name).toBe('box-1')
+  })
+
+  it('현재 저작 중(draft)이더라도 과거 발행판(FigureHistory)이 있으면 최신 발행판을 컴파일해 반환한다', async () => {
+    const repo = dataSource!.getRepository(Figure)
+    const historyRepo = dataSource!.getRepository(FigureHistory)
+
+    const v1Source = sampleSource
+    const v2DraftSource = JSON.stringify({
+      version: 1,
+      type: 'UPDATING_FIGURE',
+      base: { x: 200, y: 200, z: 200 },
+      parts: [
+        {
+          name: 'box-modified',
+          primitive: 'cube',
+          transform: { position: { x: 0, y: 0, z: 0 }, size: { x: 200, y: 200, z: 200 } },
+          material: { token: 'palette.primary' }
+        }
+      ]
+    })
+
+    const figure = await repo.save({
+      domain: testDomain,
+      type: 'UPDATING_FIGURE',
+      name: '수정 중인 도형',
+      state: 'draft',
+      source: v2DraftSource,
+      version: 1
+    })
+
+    // 과거 발행된 v1 이력
+    await historyRepo.save({
+      domain: testDomain,
+      originalId: figure.id,
+      type: 'UPDATING_FIGURE',
+      name: 'v1 발행판',
+      state: 'released',
+      version: 1,
+      source: v1Source
+    })
+
+    const query = new FigureQuery()
+    const result = await query.figureBlueprint('UPDATING_FIGURE', makeContext())
+
+    expect(result).not.toBeNull()
+    // 소비처는 수정 중인 초안(box-modified, size 200)이 아니라 기발행된 판(box-1, size 100)을 본다!
+    expect(result.groups[0].members[0].name).toBe('box-1')
+    expect(result.groups[0].members[0].transform.size.x).toBe(100)
+  })
+
+  /*
+    Every test above calls the resolver method directly, so none of them passes through the
+    `@privilege` directive — that is attached when the schema is assembled. They stay green
+    whether the declaration is there or not.
+
+    Without a declaration this field is open to callers who have not even signed in
+    (`auth-rebuild.md` §1), so that gap is the thing worth guarding. The check reads the source
+    rather than the compiled output because the declaration is authored there, and it pins the
+    category: `figure` is the authoring permission, and requiring it here would leave board and
+    twin users with an empty palette. Someone who hits that wall will be tempted to delete this
+    line; the failure message is for them.
+  */
+  it('declares figure-published on the consumer door, not the authoring permission', () => {
+    const { readFileSync } = require('fs')
+    const { join } = require('path')
+    const source = readFileSync(join(__dirname, 'figure-query.ts'), 'utf-8')
+
+    const at = source.indexOf('async figureBlueprint')
+    expect(at).toBeGreaterThan(-1)
+
+    const preceding = source.slice(0, at)
+    const directive = preceding.lastIndexOf("@Directive('@privilege(")
+    const declaration = preceding.slice(directive, preceding.indexOf('\n', directive))
+
+    expect(declaration).toContain('category: "figure-published"')
+    expect(declaration).toContain('privilege: "query"')
+    expect(declaration).toContain('domainOwnerGranted: true')
+  })
+})

package/server/service/figure/figure-propose.ts

@@ -7,6 +7,7 @@ import {
   PRIMITIVE_KINDS,
   SEGMENT_PRESETS,
   SIZING_RULES,
+  FIGURE_PLACEMENTS,
   compile,
   costOf,
   scoreOf,
@@ -131,13 +132,14 @@ export function rulesPrompt(palette: string[]): string {
     'Answer with a single JSON object and nothing else — no prose, no code fence.',
     '',
     'The JSON is a FigureSource:',
-    '  { type, base: {x,y,z}, detailLevel, parts: [...] }',
+    '  { type, base: {x,y,z}, placement?, detailLevel, parts: [...] }',
     '',
     'A part is:',
     '  { name, primitive, transform: { position: {x,y,z}, size: {x,y,z}, rotation?: {x,y,z} },',
     '    material: {token, preset?}, segments?, shape?, sizing? }',
     '',
     'Hard vocabulary — anything outside these is rejected:',
+    `  placement   ${FIGURE_PLACEMENTS.join(' | ')} (floor: default, ground equipment; ceiling: overhead hoist/OHT; center: airborne/drone/sensor)`,
     `  primitive   ${PRIMITIVE_KINDS.join(' | ')}`,
     `  segments    ${SEGMENT_PRESETS.join(' | ')} (only for cylinder and sphere)`,
     `  material.token  ${palette.join(' | ')}`,

package/server/service/figure/figure-query.ts

@@ -1,5 +1,7 @@
 import { In } from 'typeorm'
 import { Args, Arg, Ctx, Directive, Query, Resolver } from 'type-graphql'
+import { GraphQLJSON } from 'graphql-scalars'
+import { compile } from '@hatiolab/figure-model'
 
 import { Domain, getQueryBuilderFromListParams, getRepository, ListParam } from '@things-factory/shell'
 
@@ -126,4 +128,86 @@ export class FigureQuery {
 
     return rows.map(r => r.type).filter(Boolean)
   }
+
+  /**
+   * 소비처(operato-board, operato-twin, things-scene)를 위한 컴파일된 청사진(FigureBlueprint) 질의.
+   *
+   * ## 규칙
+   * 1. 소비처는 초안(draft)을 볼 수 없다 — **반드시 발행된(released) 판만 전달**한다.
+   * 2. 현재 Figure가 released 상태이면 현재 source를 컴파일한다.
+   * 3. 현재 Figure가 저작 중(draft)이더라도 이전에 발행된 이력(FigureHistory)이 있으면
+   *    가장 최근의 released 판본을 컴파일하여 하위 호환성을 유지한다.
+   * 4. 한 번도 발행된 적 없는 초안 자산이거나 존재하지 않는 타입인 경우 null을 반환하여
+   *    미완성 자산이 씬 화면에 유출되는 것을 엄격히 차단한다.
+   * 5. 도메인 상속 시 자식 도메인의 타입이 부모 도메인의 동일 타입을 항상 오버라이드한다.
+   * 6. 권한은 저작(`figure`)과 **다른 category** 인 `figure-published` 다. 소비처 사용자에게
+   *    저작 권한을 요구하면 board·twin 의 팔레트가 안 뜨고, 그렇다고 선언을 비우면 이 집에서는
+   *    로그인조차 안 한 사람에게 열린다(`auth-rebuild.md` §1). `<module>-published` 는
+   *    「그 모듈이 발행한 것을 남이 읽는 문」이라는 규약이다 — 아키텍트 판정(2026-09-15).
+   *
+   * ## 열거는 막혀 있다 — 지금은 우연이다
+   *
+   * 이 문의 열쇠는 `type` 하나뿐이라 이름을 모르면 못 꺼낸다. 그런데 그것이 **설계가 아니다** —
+   * 목록을 내는 `figures`·`figureTypeNames` 가 `figure` category 로 잠겨 있어서 결과적으로
+   * 그런 것뿐이다. 나중에 누가 소비처용 목록 문을 하나 더 열고 `figure-published` 를 붙이면
+   * 열거가 함께 열리고, 「이름을 알아야 한다」에 기대고 있던 가정이 조용히 사라진다.
+   * 그 문을 낼 사람이 이 단락을 읽고 그때 정하면 된다.
+   */
+  /*
+    This directive is attached by schema assembly, so a test that calls the resolver method
+    directly never exercises it. `figure-blueprint-query.test.ts` reads this source for the
+    declaration instead — see the test named for it there.
+  */
+  @Directive('@privilege(category: "figure-published", privilege: "query", domainOwnerGranted: true)')
+  @Query(returns => GraphQLJSON, {
+    nullable: true,
+    description: 'Compiled FigureBlueprint for external consumers (board, twin, things-scene). Only returns released figures.'
+  })
+  async figureBlueprint(
+    @Arg('type') type: string,
+    @Ctx() context: ResolverContext
+  ): Promise<any> {
+    const { domain } = context.state
+
+    // 자식 도메인 자산 우선 탐색 후, 부모 도메인 표준 자산으로 폴백 (오버라이드 보장)
+    let figure = await getRepository(Figure).findOne({
+      where: { domain: { id: domain.id }, type }
+    })
+    if (!figure && domain.parentId) {
+      figure = await getRepository(Figure).findOne({
+        where: { domain: { id: domain.parentId }, type }
+      })
+    }
+
+    if (!figure) {
+      return null
+    }
+
+    let sourceToCompile: string | null = null
+
+    if (figure.state === 'released' && figure.source) {
+      sourceToCompile = figure.source
+    } else if (figure.id) {
+      // 저작 중(draft)인 경우 최근 발행 이력(FigureHistory)을 확인한다
+      const latestReleased = await getRepository(FigureHistory).findOne({
+        where: { domain: { id: figure.domain?.id ?? domain.id }, originalId: figure.id, state: 'released' },
+        order: { version: 'DESC' }
+      })
+      if (latestReleased && latestReleased.source) {
+        sourceToCompile = latestReleased.source
+      }
+    }
+
+    if (!sourceToCompile) {
+      return null
+    }
+
+    try {
+      const parsed = typeof sourceToCompile === 'string' ? JSON.parse(sourceToCompile) : sourceToCompile
+      return compile(parsed)
+    } catch (err) {
+      console.error(`[figureBlueprint] 타입 '${type}' (figure id: ${figure.id}) 청사진 컴파일 실패:`, err)
+      return null
+    }
+  }
 }

package/server/service/figure/figure-source.test.ts

@@ -24,6 +24,7 @@ function part(over: Record<string, unknown> = {}) {
 /** 온전한 정본 하나. */
 function source(over: Record<string, unknown> = {}) {
   return {
+    version: 1,
     type: 'MIXER',
     base: { x: 300, y: 800, z: 300 },
     detailLevel: 'M',
@@ -59,22 +60,21 @@ describe('figure-source — 들어오는 문', () => {
     it('형식을 어기면 던지고, figure-model 의 코드를 그대로 전한다', () => {
       let thrown: FigureSourceError | undefined
       try {
-        // 부품이 없는 정본
         parseSource(json(source({ parts: [] })))
       } catch (e) {
         thrown = e as FigureSourceError
       }
 
       expect(thrown).toBeInstanceOf(FigureSourceError)
-      expect(thrown!.findings.length).toBeGreaterThan(0)
-      // 코드를 서버가 다시 짓지 않는다 — figure-model 의 것을 그대로 쓴다
-      for (const f of thrown!.findings) {
-        expect(typeof f.code).toBe('string')
-        expect(f.code.length).toBeGreaterThan(0)
-      }
+      expect(thrown!.findings[0].code).toBe('missing-parts')
+    })
+
+    it('필수 필드가 빠지면 던진다', () => {
+      // type 없음
+      expect(() => parseSource(json({ base: { x: 1, y: 1, z: 1 }, parts: [part()] }))).toThrow(FigureSourceError)
     })
 
-    it('어디서 났는지(path)를 함께 전한다 — 화면이 그 자리를 가리킬 수 있게', () => {
+    it('오류의 위치(at)를 알린다 — 어느 부품인지 저작 화면이 짚을 수 있다', () => {
       let thrown: FigureSourceError | undefined
       try {
         parseSource(json(source({ parts: [part({ transform: { position: { x: 0, y: 0, z: 0 }, size: { x: -1, y: 1, z: 1 } } })] })))
@@ -94,10 +94,16 @@ describe('figure-source — 들어오는 문', () => {
     })
 
     it('정본을 다시 직렬화하지 않는다 — 들어온 문자열을 그대로 저장한다', () => {
-      // 다시 만들면 키 순서·공백이 바뀌어 「고치지 않았는데 바뀌었다」가 된다
+      // 이미 version이 있는 정본은 키 순서·공백을 그대로 보존한다
       const raw = json(source())
       expect(parseSource(raw).source).toBe(raw)
     })
+
+    it('version이 누락된 구형/외부 정본은 FIGURE_SOURCE_VERSION으로 보정 직렬화한다', () => {
+      const withoutVersion = json({ type: 'MIXER', base: { x: 300, y: 800, z: 300 }, detailLevel: 'M', parts: [part()] })
+      const parsed = JSON.parse(parseSource(withoutVersion).source)
+      expect(parsed.version).toBe(1)
+    })
   })
 
   describe('파생값은 서버가 계산한다', () => {

package/server/service/figure/figure-source.ts

@@ -1,4 +1,4 @@
-import { compile, costOf, scoreOf, validate } from '@hatiolab/figure-model'
+import { FIGURE_SOURCE_VERSION, compile, costOf, scoreOf, validate } from '@hatiolab/figure-model'
 
 import { FigureFinding } from './figure-type.js'
 
@@ -24,7 +24,7 @@ import { FigureFinding } from './figure-type.js'
  * 목록 화면이 실물과 다른 것을 보여 준다. 정본에서 계산한다.
  */
 export interface ParsedSource {
-  /** 저장할 정본 JSON 문자열. 들어온 것을 그대로 쓴다 — 다시 직렬화하지 않는다. */
+  /** 저장할 정본 JSON 문자열. 들어온 것을 그대로 쓴다 — 단, version 누락 시에만 정규화 직렬화한다. */
   source: string
   /** 목록 화면이 정렬·필터에 쓰는 파생값. */
   derived: { score: number; triangles: number; groups: number }
@@ -65,6 +65,14 @@ export function parseSource(sourceJson: string): ParsedSource {
     )
   }
 
+  // version이 누락된 구형/외부 입력의 경우 FIGURE_SOURCE_VERSION을 부여하여 스키마를 정규화한다.
+  // 이미 version이 있는 정본은 포맷 훼손을 막기 위해 sourceJson 원본을 그대로 보존한다.
+  let normalizedSource = sourceJson
+  if (parsed && typeof parsed === 'object' && (parsed as any).version === undefined) {
+    (parsed as any).version = FIGURE_SOURCE_VERSION
+    normalizedSource = JSON.stringify(parsed, null, 2)
+  }
+
   // 여기까지 왔으면 형식은 맞다. 청사진을 만들어 셈에 쓴다.
   // 청사진 자체는 **저장하지 않는다** — 파생 캐시이므로 소비하는 쪽이 다시 만든다.
   const blueprint = compile(parsed as any)
@@ -72,7 +80,7 @@ export function parseSource(sourceJson: string): ParsedSource {
   const score = scoreOf(blueprint)
 
   return {
-    source: sourceJson,
+    source: normalizedSource,
     derived: {
       score: score.score,
       triangles: cost.triangles,

package/server/service/figure/figure-tools.test.ts

@@ -246,6 +246,27 @@ describe('대화면 문맥에서 대상을 해소한다', () => {
       )
     ).rejects.toThrow(/does not match Figure/)
   })
+
+  it('재현: 기존 도형 편집 중 미저장 초안의 type이 FIGURE여도 현재 도형 초안으로 허용해야 한다', async () => {
+    // DB의 row는 MIXER(또는 OHT)이지만, 캔버스/도크의 초안 type은 일반 'FIGURE'일 수 있음
+    const result = await toolNamed('getFigureSource').builder(
+      {},
+      ctx({ figureId: 'fig-1', palette: ['palette.primary'], draftSource: { ...SOURCE, type: 'FIGURE' } })
+    )
+    expect(result.draft).toBe(true)
+    expect(result.type).toBe('MIXER')
+  })
+
+  it('재현: LLM이 새 미저장 모델의 임시 타입(FIGURE_MTZO5R10)을 figureId로 전달해도 초안을 읽어야 한다', async () => {
+    const tempDraft = { ...SOURCE, type: 'FIGURE_MTZO5R10' }
+    const host = { editorMode: 'new', draftSource: tempDraft, palette: ['palette.primary'] }
+    const result = await toolNamed('getFigureSource').builder(
+      { figureId: 'FIGURE_MTZO5R10' },
+      ctx(host)
+    )
+    expect(result.draft).toBe(true)
+    expect(result.type).toBe('FIGURE_MTZO5R10')
+  })
 })
 
 /*