@things-factory/figure-service 10.1.3

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

@@ -0,0 +1,60 @@
+import { In } from 'typeorm'
+import { Args, Arg, Ctx, Directive, Query, Resolver } from 'type-graphql'
+
+import { Domain, getQueryBuilderFromListParams, getRepository, ListParam } from '@things-factory/shell'
+
+import { Figure } from './figure.js'
+import { FigureList } from './figure-type.js'
+
+@Resolver(Figure)
+export class FigureQuery {
+  @Directive('@privilege(category: "figure", privilege: "query", domainOwnerGranted: true)')
+  @Query(returns => Figure, { nullable: true, description: 'Finds a single figure by its ID.' })
+  async figure(@Arg('id') id: string, @Ctx() context: ResolverContext): Promise<Figure> {
+    const { domain } = context.state
+
+    // 부모 도메인의 Figure 도 보인다 — Board 와 같은 범위 규칙이다.
+    return await getRepository(Figure).findOne({
+      where: { domain: { id: In([domain.id, domain.parentId].filter(Boolean)) }, id }
+    })
+  }
+
+  @Directive('@privilege(category: "figure", privilege: "query", domainOwnerGranted: true)')
+  @Query(returns => FigureList, { description: 'Lists figures. Sortable by score, triangles, name, updatedAt.' })
+  async figures(@Args() params: ListParam, @Ctx() context: ResolverContext): Promise<FigureList> {
+    const { domain } = context.state
+
+    const queryBuilder = getQueryBuilderFromListParams({
+      repository: getRepository(Figure),
+      params,
+      domain,
+      alias: 'figure',
+      searchables: ['type', 'name', 'description', 'category']
+    })
+
+    const [items, total] = await queryBuilder.getManyAndCount()
+
+    return { items, total }
+  }
+
+  /**
+   * 등록된 타입 이름 목록.
+   *
+   * 저작 화면이 **새 타입 이름이 이미 쓰이는지** 물어보는 데 쓴다. `type` 은 저장되는
+   * 식별자라 만든 뒤에 고칠 수 없으므로, 만들기 전에 알려 줘야 한다.
+   *
+   * `state` 로 걸러지지 않는다 — `draft` 인 Figure 의 이름도 이미 점유된 것이다.
+   */
+  @Directive('@privilege(category: "figure", privilege: "query", domainOwnerGranted: true)')
+  @Query(returns => [String], { description: 'All figure type names in scope — used to check name collisions before create.' })
+  async figureTypeNames(@Ctx() context: ResolverContext): Promise<string[]> {
+    const { domain } = context.state
+
+    const rows = await getRepository(Figure).find({
+      where: { domain: { id: In([domain.id, domain.parentId].filter(Boolean)) } },
+      select: { type: true }
+    })
+
+    return rows.map(r => r.type).filter(Boolean)
+  }
+}

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

@@ -0,0 +1,129 @@
+/**
+ * figure-source — 정본이 들어오는 문에서 무엇을 막고 무엇을 알리나.
+ *
+ * 이 파일이 지키는 것은 하나다. **서버가 형식을 어긴 정본을 저장하지 않는다.**
+ * 저작 화면이 검증하니 서버는 믿어도 된다는 말이 안 되는 이유는, 저작 화면을 거치지
+ * 않는 길(가져오기·API·AI 어시스턴트)이 있기 때문이다.
+ *
+ * 그리고 파생값(`score`·`triangles`·`groups`)을 **클라이언트에서 받지 않는다**는 것도
+ * 여기서 지킨다. 받으면 목록 화면이 실물과 다른 것을 보여 준다.
+ */
+import { FigureSourceError, parseSource } from './figure-source'
+
+/** 온전한 부품 하나. 시험할 필드만 덮어쓴다. */
+function part(over: Record<string, unknown> = {}) {
+  return {
+    name: 'body',
+    primitive: 'cube',
+    transform: { position: { x: 0, y: 0, z: 0 }, size: { x: 100, y: 100, z: 100 } },
+    material: { token: 'palette.primary' },
+    ...over
+  }
+}
+
+/** 온전한 정본 하나. */
+function source(over: Record<string, unknown> = {}) {
+  return {
+    type: 'MIXER',
+    base: { x: 300, y: 800, z: 300 },
+    detailLevel: 'M',
+    parts: [part()],
+    ...over
+  }
+}
+
+const json = (v: unknown) => JSON.stringify(v)
+
+describe('figure-source — 들어오는 문', () => {
+  describe('막는다', () => {
+    it('JSON 이 아니면 던진다 — 무엇이 잘못됐는지 말한다', () => {
+      let thrown: FigureSourceError | undefined
+      try {
+        parseSource('{ 이건 JSON 이 아니다')
+      } catch (e) {
+        thrown = e as FigureSourceError
+      }
+
+      expect(thrown).toBeInstanceOf(FigureSourceError)
+      expect(thrown!.findings[0].code).toBe('source-not-json')
+      // 조용히 빈 값으로 넘기지 않는다
+      expect(thrown!.findings[0].message).toContain('JSON')
+    })
+
+    it('객체가 아니면 던진다', () => {
+      for (const bad of ['null', '42', '"x"', '[]']) {
+        expect(() => parseSource(bad)).toThrow(FigureSourceError)
+      }
+    })
+
+    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)
+      }
+    })
+
+    it('어디서 났는지(path)를 함께 전한다 — 화면이 그 자리를 가리킬 수 있게', () => {
+      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 } } })] })))
+      } catch (e) {
+        thrown = e as FigureSourceError
+      }
+
+      expect(thrown).toBeInstanceOf(FigureSourceError)
+      expect(thrown!.findings.some(f => !!f.at)).toBe(true)
+    })
+  })
+
+  describe('통과시킨다', () => {
+    it('온전한 정본은 그대로 통과한다', () => {
+      const result = parseSource(json(source()))
+      expect(result.violations).toEqual([])
+    })
+
+    it('정본을 다시 직렬화하지 않는다 — 들어온 문자열을 그대로 저장한다', () => {
+      // 다시 만들면 키 순서·공백이 바뀌어 「고치지 않았는데 바뀌었다」가 된다
+      const raw = json(source())
+      expect(parseSource(raw).source).toBe(raw)
+    })
+  })
+
+  describe('파생값은 서버가 계산한다', () => {
+    it('점수·삼각형 수·묶음 수가 채워진다', () => {
+      const { derived } = parseSource(json(source()))
+
+      expect(typeof derived.score).toBe('number')
+      expect(derived.score).toBeGreaterThanOrEqual(0)
+      expect(derived.score).toBeLessThanOrEqual(100)
+      expect(derived.triangles).toBeGreaterThan(0)
+      expect(derived.groups).toBeGreaterThan(0)
+    })
+
+    it('클라이언트가 보낸 값은 쓰이지 않는다 — 정본만 본다', () => {
+      // 정본 안에 거짓 파생값을 심어도 셈은 부품에서 나온다
+      const lying = json(source({ score: 100, triangles: 1, groups: 1 } as Record<string, unknown>))
+      const honest = json(source())
+
+      expect(parseSource(lying).derived).toEqual(parseSource(honest).derived)
+    })
+
+    it('부품이 늘면 삼각형 수도 는다 — 셈이 정본을 실제로 읽는다', () => {
+      const one = parseSource(json(source())).derived.triangles
+      const two = parseSource(json(source({ parts: [part(), part({ name: 'lid' })] }))).derived.triangles
+
+      expect(two).toBeGreaterThan(one)
+    })
+  })
+})

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

@@ -0,0 +1,87 @@
+import { compile, costOf, scoreOf, validate } from '@hatiolab/figure-model'
+
+import { FigureFinding } from './figure-type.js'
+
+/**
+ * 정본을 받아 **검증하고 파생값을 계산한다.**
+ *
+ * ## 왜 서버가 검증하나
+ *
+ * 저작 화면을 못 믿어서가 아니다. **저작 화면을 거치지 않는 길이 있다** — 가져오기,
+ * API 직접 호출, AI 어시스턴트. 그 길로 들어온 정본이 형식을 어기면 보드에서 조용히
+ * 안 그려진다. 들어오는 문에서 막는다.
+ *
+ * ## 막는 것과 알리는 것
+ *
+ * `figure-model` 이 두 단계로 나눠 놓았고, 서버가 그 경계를 다시 정하지 않는다.
+ *
+ *   errors      형식을 어긴 것. **거절한다**
+ *   violations  한도를 넘은 것. 거절하지 않고 **함께 돌려준다**
+ *
+ * ## 파생값은 서버가 계산한다
+ *
+ * `score`·`triangles`·`groups` 를 클라이언트에서 받지 않는다. 받으면 거짓이 들어오고
+ * 목록 화면이 실물과 다른 것을 보여 준다. 정본에서 계산한다.
+ */
+export interface ParsedSource {
+  /** 저장할 정본 JSON 문자열. 들어온 것을 그대로 쓴다 — 다시 직렬화하지 않는다. */
+  source: string
+  /** 목록 화면이 정렬·필터에 쓰는 파생값. */
+  derived: { score: number; triangles: number; groups: number }
+  /** 막지 않는 발견. 호출한 쪽이 응답에 실어 보낸다. */
+  violations: FigureFinding[]
+}
+
+/** 정본이 형식을 어겼다. 저장하지 않는다. */
+export class FigureSourceError extends Error {
+  readonly findings: FigureFinding[]
+
+  constructor(findings: FigureFinding[]) {
+    super(`정본이 형식을 어겼다 — ${findings.length}건: ${findings.map(f => f.code).join(', ')}`)
+    this.name = 'FigureSourceError'
+    this.findings = findings
+  }
+}
+
+/**
+ * 정본 JSON 문자열을 검증하고 파생값을 계산한다.
+ *
+ * @throws {FigureSourceError} JSON 이 아니거나 형식을 어긴 경우
+ */
+export function parseSource(sourceJson: string): ParsedSource {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(sourceJson)
+  } catch (e) {
+    throw new FigureSourceError([
+      { code: 'source-not-json', message: `정본이 JSON 이 아니다: ${(e as Error).message}`, at: 'source' }
+    ])
+  }
+
+  const result = validate(parsed)
+  if (result.errors.length > 0) {
+    throw new FigureSourceError(
+      result.errors.map(e => ({ code: e.code, message: e.message, at: e.path }))
+    )
+  }
+
+  // 여기까지 왔으면 형식은 맞다. 청사진을 만들어 셈에 쓴다.
+  // 청사진 자체는 **저장하지 않는다** — 파생 캐시이므로 소비하는 쪽이 다시 만든다.
+  const blueprint = compile(parsed as any)
+  const cost = costOf(blueprint, 1)
+  const score = scoreOf(blueprint)
+
+  return {
+    source: sourceJson,
+    derived: {
+      score: score.score,
+      triangles: cost.triangles,
+      groups: cost.groups
+    },
+    violations: result.violations.map(v => ({
+      code: v.code,
+      message: v.message,
+      at: undefined
+    }))
+  }
+}

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

@@ -0,0 +1,108 @@
+import { Field, InputType, Int, ObjectType } from 'type-graphql'
+
+import { Figure } from './figure.js'
+
+/**
+ * 새 Figure.
+ *
+ * `score`·`triangles`·`groups` 는 **받지 않는다.** 서버가 `source` 에서 계산한다 —
+ * 받으면 거짓이 들어오고 목록이 실물과 다른 것을 보여 준다.
+ */
+@InputType({ description: 'Input for creating a new figure.' })
+export class NewFigure {
+  @Field({ description: 'Component type name. Immutable once created, unique per domain.' })
+  type: string
+
+  @Field({ description: 'Display name shown to authors.' })
+  name: string
+
+  @Field({ nullable: true, description: 'A detailed description for the figure.' })
+  description?: string
+
+  @Field({ nullable: true, description: 'Classification code used to group figures in the palette.' })
+  category?: string
+
+  @Field({ description: 'The canonical FigureSource JSON.' })
+  source: string
+
+  @Field({ nullable: true, description: 'JSON definition of the master-data fields an instance carries.' })
+  properties?: string
+
+  @Field({ nullable: true, description: "Lifecycle state — defaults to 'draft'." })
+  state?: 'draft' | 'released'
+
+  @Field({ nullable: true, description: 'A base64 encoded thumbnail image.' })
+  thumbnail?: string
+}
+
+/**
+ * 수정.
+ *
+ * `type` 이 없다. **저장되는 식별자라 고칠 수 없다** — 바꾸면 이미 배치된 보드가
+ * 타입을 못 찾아 오류 없이 빈 화면이 된다. 고칠 수 있는 이름은 `name` 뿐이다.
+ */
+@InputType({ description: 'Input for updating an existing figure. The `type` field is absent by design — it is a stored identifier.' })
+export class FigurePatch {
+  @Field({ nullable: true, description: 'The new display name.' })
+  name?: string
+
+  @Field({ nullable: true, description: 'The new description.' })
+  description?: string
+
+  @Field({ nullable: true, description: 'The new classification code.' })
+  category?: string
+
+  @Field({ nullable: true, description: 'The new FigureSource JSON.' })
+  source?: string
+
+  @Field({ nullable: true, description: 'The new master-data field definition.' })
+  properties?: string
+
+  @Field({ nullable: true, description: 'The new lifecycle state.' })
+  state?: 'draft' | 'released'
+
+  @Field({ nullable: true, description: 'A base64 encoded thumbnail image.' })
+  thumbnail?: string
+}
+
+@ObjectType({ description: 'A paginated list of figures.' })
+export class FigureList {
+  @Field(type => [Figure], { description: 'The figures on this page.' })
+  items: Figure[]
+
+  @Field(type => Int, { description: 'Total number of figures matching the query.' })
+  total: number
+}
+
+/**
+ * 검증 결과 한 줄.
+ *
+ * 정본 형식의 검증은 `@hatiolab/figure-model` 이 두 단계로 나눈다 — `errors` 는
+ * 막고, `violations` 는 알린다. 그 경계를 서버가 다시 정하지 않는다.
+ */
+@ObjectType({ description: 'One validation finding from figure-model.' })
+export class FigureFinding {
+  @Field({ description: 'Stable code from figure-model (ERROR_CODES / VIOLATION_CODES).' })
+  code: string
+
+  @Field({ description: 'Human-readable message.' })
+  message: string
+
+  @Field({ nullable: true, description: 'Path within the source that the finding points at.' })
+  at?: string
+}
+
+/**
+ * 저장 결과.
+ *
+ * `violations` 가 있어도 저장은 된다 — 막는 것과 알리는 것을 가른다. 화면이
+ * 이것을 그대로 보여 줘야 한다. 조용히 버리면 저작자가 모른다.
+ */
+@ObjectType({ description: 'Result of saving a figure, carrying non-blocking violations.' })
+export class FigureSaveResult {
+  @Field(type => Figure, { description: 'The saved figure.' })
+  figure: Figure
+
+  @Field(type => [FigureFinding], { description: 'Non-blocking findings. The save succeeded despite these.' })
+  violations: FigureFinding[]
+}

package/server/service/figure/figure.ts

@@ -0,0 +1,168 @@
+import {
+  Column,
+  CreateDateColumn,
+  DeleteDateColumn,
+  Entity,
+  Index,
+  ManyToOne,
+  PrimaryGeneratedColumn,
+  RelationId,
+  UpdateDateColumn
+} from 'typeorm'
+import { Field, Float, ID, Int, ObjectType } from 'type-graphql'
+
+import { User } from '@things-factory/auth-base'
+import { Domain, longTextColumn } from '@things-factory/shell'
+
+/**
+ * Figure — 저작된 3D 컴포넌트 한 종류.
+ *
+ * `Board` 를 준용한다. 다른 점만 주석으로 적는다.
+ *
+ * ## 무엇을 담나 — `FigureSource` 다, 씬 모델이 아니다
+ *
+ * 정본 형식은 `@hatiolab/figure-model` 이 정한다(`FigureSource`). 씬 컴포넌트 트리를
+ * 담지 않는다. 담으면 저작도구가 씬 편집기가 되고, 부품 이름·상태 슬롯·애니메이션
+ * 자리가 형식에 없어 따로 관리해야 한다.
+ *
+ * 청사진(`FigureBlueprint`)은 **저장하지 않는다.** 정본에서 파생되는 캐시이므로
+ * 소비하는 쪽이 `compile()` 로 만든다. 저장하면 정본과 갈린다.
+ *
+ * 그래서 `baseWidth`·`anchor`·`statusSlots`·`parts`·`animations` 같은 것을 컬럼으로
+ * 두지 않는다 — 전부 `source` 안에 이미 있는 자리다. 두 벌이면 갈린다.
+ *
+ * 설계: `docs/design/figure-modules.md` §2
+ */
+@Entity()
+@Index('ix_figure_1', (figure: Figure) => [figure.domain, figure.type], {
+  unique: true,
+  where: '"deleted_at" IS NULL'
+})
+@Index('ix_figure_2', (figure: Figure) => [figure.domain, figure.category])
+@ObjectType({ description: 'An authored 3D component type — the canonical FigureSource plus its metadata.' })
+export class Figure {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(type => ID, { nullable: true, description: 'Unique identifier for the figure.' })
+  readonly id?: string
+
+  @Column({ nullable: true, default: 1 })
+  @Field(type => Int, { nullable: true, description: 'Revision counter, incremented on each save.' })
+  version?: number = 1
+
+  @ManyToOne(type => Domain)
+  @Field(type => Domain, { nullable: true, description: 'The domain this figure belongs to.' })
+  domain?: Domain
+
+  @RelationId((figure: Figure) => figure.domain)
+  domainId?: string
+
+  /**
+   * 컴포넌트 타입 이름. **저장되는 식별자다.**
+   *
+   * 배치된 보드가 이 이름으로 타입을 찾는다. 바꾸면 그 보드는 타입을 못 찾아
+   * **오류 없이 빈 화면**이 된다. 그래서 만들 때 정하고 잠근다 — 고칠 수 있는 것은
+   * 표시 이름(`name`)뿐이다. 수정 리졸버가 이 필드를 받지 않는다.
+   *
+   * `Board.type`(main/sub/popup)과 뜻이 전혀 다르다. 혼동하지 않는다.
+   */
+  @Column()
+  @Field({ description: 'Component type name. A stored identifier — unique per domain and immutable once created.' })
+  type?: string
+
+  @Column()
+  @Field({ description: 'Display name shown to authors. Safe to rename.' })
+  name?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'A detailed description for the figure.' })
+  description?: string
+
+  /** 분류 코드. 팔레트에서 묶어 보이는 기준. */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Classification code used to group figures in the palette.' })
+  category?: string
+
+  @Column({ nullable: true, default: 'draft' })
+  @Field({ nullable: true, description: "Lifecycle state — 'draft' figures do not appear in the board palette." })
+  state?: 'draft' | 'released'
+
+  /**
+   * `FigureSource` JSON.
+   *
+   * `Board.model` 자리이지만 이름을 바꿨다 — 「씬 모델이 아니다」를 필드 이름이
+   * 드러내야 한다.
+   */
+  @Column({ nullable: true, ...longTextColumn() })
+  @Field({ nullable: true, description: 'The canonical FigureSource JSON authored by the modeller.' })
+  source?: string
+
+  // ── 파생값 — 저장하는 이유가 하나뿐이다 ──────────────────────────────────
+  //
+  // 셋 다 `source` 에서 계산된다. 그런데도 컬럼으로 두는 이유는 **목록 화면이
+  // 정렬·필터를 해야** 하기 때문이다. JSON 을 파싱해 정렬할 수는 없다.
+  //
+  // 저장할 때 `figure-model` 로 계산해 채운다. **클라이언트가 준 값을 받지 않는다** —
+  // 받으면 거짓이 들어오고, 목록이 실물과 다른 것을 보여 준다.
+
+  /** 재활용 점수 0~100. `scoreOf()` 가 계산한다. */
+  @Column({ type: 'float', nullable: true })
+  @Field(type => Float, { nullable: true, description: 'Reuse score 0-100, computed from source on save.' })
+  score?: number
+
+  /** 삼각형 수. `costOf()` 가 계산한다. */
+  @Column({ nullable: true })
+  @Field(type => Int, { nullable: true, description: 'Triangle count, computed from source on save.' })
+  triangles?: number
+
+  /** 재질 묶음 수 — 인스턴스당 draw call 의 근거. */
+  @Column({ nullable: true })
+  @Field(type => Int, { nullable: true, description: 'Material group count — the basis of per-instance draw calls.' })
+  groups?: number
+
+  /** 기준정보 항목 정의. Figure 를 배치할 때 인스턴스가 채우는 자리. */
+  @Column({ nullable: true, ...longTextColumn() })
+  @Field({ nullable: true, description: 'JSON definition of the master-data fields an instance of this figure carries.' })
+  properties?: string
+
+  @Column({ nullable: true, ...longTextColumn() })
+  @Field({ nullable: true, description: 'A base64 encoded thumbnail image of the figure.' })
+  thumbnail?: string
+
+  /**
+   * 썸네일이 **썸네일로서** 마지막으로 갱신된 시각. `updatedAt` 과는 별개 도메인이다 —
+   * 이름·설명만 고쳤을 때는 갱신되지 않는다. `Board` 와 같은 방식.
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Timestamp of the last thumbnail generation. Separate lifecycle from updatedAt.' })
+  thumbnailUpdatedAt?: Date
+
+  @Column({ type: 'float', nullable: true, default: 0 })
+  @Field(type => Float, { nullable: true, description: 'Sort order within a listing.' })
+  sortOrder?: number
+
+  @CreateDateColumn()
+  @Field({ nullable: true, description: 'Creation timestamp.' })
+  createdAt?: Date
+
+  @UpdateDateColumn()
+  @Field({ nullable: true, description: 'Last update timestamp.' })
+  updatedAt?: Date
+
+  @DeleteDateColumn()
+  @Field({ nullable: true, description: 'Soft-delete timestamp.' })
+  deletedAt?: Date
+
+  @ManyToOne(type => User, { nullable: true })
+  @Field(type => User, { nullable: true, description: 'The user who created this figure.' })
+  creator?: User
+
+  @RelationId((figure: Figure) => figure.creator)
+  creatorId?: string
+
+  @ManyToOne(type => User, { nullable: true })
+  @Field(type => User, { nullable: true, description: 'The user who last updated this figure.' })
+  updater?: User
+
+  @RelationId((figure: Figure) => figure.updater)
+  updaterId?: string
+}

package/server/service/figure/index.ts

@@ -0,0 +1,6 @@
+import { Figure } from './figure.js'
+import { FigureQuery } from './figure-query.js'
+import { FigureMutation } from './figure-mutation.js'
+
+export const entities = [Figure]
+export const resolvers = [FigureQuery, FigureMutation]

package/server/service/index.ts

@@ -0,0 +1,10 @@
+// Entity types
+export * from './figure/figure.js'
+export * from './figure/figure-type.js'
+export * from './figure/figure-source.js'
+
+// Entities, resolvers
+import { entities as FigureEntities, resolvers as FigureResolvers } from './figure/index.js'
+
+export const entities = [...FigureEntities]
+export const resolvers = [...FigureResolvers]

package/things-factory.config.js

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

package/tsconfig.json

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