@things-factory/figure-service 10.1.3 → 10.1.6

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

@@ -4,8 +4,10 @@ import { Arg, Ctx, Directive, Mutation, Resolver } from 'type-graphql'
 import { getRepository } from '@things-factory/shell'
 
 import { Figure } from './figure.js'
+import { FigureHistory } from './figure-history.js'
 import { FigurePatch, FigureSaveResult, NewFigure } from './figure-type.js'
 import { FigureProposal, ProposeRequest } from './figure-propose-type.js'
+import { inspectSource } from './figure-gate.js'
 import { parseSource } from './figure-source.js'
 import { ProposeFailure, proposeFigure } from './figure-propose.js'
 
@@ -76,17 +78,194 @@ export class FigureMutation {
       violations = parsed.violations
     }
 
+    /*
+      **판 번호는 여기서 손대지 않는다.** 저장은 저작이고, 판은 발행에서 생긴다(`releaseFigure`).
+      board 의 `updateBoard` 도 같다 — 저장 경로에는 version 이 없다.
+    */
     const saved = await repository.save({
+      /*
+        `domain` 을 명시로 넣는다 — 읽어 온 엔티티에는 관계가 안 실려 있다.
+
+        판본 스냅샷은 넘겨받은 엔티티를 베끼므로, 여기서 빠지면 판본의 도메인이 비고 그 판은
+        도메인으로 거르는 조회에 **한 줄도 안 걸린다**(실제로 그랬다). board 의 저장들도 같은
+        자리에서 domain 을 함께 넣는다.
+      */
+      domain,
       ...figure,
       ...patch,
       source,
+      /*
+        **고치면 발행이 풀린다.**
+
+        발행은 「이 판을 써도 된다」는 약속이고, 그 뒤에 정본이 바뀌면 약속한 것과 배포된 것이
+        달라진다. 그래서 저장은 언제나 초안으로 되돌리고, 다시 내보내려면 발행을 한 번 더 한다
+        (판 번호가 하나 오르고 판본이 하나 더 남는다). board 의 `updateBoard` 가 같은 한 줄을 쓴다.
+      */
+      state: 'draft',
       ...(derived ?? {}),
       // 썸네일이 **썸네일로서** 바뀐 때만 시각을 갱신한다. 이름·설명 변경에는 안 건드린다.
       thumbnailUpdatedAt:
         patch.thumbnail !== undefined && patch.thumbnail !== figure.thumbnail
           ? new Date()
           : figure.thumbnailUpdatedAt,
-      version: (figure.version ?? 1) + 1,
+      updater: user
+    })
+
+    return { figure: saved, violations }
+  }
+
+  /**
+   * 발행한다 — **판이 생기는 유일한 자리.**
+   *
+   * ## 무엇이 일어나나
+   *
+   * `state` 가 `released` 가 되고, 판 번호가 하나 오르고, 그 순간의 도형이 판본으로 남는다
+   * (`FigureHistory` — 스냅샷은 구독자가 뜬다). 저작 중 저장은 이 셋 중 아무것도 하지 않는다.
+   *
+   * ## 왜 이미 발행된 것을 거절하나
+   *
+   * 발행은 소비처에게 하는 약속이다. 같은 판을 두 번 발행하면 무엇이 약속인지 흐려진다. 고쳐서
+   * 다시 내려면 초안으로 되돌린 뒤 발행한다 — board 가 같은 규칙이다.
+   *
+   * ## 번호는 판본에서 센다
+   *
+   * 도형의 현재 번호가 아니라 **판본의 최대 번호 + 1** 이다. 되돌리기로 옛 판이 현재가 되어도
+   * 다음 발행이 이미 쓴 번호를 다시 쓰지 않는다.
+   *
+   * ## 게이트를 통과해야 한다
+   *
+   * 크기를 바꿨을 때 조각이 갈라지는 도형은 발행되지 않는다(`figure-gate.ts`). 소비처는 형상을
+   * 늘려 쓰므로 — 그것이 이 형식의 값이다 — 늘려도 견디는지가 약속의 일부다. 화면은 같은 판정을
+   * `inspectFigure` 로 미리 물어 이유를 보여 준다.
+   */
+  @Directive('@transaction')
+  @Directive('@privilege(category: "figure", privilege: "mutation", domainOwnerGranted: true)')
+  @Mutation(returns => Figure, { description: 'Releases a figure — raises its version and keeps the released state as history.' })
+  async releaseFigure(
+    @Arg('id') id: string,
+    @Arg('comment', { nullable: true }) comment: string,
+    @Ctx() context: ResolverContext
+  ): Promise<Figure> {
+    const { domain, user, tx } = context.state
+    const repository = tx.getRepository(Figure)
+    const historyRepository = tx.getRepository(FigureHistory)
+
+    const figure = await repository.findOne({
+      where: { domain: { id: In([domain.id, domain.parentId].filter(Boolean)) }, id }
+    })
+    if (!figure) {
+      throw new Error(`Figure ${id} 를 찾을 수 없다`)
+    }
+
+    if (figure.state === 'released') {
+      throw new Error(`Figure '${figure.type}' 은 이미 발행되어 있다. 고쳐서 다시 내려면 초안으로 되돌린 뒤 발행한다`)
+    }
+
+    /*
+      ── 게이트는 여기 있어야 한다 ────────────────────────────────────────────
+      화면도 같은 판정을 미리 물어(`inspectFigure`) 이유를 보여 주지만, **막는 자리는 이곳뿐이다.**
+      물어본 뒤 정본이 바뀌었을 수 있고, 화면을 거치지 않는 부름도 있다.
+
+      막는 이유는 사유와 함께 낸다. 「발행할 수 없습니다」로 뭉치면 무엇을 고쳐야 하는지 모른다.
+    */
+    const inspection = inspectSource(figure.source)
+    if (inspection.blocked) {
+      const reasons = inspection.findings
+        .filter(finding => finding.blocking)
+        .map(finding => (finding.at ? `${finding.message} (${finding.at})` : finding.message))
+
+      throw new Error(`Figure '${figure.type}' 은 아직 발행할 수 없다 — ${reasons.join(' · ')}`)
+    }
+
+    const highest = await historyRepository
+      .createQueryBuilder('history')
+      .select('MAX(history.version)', 'max')
+      .where('history.originalId = :id', { id: figure.id })
+      .getRawOne()
+
+    const nextVersion = highest?.max ? Number(highest.max) + 1 : 1
+
+    return await repository.save({
+      /*
+        `domain` 을 명시로 넣는다 — 읽어 온 엔티티에는 관계가 안 실려 있다.
+
+        판본 스냅샷은 넘겨받은 엔티티를 베끼므로, 여기서 빠지면 판본의 도메인이 비고 그 판은
+        도메인으로 거르는 조회에 **한 줄도 안 걸린다**(실제로 그랬다). board 의 저장들도 같은
+        자리에서 domain 을 함께 넣는다.
+      */
+      domain,
+      ...figure,
+      version: nextVersion,
+      state: 'released',
+      updater: user,
+      /* 판본 구독자가 이것을 판본의 comment 로 옮긴다. Figure 의 칸이 아니다. */
+      __releaseComment: comment ?? null
+    } as any)
+  }
+
+  /**
+   * 옛 판으로 되돌린다.
+   *
+   * ## 무엇이 돌아오나
+   *
+   * 그 판의 **정본과 속성 정의, 그리고 그림**이다. 이름·설명·분류는 그대로 둔다 — 그것들은 언제든
+   * 바꿔도 안전한 카탈로그의 말이고, 되돌리기가 개명까지 되돌리면 사람이 시키지 않은 일을 한다.
+   *
+   * ## 되돌려도 발행은 아니다
+   *
+   * 초안으로 돌아온다. 다시 내보내려면 발행을 한 번 더 하고, 그때 판 번호는 **이미 쓴 번호 다음**을
+   * 받는다 — 3판을 되살렸다고 다시 3판이 되지 않는다. board 도 같다.
+   *
+   * ## 비용은 다시 잰다
+   *
+   * 판본이 든 점수·삼각형은 **그때의 형식**으로 잰 값이다. 지금 이 도형이 그 내용이 되었으므로
+   * 오늘 기준으로 다시 계산한다. 옛 값은 판본에 그대로 남아 있다.
+   */
+  @Directive('@transaction')
+  @Directive('@privilege(category: "figure", privilege: "mutation", domainOwnerGranted: true)')
+  @Mutation(returns => FigureSaveResult, { description: 'Reverts a figure to one of its released versions. It comes back as a draft.' })
+  async revertFigureVersion(
+    @Arg('id') id: string,
+    @Arg('version') version: number,
+    @Ctx() context: ResolverContext
+  ): Promise<FigureSaveResult> {
+    const { domain, user, tx } = context.state
+    const repository = tx.getRepository(Figure)
+    const historyRepository = tx.getRepository(FigureHistory)
+
+    const figure = await repository.findOne({
+      where: { domain: { id: In([domain.id, domain.parentId].filter(Boolean)) }, id }
+    })
+    if (!figure) {
+      throw new Error(`Figure ${id} 를 찾을 수 없다`)
+    }
+
+    const history = await historyRepository.findOne({
+      where: { domain: { id: In([domain.id, domain.parentId].filter(Boolean)) }, originalId: id, version }
+    })
+    if (!history) {
+      throw new Error(`Figure '${figure.type}' 에 ${version} 판이 없다`)
+    }
+
+    /* 형식 검사도 다시 받는다 — 옛 판이 오늘의 형식을 어길 수 있고, 그것을 조용히 들이지 않는다. */
+    const { source, derived, violations } = parseSource(history.source)
+
+    const saved = await repository.save({
+      /*
+        `domain` 을 명시로 넣는다 — 읽어 온 엔티티에는 관계가 안 실려 있다.
+
+        판본 스냅샷은 넘겨받은 엔티티를 베끼므로, 여기서 빠지면 판본의 도메인이 비고 그 판은
+        도메인으로 거르는 조회에 **한 줄도 안 걸린다**(실제로 그랬다). board 의 저장들도 같은
+        자리에서 domain 을 함께 넣는다.
+      */
+      domain,
+      ...figure,
+      source,
+      ...derived,
+      properties: history.properties,
+      thumbnail: history.thumbnail,
+      thumbnailUpdatedAt: history.thumbnail === figure.thumbnail ? figure.thumbnailUpdatedAt : new Date(),
+      state: 'draft',
       updater: user
     })
 

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

@@ -37,22 +37,38 @@ function candidate(over: Record<string, unknown> = {}) {
   }
 }
 
-/** 정해 둔 답을 차례로 내놓는 가짜 모델. */
-function stubClient(answers: unknown[]): AIClient & { calls: number } {
+/**
+ * 정해 둔 답을 차례로 내놓는 가짜 모델.
+ *
+ * **받은 말을 적어 둔다.** 프롬프트에 실려 나가는 지시 중에 지켜져야 할 것이 있어서다 —
+ * 고치는 요청에서 「부품 이름을 바꾸지 말라」가 빠지면 AI 가 이름을 갈아 버리고, 그러면
+ * 이미 배치된 보드의 바인딩이 끊긴다. 답만 보는 모형으로는 그것이 나갔는지 알 수 없다.
+ */
+function stubClient(answers: unknown[]): AIClient & { calls: number; sent: any[][]; system?: string } {
   const client = {
     id: 'stub',
     calls: 0,
+    sent: [] as any[][],
+    system: undefined as string | undefined,
     async chat() {
       return ''
     },
-    async generateJSON() {
+    async generateJSON(messages: any[], options?: { systemPrompt?: string }) {
+      client.sent.push(JSON.parse(JSON.stringify(messages)))
+      client.system = options?.systemPrompt
       const answer = answers[client.calls]
       client.calls++
       if (answer instanceof Error) throw answer
       return answer
     }
   }
-  return client as unknown as AIClient & { calls: number }
+  return client as unknown as AIClient & { calls: number; sent: any[][]; system?: string }
+}
+
+/** 첫 요청에 실려 나간 사람 쪽 말. 이어 붙인 것까지 한 덩어리로 본다. */
+function firstAsk(client: { sent: any[][] }): string {
+  const content = client.sent[0]![0]!.content
+  return typeof content === 'string' ? content : JSON.stringify(content)
 }
 
 afterEach(() => setDefaultAIClient(undefined))
@@ -162,3 +178,119 @@ describe('후보를 만들 때', () => {
     )
   })
 })
+
+describe('무엇을 시키는지가 프롬프트에 실린다', () => {
+  /*
+    고치는 요청에서 이 지시가 빠지면 AI 가 부품 이름을 갈아 버린다. 부품 이름은 **저장되는
+    식별자**라서, 이미 배치된 보드의 바인딩·애니메이션이 그 이름을 가리키고 있다. 조용히
+    끊기고, 끊긴 것은 그 보드를 열어 봐야 드러난다.
+  */
+  it('고치는 요청이면 지금 정본과 「이름을 바꾸지 말라」가 함께 나간다', async () => {
+    const client = stubClient([candidate()])
+    setDefaultAIClient(client)
+
+    const base = candidate({ type: 'MIXER' }) as never
+    await proposeFigure({ prompt: '재질을 줄여줘', palette: PALETTE, base })
+
+    const ask = firstAsk(client)
+    expect(ask).toContain('Revise this existing figure')
+    expect(ask).toMatch(/renaming a part breaks bindings/)
+    // 지금 정본이 실제로 실려 나가야 한다 — 없으면 모델이 처음부터 만든다.
+    expect(ask).toContain('"name":"body"')
+  })
+
+  /*
+    타입 이름을 안 주면 `FIGURE` 로 나간다. **조용히 지어지는 값**이라 못 박아 둔다 — 저작면이
+    타입을 늘 주므로 이 자리는 평소 안 보이지만, 안 주는 부르는 쪽이 생기면 모델이 만든 것이
+    전부 `FIGURE` 라는 이름을 갖게 된다. 타입 이름은 저장되는 식별자다.
+  */
+  it('타입을 안 주면 FIGURE 로 나간다 — 조용히 빈 이름을 보내지 않는다', async () => {
+    const client = stubClient([candidate()])
+    setDefaultAIClient(client)
+
+    await proposeFigure({ prompt: '무언가', palette: PALETTE })
+
+    expect(firstAsk(client)).toContain('type "FIGURE"')
+  })
+
+  it('새로 만드는 요청이면 타입 이름이 나가고 고치라는 말은 안 나간다', async () => {
+    const client = stubClient([candidate()])
+    setDefaultAIClient(client)
+
+    await proposeFigure({ prompt: '교반기', palette: PALETTE, type: 'MIXER' })
+
+    const ask = firstAsk(client)
+    expect(ask).toContain('type "MIXER"')
+    expect(ask).not.toContain('Revise this existing figure')
+  })
+
+  /*
+    그림은 **비례를 보라고** 주는 것이지 표면 무늬를 베끼라고 주는 것이 아니다. 그 말이 빠지면
+    모델이 사진의 로고·녹·글자까지 부품으로 만들려 들고, 로우폴리에서 그것은 부품 낭비다.
+  */
+  it('그림을 주면 비례를 보라는 말과 함께 나간다', async () => {
+    const client = stubClient([candidate()])
+    setDefaultAIClient(client)
+
+    await proposeFigure({
+      prompt: '이 설비',
+      palette: PALETTE,
+      type: 'MIXER',
+      image: { data: Buffer.from('89504e47', 'hex'), mediaType: 'image/png' }
+    })
+
+    const ask = firstAsk(client)
+    expect(ask).toMatch(/proportions and masses, not for surface detail/)
+    // 그림 자체도 실려야 한다 — 말만 나가고 그림이 빠지면 모델이 볼 것이 없다.
+    expect(ask).toContain('"type":"image"')
+  })
+})
+
+describe('모델이 JSON 을 못 낼 때', () => {
+  /*
+    어댑터가 던지는 경우다. 그것도 사유이므로 **돌려주고 다시 시킨다** — 던져 버리면 저작자는
+    「안 됐다」만 보고, 무엇이 문제였는지도 모델이 고칠 기회도 없다.
+  */
+  it('던진 사유를 돌려주고 다시 시킨다', async () => {
+    const client = stubClient([new Error('unterminated string'), candidate()])
+    setDefaultAIClient(client)
+
+    const result = await proposeFigure({ prompt: '교반기', palette: PALETTE, type: 'MIXER' })
+
+    expect(result.attempts).toBe(2)
+    expect(client.calls).toBe(2)
+
+    // 두 번째 요청에 그 사유가 실려야 한다.
+    const retry = JSON.stringify(client.sent[1])
+    expect(retry).toContain('unterminated string')
+    expect(retry).toMatch(/Answer with the JSON object only/)
+  })
+
+  it('세 번 다 던지면 못 만들었다고 말한다', async () => {
+    setDefaultAIClient(stubClient([new Error('a'), new Error('b'), new Error('c')]))
+
+    await expect(proposeFigure({ prompt: '교반기', palette: PALETTE, type: 'MIXER' })).rejects.toThrow(ProposeFailure)
+  })
+})
+
+describe('정책을 넘은 후보는 막지 않고 알린다', () => {
+  /*
+    형식의 두 갈래를 그대로 지킨다 — `errors` 는 막고 `violations` 는 알린다. 정책 위반으로
+    후보를 버리면 저작자가 판단할 기회가 없어진다. 랜드마크 설비 하나는 정교해도 되고, 그
+    대가가 숫자로 보이면 된다.
+  */
+  it('등급 한도를 넘겨도 후보로 오고 위반이 함께 온다', async () => {
+    const many = Array.from({ length: PART_LIMIT.S + 1 }, (_, at) => ({
+      name: `part-${at}`,
+      primitive: PRIMITIVE_KINDS[0],
+      transform: { position: { x: at * 10, y: 0, z: 0 }, size: { x: 20, y: 20, z: 20 } },
+      material: { token: PALETTE[0] }
+    }))
+    setDefaultAIClient(stubClient([candidate({ detailLevel: 'S', parts: many })]))
+
+    const result = await proposeFigure({ prompt: '단순한 것', palette: PALETTE, type: 'MIXER' })
+
+    expect(result.source.parts).toHaveLength(PART_LIMIT.S + 1)
+    expect(result.violations.map(one => one.code)).toContain('too-many-parts')
+  })
+})

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

@@ -4,7 +4,9 @@ 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'
+import { FigureHistory } from './figure-history.js'
+import { inspectSource } from './figure-gate.js'
+import { FigureInspection, FigureList } from './figure-type.js'
 
 @Resolver(Figure)
 export class FigureQuery {
@@ -45,6 +47,66 @@ export class FigureQuery {
    *
    * `state` 로 걸러지지 않는다 — `draft` 인 Figure 의 이름도 이미 점유된 것이다.
    */
+  /**
+   * 발행된 판들 — 최근 것부터.
+   *
+   * 저작 중 저장은 여기 없다. 판본은 발행에서만 생기므로(`releaseFigure`), 이 목록이 곧
+   * 「이 도형이 몇 번 약속되었나」다.
+   */
+  @Directive('@privilege(category: "figure", privilege: "query", domainOwnerGranted: true)')
+  @Query(returns => [FigureHistory], { description: 'Released versions of a figure, newest first.' })
+  async figureVersions(@Arg('id') id: string, @Ctx() context: ResolverContext): Promise<FigureHistory[]> {
+    const { domain } = context.state
+
+    return await getRepository(FigureHistory).find({
+      where: { domain: { id: In([domain.id, domain.parentId].filter(Boolean)) }, originalId: id },
+      relations: ['updater'],
+      order: { version: 'DESC' },
+      take: 10
+    })
+  }
+
+  /**
+   * 지금 소비처가 쓰는 판.
+   *
+   * 도형의 현재 정본은 저작 중일 수 있다(초안). 배치된 것이 보는 것은 **마지막으로 발행된 판**이고,
+   * 그것을 이 자리가 답한다.
+   */
+  @Directive('@privilege(category: "figure", privilege: "query", domainOwnerGranted: true)')
+  @Query(returns => FigureHistory, { nullable: true, description: 'The most recently released version of a figure.' })
+  async figureReleased(@Arg('id') id: string, @Ctx() context: ResolverContext): Promise<FigureHistory> {
+    const { domain } = context.state
+
+    return await getRepository(FigureHistory).findOne({
+      where: { domain: { id: In([domain.id, domain.parentId].filter(Boolean)) }, originalId: id },
+      order: { version: 'DESC' }
+    })
+  }
+
+  /**
+   * 발행해도 되나 — **누르기 전에** 묻는 자리.
+   *
+   * 판정은 `figure-gate.ts` 가 하고 이 자리는 정본을 꺼내 넘긴다. 같은 판정을 `releaseFigure` 도
+   * 부른다 — 화면이 물어 보고 통과했더라도 그 사이에 정본이 바뀌었을 수 있으므로, 막는 것은 언제나
+   * 뮤테이션이다. 이 질의는 **이유를 미리 보여 주기 위한 것**이고 허가증이 아니다.
+   */
+  @Directive('@privilege(category: "figure", privilege: "query", domainOwnerGranted: true)')
+  @Query(returns => FigureInspection, { description: 'Whether a figure may be released, with the reasons.' })
+  async inspectFigure(@Arg('id') id: string, @Ctx() context: ResolverContext): Promise<FigureInspection> {
+    const { domain } = context.state
+
+    const figure = await getRepository(Figure).findOne({
+      where: { domain: { id: In([domain.id, domain.parentId].filter(Boolean)) }, id },
+      select: { id: true, source: true }
+    })
+
+    if (!figure) {
+      throw new Error(`Figure ${id} 를 찾을 수 없다`)
+    }
+
+    return inspectSource(figure.source)
+  }
+
   @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[]> {