@things-factory/figure-service 10.1.3 → 10.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/figure-service",
-  "version": "10.1.3",
+  "version": "10.1.6",
   "publishConfig": {
     "access": "public",
     "@things-factory:registry": "https://registry.npmjs.org"
@@ -23,11 +23,14 @@
     "migration:create": "node ../../node_modules/typeorm/cli.js migration:create ./server/migrations/migration"
   },
   "dependencies": {
-    "@hatiolab/figure-model": "^0.1.12",
-    "@things-factory/ai-client-base": "^10.1.3",
-    "@things-factory/auth-base": "^10.1.3",
+    "@hatiolab/figure-model": "^0.1.15",
+    "@operato/typeorm-history": "^10.0.0",
+    "@things-factory/ai-client-base": "^10.1.6",
+    "@things-factory/auth-base": "^10.1.6",
     "@things-factory/env": "^10.1.3",
-    "graphql-upload": "^15.0.2"
+    "@things-factory/shell": "^10.1.4",
+    "graphql-upload": "^15.0.2",
+    "koa-router": "^7.4.0"
   },
-  "gitHead": "8407b1e9d1f47f6676af144d4a33c8ac01cb49c4"
+  "gitHead": "963aeb9ac470be5aea05bb5842a0a92afcab6036"
 }

package/server/index.ts

@@ -1,2 +1,15 @@
+import './routes.js'
+
+/*
+ * 저작 도구를 어시스턴트 레지스트리에 등록한다.
+ *
+ * 이 패키지가 적재되면 대화면(도크)이 저작 중인 Figure 의 정본·비용·발행 판정을 읽고 후보를
+ * 요청할 수 있다. 능력을 복제하지 않고 figure-service 가 이미 가진 진입점을 투영한다 —
+ * 노출 범위는 대화면이 `toolCategories` 로 고른다(twin-ai · board-import 와 같은 방식).
+ */
+import { registerFigureToolCategories } from './service/figure/figure-tools.js'
+registerFigureToolCategories()
+
 export * from './service/index.js'
 export * from './migrations/index.js'
+export { registerFigureToolCategories } from './service/figure/figure-tools.js'

package/server/routers/figure-thumbnail-router.ts

@@ -0,0 +1,110 @@
+import Router from 'koa-router'
+import { In } from 'typeorm'
+
+import { checkPermission } from '@things-factory/auth-base'
+import { getRepository } from '@things-factory/shell'
+
+import { Figure } from '../service/figure/figure.js'
+
+/**
+ * 썸네일을 **그림으로** 내보내는 길.
+ *
+ * ## 왜 필요한가
+ *
+ * 썸네일은 base64 문자열로 칸에 들어 있다(`Board.thumbnail` 과 같은 방식). 그것을 목록 질의가
+ * 함께 실어 오면 카탈로그를 열 때마다 그림 전부가 JSON 안에 담겨 다시 온다 — data URL 은
+ * 브라우저가 캐시할 수 없다. [확인함] 표본 14개에 227KB, 한 장 최대 20KB.
+ *
+ * 그림으로 내보내면 브라우저가 캐시하고, 부르는 쪽이 `?v=thumbnailUpdatedAt` 을 붙이므로 그림이
+ * 다시 만들어진 것만 다시 받는다. 목록 질의에서는 `thumbnail` 을 아예 고르지 않는다.
+ *
+ * ## board 를 베끼면서 고친 것 셋
+ *
+ * `standalone-board-service-router` 의 `/thumbnail/:id` 가 본이지만 그대로 두면 안 되는 것들이 있다.
+ *
+ *   1. **길 이름이 겹친다.** 이 앱은 board 도 함께 싣는다(메뉴가 board-ui 를 끌어온다).
+ *      `/thumbnail/:id` 로 두면 먼저 등록된 쪽이 이기고, 남의 표에서 id 를 찾아 404 를 낸다.
+ *   2. **행 전체를 읽는다.** board 는 `findOneBy` 로 행을 다 읽는다. figure 행에는 정본(`source`)이
+ *      붙어 있어, 그림 한 장에 정본까지 읽게 된다. 필요한 칸만 고른다.
+ *   3. **png 로 못 박는다.** figure 썸네일은 webp 다(모델러가 그렇게 만든다). data URL 이 스스로
+ *      말하는 형식을 쓴다 — 못 박으면 브라우저가 확장자와 다른 바이트를 받는다.
+ */
+export const figureThumbnailRouter = new Router()
+
+/** `data:image/webp;base64,....` → 형식과 바이트. 아니면 undefined. */
+function decodeDataUrl(dataUrl: string): { type: string; buffer: Buffer } | undefined {
+  const matched = /^data:([^;,]+);base64,(.*)$/s.exec(dataUrl)
+  if (!matched) {
+    return undefined
+  }
+
+  return { type: matched[1], buffer: Buffer.from(matched[2], 'base64') }
+}
+
+figureThumbnailRouter.get('/figure-thumbnail/:id', async (context, next) => {
+  const { domain, user, unsafeIP, prohibitedPrivileges } = context.state
+
+  /*
+    **질의와 같은 문을 쓴다.**
+
+    `User.hasPrivilege('query','figure',…)` 만 보면 안 된다 — figure 질의는
+    `@privilege(category: "figure", privilege: "query", domainOwnerGranted: true)` 로 선언되어 있고,
+    도메인 소유자는 `figure:query` 권한 줄이 없어도 통과한다. 그 허용을 여기서 빼면 목록은 보이는데
+    그림만 403 이 되어, 화면은 「그림이 아직 없다」고 거짓말한다. [확인함] 실제로 카드 14장이 전부
+    403 이었다.
+
+    조건을 손으로 다시 적지 않고 지시자가 쓰는 함수를 그대로 쓴다. 선언이 바뀌면 여기도 함께 바뀐다.
+  */
+  const allowed = await checkPermission(
+    { category: 'figure', privilege: 'query', owner: true },
+    user,
+    domain,
+    unsafeIP,
+    prohibitedPrivileges
+  )
+
+  if (!allowed) {
+    context.status = 403
+    return
+  }
+
+  const { id } = context.params
+
+  /*
+    읽기는 부모 도메인까지 본다 — `figure` 질의와 같은 범위다. 물려받은 형상을 목록에는 보여 주고
+    그림만 404 를 내면, 화면은 「그림이 아직 없다」고 거짓말하게 된다.
+  */
+  const found = await getRepository(Figure).findOne({
+    where: { domain: { id: In([domain.id, domain.parentId].filter(Boolean)) }, id },
+    select: { id: true, thumbnail: true, thumbnailUpdatedAt: true }
+  })
+
+  const decoded = found?.thumbnail ? decodeDataUrl(found.thumbnail) : undefined
+
+  if (!decoded) {
+    context.status = 404
+    return
+  }
+
+  /*
+    **개인 캐시만 허락한다.** 이 그림은 권한을 본 뒤에 내주는 것이므로 공용 캐시(프록시)에 남으면
+    안 된다. 부르는 쪽이 `?v=` 로 판을 가리므로 오래 두어도 낡은 그림이 남지 않고, `v` 없이 부른
+    경우를 위해 시각을 함께 실어 다시 물어볼 수 있게 한다.
+  */
+  const stamp = found!.thumbnailUpdatedAt
+
+  context.type = decoded.type
+  context.set('Cache-Control', 'private, max-age=31536000')
+  if (stamp) {
+    context.set('Last-Modified', new Date(stamp).toUTCString())
+    context.set('ETag', `"${new Date(stamp).getTime()}"`)
+
+    /* 브라우저가 가진 것이 아직 그것이면 바이트를 보내지 않는다. */
+    if (context.fresh) {
+      context.status = 304
+      return
+    }
+  }
+
+  context.body = decoded.buffer
+})

package/server/routes.ts

@@ -0,0 +1,24 @@
+import { config } from '@things-factory/env'
+import { getRoutePrefixForDomainType } from '@things-factory/shell'
+
+import { figureThumbnailRouter } from './routers/figure-thumbnail-router.js'
+
+/**
+ * 도메인 경로가 주소에 들어가는 배치인가.
+ *
+ * `subdomain` 설정이 있으면 도메인은 호스트 이름으로 갈리므로 경로에 도메인이 없다. 없으면
+ * `/domain/{subdomain}/...` 로 갈린다 — board-service 가 같은 판단을 같은 방식으로 한다.
+ */
+const isPathBaseDomain = !config.get('subdomain')
+
+process.on('bootstrap-module-domain-private-route' as any, (app, domainPrivateRouter) => {
+  if (isPathBaseDomain) {
+    domainPrivateRouter.use(
+      `/${getRoutePrefixForDomainType()}/:domain`,
+      figureThumbnailRouter.routes(),
+      figureThumbnailRouter.allowedMethods()
+    )
+  } else {
+    domainPrivateRouter.use('', figureThumbnailRouter.routes(), figureThumbnailRouter.allowedMethods())
+  }
+})

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-gate.ts

@@ -0,0 +1,119 @@
+import { compile, sizingReport, validate } from '@hatiolab/figure-model'
+import type { FigureSource } from '@hatiolab/figure-model'
+
+/**
+ * 발행해도 되나 — **서버가 판정한다.**
+ *
+ * ## 왜 서버인가
+ *
+ * 이 검사는 브라우저 하네스에만 있었다(`test/browser/check-figure-scaling.mjs`). 사람이 돌릴 때만
+ * 돌았고, 발행 경로에는 아무 검사도 없었다 — 형식만 맞으면 무엇이든 발행되었다. 발행은 소비처에게
+ * 하는 약속이므로, 그 약속을 지킬 수 있는지는 약속하는 자리가 재야 한다.
+ *
+ * ## 무엇을 막고 무엇을 알리나
+ *
+ * 판정은 `figure-model` 의 `gate.ts` 가 이미 문서로 정해 두었다. 여기서 새로 정하지 않는다.
+ *
+ *   sizing-splits   크기를 바꾸면 조각이 갈라진다   **막는다**
+ *   sizing-loose    1배에서 이미 여러 조각이다      알린다
+ *   violations      형식이 권하지 않는 것          알린다 (저장 때 이미 보여 준 것들)
+ *
+ * 갈라짐을 막는 이유는 사람 눈에 「부서졌다」로 보이기 때문이다 — 시그널타워를 3배로 세우니 램프가
+ * 기둥 위 공중에 떴던 그것이고, 앵커 규칙이 생긴 이유다. 소비처가 형상을 늘려 쓰는 것은 막을 수
+ * 없으니(그것이 이 형식의 값이다), 늘려도 견디는지를 발행 전에 본다.
+ *
+ * ## 재 본 값
+ *
+ * [확인함] 2026-09-09 · 표본 15개(시드 14 + 저작 1)
+ *   형식 오류 0 · 1배 분리 0 · **갈라짐 1**(MIXER, z·y-z 조합) · 조용함 14
+ *
+ * 게이트가 벽이 아니라는 뜻이다. 열넷은 그대로 발행되고, 하나는 고칠 것이 있다.
+ */
+
+/** 게이트가 낸 한 가지. `blocking` 이 참이면 발행이 안 된다. */
+export interface GateFinding {
+  code: string
+  message: string
+  /**
+   * **왜 그것이 문제인가.** 잰 것만 보여 주면 읽는 사람이 「그래서?」에서 멈춘다 — 화면에
+   * 「1 조각이 2 조각으로 갈라진다」만 떴을 때 실제로 그랬다.
+   */
+  why?: string
+  /** **무엇을 바꾸면 되나.** 부품 이름과 값으로. 형식이 만든 문장을 그대로 옮긴다. */
+  how?: string
+  /** 어디를 가리키나 — 갈라짐은 갈라진 부품 이름들, 형식 위반은 정본 안의 경로. */
+  at?: string
+  blocking: boolean
+}
+
+export interface Inspection {
+  findings: GateFinding[]
+  /** 막는 것이 하나라도 있나. 화면이 이것으로 단추를 잠근다. */
+  blocked: boolean
+}
+
+/**
+ * 정본 하나를 판정한다.
+ *
+ * 정본이 없거나(아직 저장 전) JSON 이 아니면 **막는다** — 발행할 대상이 없는 것이다. 그 경우를
+ * 조용히 통과시키면 빈 것이 발행된다.
+ */
+export function inspectSource(sourceJson?: string | null): Inspection {
+  if (!sourceJson) {
+    return {
+      blocked: true,
+      findings: [
+        {
+          code: 'no-source',
+          message: '저장된 정본이 없다. 저장하면 발행할 수 있다',
+          blocking: true
+        }
+      ]
+    }
+  }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(sourceJson)
+  } catch (e) {
+    return {
+      blocked: true,
+      findings: [{ code: 'source-not-json', message: `정본이 JSON 이 아니다: ${(e as Error).message}`, blocking: true }]
+    }
+  }
+
+  const result = validate(parsed)
+  const findings: GateFinding[] = []
+
+  /*
+    형식 오류는 **저장을 통과할 수 없다**(`parseSource` 가 거절한다). 그래도 여기서 다시 보는 이유는,
+    이 판정이 저장 경로와 독립이어야 하기 때문이다 — 옛 정본이 남아 있거나 형식이 엄해진 뒤라면
+    저장 때는 맞았던 것이 지금은 틀릴 수 있다. 그때 발행이 통과하면 안 된다.
+  */
+  for (const error of result.errors) {
+    findings.push({ code: error.code, message: error.message, at: error.path, blocking: true })
+  }
+
+  for (const violation of result.violations) {
+    findings.push({ code: violation.code, message: violation.message, blocking: false })
+  }
+
+  if (result.errors.length === 0) {
+    const report = sizingReport(compile(parsed as FigureSource))
+
+    for (const finding of report.findings) {
+      findings.push({
+        code: finding.code,
+        message: finding.message,
+        /* 왜·어떻게는 형식이 소유한다. 서버가 다시 쓰면 두 벌이 되고 곧 어긋난다. */
+        why: finding.why,
+        how: finding.how,
+        /* 숫자가 아니라 자리를 말한다 — 어느 부품들이 갈라져 나왔나. */
+        at: finding.clumps.map(clump => [...clump].sort().join('+')).join(' | ') || undefined,
+        blocking: finding.code === 'sizing-splits'
+      })
+    }
+  }
+
+  return { findings, blocked: findings.some(finding => finding.blocking) }
+}

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
+}