@things-factory/figure-service 10.1.3 → 10.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/figure-service",
-  "version": "10.1.3",
+  "version": "10.1.4",
   "publishConfig": {
     "access": "public",
     "@things-factory:registry": "https://registry.npmjs.org"
@@ -24,10 +24,11 @@
   },
   "dependencies": {
     "@hatiolab/figure-model": "^0.1.12",
+    "@operato/typeorm-history": "^10.0.0",
     "@things-factory/ai-client-base": "^10.1.3",
-    "@things-factory/auth-base": "^10.1.3",
+    "@things-factory/auth-base": "^10.1.4",
     "@things-factory/env": "^10.1.3",
     "graphql-upload": "^15.0.2"
   },
-  "gitHead": "8407b1e9d1f47f6676af144d4a33c8ac01cb49c4"
+  "gitHead": "c653a2967daa76b3828f1eb7f4eb18934263d4b8"
 }

package/server/service/figure/event-subscriber.ts

@@ -0,0 +1,49 @@
+import { EventSubscriber } from 'typeorm'
+
+import { HistoryEntitySubscriber } from '@operato/typeorm-history'
+
+import { Figure } from './figure.js'
+import { FigureHistory } from './figure-history.js'
+
+/**
+ * 판본을 남긴다 — **발행된 저장에만.**
+ *
+ * `@operato/typeorm-history` 는 원래 모든 저장을 베낀다. 그런데 도형은 저작 중에 수십 번 저장되고,
+ * 그 전부를 남기면 판본 목록이 「내가 오늘 몇 번 눌렀나」가 된다. 사람이 판이라고 부르는 것은
+ * **발행한 것**이므로 그때만 베낀다. board 가 같은 규칙으로 돈다(`board-service` 의 같은 이름 파일).
+ *
+ * 발행 메모는 Figure 의 칸이 아니다. `releaseFigure` 가 저장할 엔티티에 `__releaseComment` 로 얹어
+ * 두면 여기서 판본의 `comment` 로 옮긴다 — 메모는 그 판의 것이지 도형의 것이 아니다.
+ */
+@EventSubscriber()
+export class FigureHistoryEntitySubscriber extends HistoryEntitySubscriber<Figure, FigureHistory> {
+  public get entity() {
+    return Figure
+  }
+
+  public get historyEntity() {
+    return FigureHistory
+  }
+
+  public beforeInsertHistory(history: FigureHistory, entity: Figure): FigureHistory {
+    ;(history as any).comment = (entity as any).__releaseComment ?? null
+    return history
+  }
+
+  public beforeUpdateHistory(history: FigureHistory, entity: Figure): FigureHistory {
+    ;(history as any).comment = (entity as any).__releaseComment ?? null
+    return history
+  }
+
+  public async afterInsert(event: any): Promise<void> {
+    if (event.entity?.state == 'released') {
+      await super.afterInsert(event)
+    }
+  }
+
+  public async afterUpdate(event: any): Promise<void> {
+    if (event.entity?.state == 'released') {
+      await super.afterUpdate(event)
+    }
+  }
+}

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

@@ -0,0 +1,130 @@
+import { Field, ID, ObjectType, Float, Int } from 'type-graphql'
+import { Column, Entity, Index, ManyToOne, PrimaryGeneratedColumn, RelationId } from 'typeorm'
+
+import {
+  HistoryActionColumn,
+  HistoryActionType,
+  HistoryEntityInterface,
+  HistoryOriginalIdColumn
+} from '@operato/typeorm-history'
+import { User } from '@things-factory/auth-base'
+import { Domain, longTextColumn } from '@things-factory/shell'
+
+import { Figure } from './figure.js'
+
+/**
+ * 발행된 판 하나 — **발행할 때만 남는다.**
+ *
+ * 저작 중 저장은 여기 오지 않는다. 스냅샷을 뜨는 subscriber 가 `state === 'released'` 인 저장에만
+ * 움직인다(`event-subscriber.ts`) — board 가 같은 규칙으로 돈다.
+ *
+ * ## 왜 통째로 베끼나
+ *
+ * 판을 되세우려면 그때의 정본만으로는 모자란다. 이름·분류·그림·비용까지 함께 있어야 「그 판이
+ * 무엇이었나」를 보여 주고 되돌릴 수 있다. 파생값(점수·삼각형·묶음)도 같이 둔다 — 다시 계산하면
+ * 형식이 바뀐 오늘의 값이 나오고, 그것은 그 판의 값이 아니다.
+ */
+@Entity()
+@Index('ix_figure_history_0', (history: FigureHistory) => [history.originalId, history.version], { unique: true })
+@ObjectType({ description: 'A released version of a figure — one row per release.' })
+export class FigureHistory implements HistoryEntityInterface<Figure> {
+  @PrimaryGeneratedColumn('uuid')
+  @Field(type => ID, { description: 'Unique identifier for this history record.' })
+  readonly id: string
+
+  @Column({ nullable: true, default: 1 })
+  @Field(type => Int, { nullable: true, description: 'The published version number this record holds.' })
+  version?: number = 1
+
+  @ManyToOne(type => Domain)
+  @Field(type => Domain, { nullable: true, description: 'The domain the figure belonged to.' })
+  domain?: Domain
+
+  @RelationId((history: FigureHistory) => history.domain)
+  domainId?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'The stored identifier of the figure. It never changes.' })
+  type?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'The display name at this version.' })
+  name?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'The description at this version.' })
+  description?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'The classification code at this version.' })
+  category?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'The lifecycle state recorded with this version.' })
+  state?: 'draft' | 'released'
+
+  @Column({ nullable: true, ...longTextColumn() })
+  @Field({ nullable: true, description: 'The canonical FigureSource JSON at this version.' })
+  source?: string
+
+  @Column({ nullable: true, ...longTextColumn() })
+  @Field({ nullable: true, description: 'The master-data field definition at this version.' })
+  properties?: string
+
+  @Column({ nullable: true, ...longTextColumn() })
+  @Field({ nullable: true, description: 'The thumbnail as it looked at this version.' })
+  thumbnail?: string
+
+  /*
+   * 그때의 비용이다. 오늘 다시 계산하면 오늘의 형식으로 나온다 — 그 판을 설명하지 못한다.
+   */
+  @Column({ type: 'float', nullable: true })
+  @Field(type => Float, { nullable: true, description: 'Reuse score as computed at this version.' })
+  score?: number
+
+  @Column({ nullable: true })
+  @Field(type => Int, { nullable: true, description: 'Triangle count at this version.' })
+  triangles?: number
+
+  @Column({ nullable: true })
+  @Field(type => Int, { nullable: true, description: 'Material group count at this version.' })
+  groups?: number
+
+  @Column({ nullable: true, ...longTextColumn() })
+  @Field({ nullable: true, description: 'The note left when this version was released.' })
+  comment?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'When the original figure was created.' })
+  createdAt?: Date
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'When the figure was saved at this version.' })
+  updatedAt?: Date
+
+  @ManyToOne(type => User, { nullable: true })
+  @Field(type => User, { nullable: true, description: 'Who created the original figure.' })
+  creator?: User
+
+  @RelationId((history: FigureHistory) => history.creator)
+  creatorId?: string
+
+  @ManyToOne(type => User, { nullable: true })
+  @Field(type => User, { nullable: true, description: 'Who released this version.' })
+  updater?: User
+
+  @RelationId((history: FigureHistory) => history.updater)
+  updaterId?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'When the original figure was deleted, if it was.' })
+  deletedAt?: Date
+
+  @HistoryOriginalIdColumn()
+  @Field({ description: 'The id of the figure this version belongs to.' })
+  public originalId!: string
+
+  @HistoryActionColumn({ nullable: false, type: 'varchar', length: 10 })
+  @Field(type => String, { description: 'What produced this record (created · updated · deleted).' })
+  public action!: HistoryActionType
+}

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

@@ -4,6 +4,7 @@ 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 { parseSource } from './figure-source.js'
@@ -76,17 +77,172 @@ 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** 이다. 되돌리기로 옛 판이 현재가 되어도
+   * 다음 발행이 이미 쓴 번호를 다시 쓰지 않는다.
+   */
+  @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}' 은 이미 발행되어 있다. 고쳐서 다시 내려면 초안으로 되돌린 뒤 발행한다`)
+    }
+
+    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-query.ts

@@ -4,6 +4,7 @@ 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 { FigureHistory } from './figure-history.js'
 import { FigureList } from './figure-type.js'
 
 @Resolver(Figure)
@@ -45,6 +46,42 @@ 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' }
+    })
+  }
+
   @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[]> {

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

@@ -58,8 +58,12 @@ export class FigurePatch {
   @Field({ nullable: true, description: 'The new master-data field definition.' })
   properties?: string
 
-  @Field({ nullable: true, description: 'The new lifecycle state.' })
-  state?: 'draft' | 'released'
+  /*
+    `state` 는 여기 없다 — **상태는 저장이 정하지 않는다.**
+
+    발행은 `releaseFigure` 가 한다. 저장으로 상태를 바꿀 수 있게 두면 발행된 판을 덮어쓰면서 같은
+    판 번호로 판본을 또 뜨게 되고(유니크 충돌), 무엇이 약속된 판인지도 흐려진다. board 도 같다.
+  */
 
   @Field({ nullable: true, description: 'A base64 encoded thumbnail image.' })
   thumbnail?: string

package/server/service/figure/figure.ts

@@ -45,9 +45,21 @@ export class Figure {
   @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
+  /**
+   * 발행된 판의 번호 — **발행할 때만 올라간다.**
+   *
+   * 저장 횟수가 아니다. 저작 중에는 몇 번을 고쳐 저장하든 그대로이고, `draft` 가 `released` 가
+   * 되는 순간에만 하나 오른다. 소비처가 「몇 번째 판을 쓰고 있나」를 이 값으로 말한다.
+   *
+   * 한 번도 발행되지 않았으면 **0** 이다. 1 로 시작하면 아직 아무에게도 약속하지 않은 초안이
+   * 첫 판인 것처럼 보인다.
+   */
+  @Column({ nullable: true, default: 0 })
+  @Field(type => Int, {
+    nullable: true,
+    description: 'Published version. Raised when the figure is released, not when it is saved. 0 means never released.'
+  })
+  version?: number = 0
 
   @ManyToOne(type => Domain)
   @Field(type => Domain, { nullable: true, description: 'The domain this figure belongs to.' })

package/server/service/figure/index.ts

@@ -1,6 +1,9 @@
 import { Figure } from './figure.js'
+import { FigureHistory } from './figure-history.js'
 import { FigureQuery } from './figure-query.js'
 import { FigureMutation } from './figure-mutation.js'
+import { FigureHistoryEntitySubscriber } from './event-subscriber.js'
 
-export const entities = [Figure]
+export const entities = [Figure, FigureHistory]
 export const resolvers = [FigureQuery, FigureMutation]
+export const subscribers = [FigureHistoryEntitySubscriber]

package/server/service/index.ts

@@ -2,9 +2,30 @@
 export * from './figure/figure.js'
 export * from './figure/figure-type.js'
 export * from './figure/figure-source.js'
+export * from './figure/figure-history.js'
 
 // Entities, resolvers
-import { entities as FigureEntities, resolvers as FigureResolvers } from './figure/index.js'
+import {
+  entities as FigureEntities,
+  resolvers as FigureResolvers,
+  subscribers as FigureSubscribers
+} from './figure/index.js'
 
 export const entities = [...FigureEntities]
-export const resolvers = [...FigureResolvers]
+
+/* 판본 스냅샷을 뜨는 구독자. 셸이 이 이름으로 모아 TypeORM 에 등록한다(board-service 와 같다). */
+export const subscribers = [...FigureSubscribers]
+
+/*
+ * The shell reads `schema.resolverClasses` from every module — nothing else.
+ *
+ *     shell/dist-server/schema.js   orderedModuleNames.map(dep => loader(dep).schema)
+ *
+ * This module used to export the classes as a bare `resolvers` array, a name the shell never looks
+ * at. The table was migrated and the resolver classes were compiled, and still every query failed
+ * with `Cannot query field "figures" on type "Query"` — the field was not in the schema at all.
+ * board-service, ops-master and font-base all export the shape below.
+ */
+export const schema = {
+  resolverClasses: [...FigureResolvers]
+}