@things-factory/figure-service 10.1.110 → 10.1.112

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/figure-service",
-  "version": "10.1.110",
+  "version": "10.1.112",
   "publishConfig": {
     "access": "public",
     "@things-factory:registry": "https://registry.npmjs.org"
@@ -25,15 +25,16 @@
     "test:templates": "node --test scripts/templates.test.mts"
   },
   "dependencies": {
-    "@hatiolab/figure-model": "^0.2.8",
+    "@hatiolab/figure-model": "^0.2.10",
     "@operato/typeorm-history": "^10.0.0",
     "@things-factory/ai-client-base": "^10.1.81",
-    "@things-factory/auth-base": "^10.1.107",
+    "@things-factory/attachment-base": "^10.1.112",
+    "@things-factory/auth-base": "^10.1.111",
     "@things-factory/env": "^10.1.20",
     "@things-factory/shell": "^10.1.106",
     "graphql-scalars": "^1.22.4",
     "graphql-upload": "^15.0.2",
     "koa-router": "^7.4.0"
   },
-  "gitHead": "b68feb6eccbef44af2a6365f384bd852dd70a8f9"
+  "gitHead": "e300d1b60b98ccb80380afe8df6d2807b1bcff91"
 }

package/server/index.ts

@@ -20,6 +20,21 @@ process.on('bootstrap-module-start' as any, () => {
   console.log(`[figure-service:bootstrap] recipe templates ${templates.length}${refused.length ? `, left out: ${refused.join(' | ')}` : ''}`)
 })
 
+/*
+ * The pictures an install kept as base64 move into attachment-base by their content, once, at start (ADR-0104 decision
+ * 6). In the boot's one line: it writes, and sqlite holds one runner. A failure is said and the server goes on.
+ */
+import { getDataSource, inBootTurn } from '@things-factory/shell'
+import { moveBase64Thumbnails } from './service/figure/figure-thumbnail-upgrade.js'
+process.on('bootstrap-module-start' as any, () => {
+  inBootTurn(() => moveBase64Thumbnails(getDataSource()))
+    .then(moved => {
+      const any = moved.filter(m => m.moved || m.kept)
+      if (any.length) console.log(`[figure-service:bootstrap] thumbnails moved: ${any.map(m => `${m.table} ${m.moved}${m.kept ? ` (kept as base64: ${m.kept})` : ''}`).join(', ')}`)
+    })
+    .catch(error => console.error(`[figure-service] 썸네일을 옮기지 못했다 — ${error?.message ?? error}`))
+})
+
 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

@@ -7,6 +7,7 @@ import { getRepository } from '@things-factory/shell'
 import { readFileSync } from 'fs'
 
 import { Figure } from '../service/figure/figure.js'
+import { thumbnailAttachmentOf, thumbnailFiles, type ThumbnailFiles } from '../service/figure/figure-thumbnail-store.js'
 import { recipeTemplates } from '../service/figure-recipe/figure-recipe-templates.js'
 
 /**
@@ -14,7 +15,7 @@ import { recipeTemplates } from '../service/figure-recipe/figure-recipe-template
  *
  * ## 왜 필요한가
  *
- * 썸네일은 base64 문자열로 칸에 들어 있다(`Board.thumbnail` 과 같은 방식). 그것을 목록 질의가
+ * 썸네일은 attachment-base 가 내용 해시로 갖는다(ADR-0104 결정 6). 옛날에는 base64 문자열로 칸에 있었고, 그것을 목록 질의가
  * 함께 실어 오면 카탈로그를 열 때마다 그림 전부가 JSON 안에 담겨 다시 온다 — data URL 은
  * 브라우저가 캐시할 수 없다. [확인함] 표본 14개에 227KB, 한 장 최대 20KB.
  *
@@ -29,21 +30,11 @@ import { recipeTemplates } from '../service/figure-recipe/figure-recipe-template
  *      `/thumbnail/:id` 로 두면 먼저 등록된 쪽이 이기고, 남의 표에서 id 를 찾아 404 를 낸다.
  *   2. **행 전체를 읽는다.** board 는 `findOneBy` 로 행을 다 읽는다. figure 행에는 정본(`source`)이
  *      붙어 있어, 그림 한 장에 정본까지 읽게 된다. 필요한 칸만 고른다.
- *   3. **png 로 못 박는다.** figure 썸네일은 webp 다(모델러가 그렇게 만든다). data URL 이 스스로
- *      말하는 형식을 쓴다 — 못 박으면 브라우저가 확장자와 다른 바이트를 받는다.
+ *   3. **png 로 못 박는다.** figure 썸네일은 webp 다(모델러가 그렇게 만든다). 저장할 때 data URL 이 스스로
+ *      말한 형식을 attachment 의 mimetype 으로 쓴다 — 못 박으면 브라우저가 확장자와 다른 바이트를 받는다.
  */
 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
 
@@ -71,46 +62,59 @@ figureThumbnailRouter.get('/figure-thumbnail/:id', async (context, next) => {
     return
   }
 
-  const { id } = context.params
+  await sendFigureThumbnail(context, next, context.params.id, domain)
+})
 
+/**
+ * The picture of a figure the caller may read, by its hash (ADR-0104 decision 6). Exported for tests, which give
+ * their own `files`.
+ */
+export async function sendFigureThumbnail(
+  context: any,
+  next: () => Promise<any>,
+  id: string,
+  domain: { id: string; parentId?: string },
+  files: ThumbnailFiles = thumbnailFiles()
+): Promise<void> {
   /*
     읽기는 부모 도메인까지 본다 — `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 }
+    relations: { domain: true },
+    select: { id: true, thumbnailHash: true, thumbnailUpdatedAt: true, domain: { id: true } }
   })
-
-  const decoded = found?.thumbnail ? decodeDataUrl(found.thumbnail) : undefined
-
-  if (!decoded) {
+  if (!found?.thumbnailHash) {
     context.status = 404
     return
   }
 
   /*
-    **개인 캐시만 허락한다.** 이 그림은 권한을 본 뒤에 내주는 것이므로 공용 캐시(프록시)에 남으면
-    안 된다. 부르는 쪽이 `?v=` 로 판을 가리므로 오래 두어도 낡은 그림이 남지 않고, `v` 없이 부른
-    경우를 위해 시각을 함께 실어 다시 물어볼 수 있게 한다.
+    그림은 **그 figure 의 도메인**에서 찾는다 — 묻는 도메인이 아니다(판정 조건 4). 해시가 같아도 다른 도메인의 행을
+    집지 않는다. 물려받은 figure 의 그림은 부모 도메인에 있다.
   */
-  const stamp = found!.thumbnailUpdatedAt
+  const picture = await thumbnailAttachmentOf({ getRepository }, found.domain!.id, found.thumbnailHash)
+  if (!picture) {
+    context.status = 404
+    return
+  }
 
-  context.type = decoded.type
+  /*
+    **개인 캐시만 허락한다.** 이 그림은 권한을 본 뒤에 내주는 것이므로 공용 캐시(프록시)에 남으면 안 된다 —
+    attachment 의 공개 경로가 쓰는 `public` 을 따라 쓰지 않는다(판정 조건 1). 같은 내용은 같은 해시이므로 ETag 가
+    곧 내용이다. 부르는 쪽이 `?v=` 로 판을 가리므로 오래 두어도 낡은 그림이 남지 않는다.
+  */
+  context.type = picture.mimetype
   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.set('ETag', `"${found.thumbnailHash}"`)
+  if (found.thumbnailUpdatedAt) context.set('Last-Modified', new Date(found.thumbnailUpdatedAt).toUTCString())
+  if (context.fresh) {
+    context.status = 304
+    return
   }
-
-  context.body = decoded.buffer
-})
+  await files.send(context, picture.path!, next)
+}
 
 /**
  * A recipe template's thumbnail (ADR-0095 amended): the file drawn from its model, served behind the same door as the

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

@@ -14,7 +14,8 @@ import { FigureHistory } from './figure-history.js'
  *
  * 발행 메모는 Figure 의 칸이 아니다. `releaseFigure` 가 저장할 엔티티에 `__releaseComment` 로 얹어
  * 두면 여기서 판본의 `comment` 로 옮긴다 — 메모는 그 판의 것이지 도형의 것이 아니다. 정본 형식
- * (`__releaseFormat`)과 직전 판에 견준 변경(`__releaseChanges`)도 같은 길로 옮긴다(ADR-0104).
+ * (`__releaseFormat`), 직전 판에 견준 변경(`__releaseChanges`), 발행 때 잰 값(`__releaseMetrics`)과
+ * 윗모습(`__releaseTopView`)도 같은 길로 옮긴다(ADR-0104).
  */
 /** What `releaseFigure` laid on the entity for this release, moved onto the history row. */
 function releaseRecordOnto(history: FigureHistory, entity: Figure): FigureHistory {
@@ -23,6 +24,8 @@ function releaseRecordOnto(history: FigureHistory, entity: Figure): FigureHistor
   history.assetFormat = e.__releaseFormat ?? null
   /* [] stays "[]" (nothing changed); null stays null (not compared). */
   history.changes = e.__releaseChanges == null ? null : JSON.stringify(e.__releaseChanges)
+  history.metrics = e.__releaseMetrics == null ? null : JSON.stringify(e.__releaseMetrics)
+  history.topView = e.__releaseTopView == null ? null : JSON.stringify(e.__releaseTopView)
   return history
 }
 

package/server/service/figure/figure-deprecation-db.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Retiring a figure and its names by language (ADR-0104 decision 6), on sqlite with the history subscriber on.
+ * A retired figure stays released and is served as before; retiring writes no history row.
+ */
+import type { DataSource } from 'typeorm'
+
+const { DataSource: TypeOrmDataSource } = require('typeorm')
+const shell = require('@things-factory/shell')
+const authBase = require('@things-factory/auth-base')
+const { createFigureAsset, addFigureBox, serializeFigureAsset, applyFigureAuthoring, proposeFigureOccupancy } = require('@hatiolab/figure-model')
+
+let dataSource: DataSource | null = null
+let Figure: any
+let FigureHistory: any
+let Subscriber: any
+let FigureMutation: any
+let assertNames: 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먼저 빌드할 것:\n  yarn workspace @things-factory/figure-service build:server`)
+  return require(resolved)
+}
+
+beforeAll(async () => {
+  Figure = loadCompiled('service/figure/figure').Figure
+  FigureHistory = loadCompiled('service/figure/figure-history').FigureHistory
+  Subscriber = loadCompiled('service/figure/event-subscriber').FigureHistoryEntitySubscriber
+  ;({ FigureMutation, assertNames } = loadCompiled('service/figure/figure-mutation'))
+  dataSource = new TypeOrmDataSource({
+    type: 'sqlite',
+    database: ':memory:',
+    synchronize: true,
+    dropSchema: true,
+    namingStrategy: new shell.NamingStrategy(),
+    entities: [...shell.entities, ...authBase.entities, Figure, FigureHistory],
+    subscribers: [Subscriber],
+    logging: false
+  })
+  await dataSource.initialize()
+})
+
+afterAll(async () => {
+  await dataSource?.destroy()
+  dataSource = null
+})
+
+const releasable = () => {
+  let a = addFigureBox(createFigureAsset('Mixer'), { id: 'body', size: { x: 100, y: 100, z: 100 }, position: { x: 0, y: 50, z: 0 } })
+  a = applyFigureAuthoring(a, { kind: 'attach', part: 'body', face: 'bottom', to: { plane: 'mounting-plane' } })
+  return serializeFigureAsset(applyFigureAuthoring(a, { kind: 'declare-occupancy', proposal: proposeFigureOccupancy(a, { over: 'range' }), placement: 'floor' }))
+}
+
+let seq = 0
+async function released(type: string) {
+  const name = `retire-${++seq}`
+  const domain = await dataSource!.getRepository(shell.Domain).save({ name, subdomain: name })
+  const context = { state: { domain, user: undefined, tx: dataSource!.manager } }
+  const figure = await dataSource!.getRepository(Figure).save({ type, name: 'mixer', source: releasable(), state: 'draft', version: 0, domain })
+  await new FigureMutation().releaseFigure(figure.id, 'one', context)
+  return { figure, context, domain }
+}
+const historyCount = (id: string) => dataSource!.getRepository(FigureHistory).count({ where: { originalId: id } })
+
+describe('retiring a figure', () => {
+  it('stays released, writes no history row, and names what to use instead', async () => {
+    const { figure, context, domain } = await released('OLD_MIXER')
+    await dataSource!.getRepository(Figure).save({ type: 'NEW_MIXER', name: 'new', source: releasable(), state: 'draft', version: 0, domain })
+    const retired = await new FigureMutation().setFigureDeprecation(figure.id, true, context, 'NEW_MIXER')
+    expect([retired.deprecated, retired.supersededBy, retired.state, retired.version]).toEqual([true, 'NEW_MIXER', 'released', 1])
+    expect(await historyCount(figure.id)).toBe(1)
+    const back = await new FigureMutation().setFigureDeprecation(figure.id, false, context, 'NEW_MIXER')
+    expect([back.deprecated, back.supersededBy, back.state]).toEqual([false, null, 'released'])
+    expect(await historyCount(figure.id)).toBe(1)
+  })
+
+  it('refuses a replacement that is not there, or itself', async () => {
+    const { figure, context } = await released('LONE_MIXER')
+    await expect(new FigureMutation().setFigureDeprecation(figure.id, true, context, 'NOWHERE')).rejects.toThrow(/NOWHERE/)
+    await expect(new FigureMutation().setFigureDeprecation(figure.id, true, context, 'LONE_MIXER')).rejects.toThrow(/자기 자신/)
+  })
+})
+
+describe('names by language', () => {
+  it('a language code to a name of 1-128 characters', () => {
+    expect(() => assertNames({ en: 'Mixer', 'zh-Hans': '搅拌机' })).not.toThrow()
+    expect(() => assertNames({ English: 'Mixer' })).toThrow(/English/)
+    expect(() => assertNames({ en: '' })).toThrow(/en/)
+    expect(() => assertNames({ en: 'x'.repeat(129) })).toThrow(/en/)
+    expect(() => assertNames(['en'])).toThrow()
+  })
+
+  it('kept on the figure and copied onto the release it goes out with', async () => {
+    const name = `names-${++seq}`
+    const domain = await dataSource!.getRepository(shell.Domain).save({ name, subdomain: name })
+    const context = { state: { domain, user: undefined, tx: dataSource!.manager } }
+    const figure = await dataSource!.getRepository(Figure).save({ type: 'NAMED', name: 'mixer', source: releasable(), state: 'draft', version: 0, domain })
+    await new FigureMutation().updateFigure(figure.id, { names: { en: 'Mixer', ko: '믹서' } }, context)
+    await new FigureMutation().releaseFigure(figure.id, 'one', context)
+    const [row] = await dataSource!.getRepository(FigureHistory).find({ where: { originalId: figure.id } })
+    expect(row.names).toEqual({ en: 'Mixer', ko: '믹서' })
+    await expect(new FigureMutation().updateFigure(figure.id, { names: { English: 'x' } }, context)).rejects.toThrow(/English/)
+  })
+})

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

@@ -330,7 +330,12 @@ describe('figure-format — 판을 알아보는 문', () => {
       return serializeFigureAsset(applyFigureAuthoring(asset, { kind: 'declare-occupancy', proposal: proposeFigureOccupancy(asset, { over: 'range' }), placement: 'floor' }))
     }
     it('a first release: its format, and nothing changed', () => {
-      expect(releaseRecordOf(serializeFigureAsset(figureAsset()))).toEqual({ format: 'figure-asset-1', changes: [] })
+      const record = releaseRecordOf(serializeFigureAsset(figureAsset()))
+      expect([record.format, record.changes]).toEqual(['figure-asset-1', []])
+      /* Not sized from the instance: nothing measured across sizes, only where its origin is. Its plan is its one body from above. */
+      expect(record.metrics).toEqual({ origin: { centred: true, off: [] } })
+      expect(record.topView.shapes.map(s => s.id)).toEqual(['body'])
+      expect(record.topView.size).toBeNull()
     })
     it('the same again changes nothing; a wider room is said and does not block', () => {
       const v1 = serializeFigureAsset(figureAsset())
@@ -349,4 +354,17 @@ describe('figure-format — 판을 알아보는 문', () => {
         for (const dict of [KO, EN]) for (const field of ['message', 'why']) expect(dict[`figure.gate.contract.${code}.${field}`]).toBeTruthy()
     })
   })
+
+  /* ADR-0104 decision 4: off the middle of its room is said at release, never refused. */
+  it('an origin off the middle of the room is a warning, and the release goes on', () => {
+    let asset = createFigureAsset('Door')
+    asset = addFigureBox(asset, { id: 'leaf', size: { x: 100, y: 200, z: 40 }, position: { x: 50, y: 100, z: 0 } })
+    asset = applyFigureAuthoring(asset, { kind: 'declare-occupancy', proposal: proposeFigureOccupancy(asset), placement: 'floor' })
+    const result = inspectSource(serializeFigureAsset(asset), null, undefined, 'DOOR')
+    const off = result.findings.find(f => f.code === 'origin-off-centre')!
+    expect(off.blocking).toBe(false)
+    expect(off.message).toMatch(/X 50 mm/)
+    expect(result.findings.filter(f => f.blocking).map(f => f.code)).not.toContain('origin-off-centre')
+    expect(inspectSource(serializeFigureAsset(figureAsset()), null, undefined, 'MIXER').findings.map(f => f.code)).not.toContain('origin-off-centre')
+  })
 })

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

@@ -3,8 +3,8 @@
  * board (`consumablePayloadOf`). The format is `figure-asset-1`, and the asset says so in its `version`; a source
  * that does not is refused by name, because a source the server cannot identify is one it must not save.
  */
-import { compileFigureAsset, inspectFigureAsset, isPlaceholderType, parseFigureAsset, serializeFigureAsset, figureContractChanges, figureCostOf, figureScoreOf } from '@hatiolab/figure-model'
-import type { FigureAsset, FigureContractChange, FigureContractError, FigureViolation } from '@hatiolab/figure-model'
+import { compileFigureAsset, inspectFigureAsset, isPlaceholderType, parseFigureAsset, serializeFigureAsset, figureContractChanges, figureCostOf, figureOriginCentredOf, figureReleaseMetricsOf, figureScoreOf, figureTopViewOf } from '@hatiolab/figure-model'
+import type { FigureAsset, FigureContractChange, FigureContractError, FigureReleaseMetrics, FigureTopView, FigureViolation } from '@hatiolab/figure-model'
 
 import type { FigureFinding } from './figure-type.js'
 
@@ -280,6 +280,21 @@ export function inspectSource(
       blocking: false
     })
   }
+  /*
+    Said, never refused (ADR-0104 decision 4): the origin is where the figure is fastened, and a door fastened at its
+    hinge is a right model. A drawing that places figures by the middle of their room reads this before it pins one.
+  */
+  const origin = figureOriginCentredOf(asset!)
+  if (origin && !origin.centred) {
+    const off = origin.off.map(o => `${o.axis.toUpperCase()} ${o.mm} mm`).join(', ')
+    findings.push({
+      code: 'origin-off-centre',
+      message: say('figure.gate.origin-off-centre.message', { off }, `The origin is off the middle of the declared room: ${off}.`),
+      why: say('figure.gate.origin-off-centre.why', {}, 'A drawing that places figures by the middle of their room puts this one that far from where it is drawn.'),
+      how: say('figure.gate.origin-off-centre.how', {}, 'Keep it when the figure is fastened there, as a door at its hinge. Move the origin to the middle to place it by its room.'),
+      blocking: false
+    })
+  }
   if (releasedJson) findings.push(...figureContractFindings(asset!, releasedJson, say))
   return { blocked: findings.some(finding => finding.blocking), findings }
 }
@@ -450,21 +465,25 @@ function figureContractWording(change: FigureContractChange, say: Say): Pick<Gat
 }
 
 /**
- * What a release records about itself (ADR-0104 decision 5): the format its asset is written in, and what changed
- * against the previous release -- the kernel's own comparison, kept as it was then so a consumer that pins releases
+ * What a release records about itself (ADR-0104 decision 5): the format its asset is written in, what it measured
+ * (its cost at its largest, whether resizing is stretching), its plan from above, and what changed against the previous release -- the kernel's own comparison, kept as it was then so a consumer that pins releases
  * reads it rather than computing it again. `[]` for a first release; `null` when the previous release could not be
  * read, which is a different fact from "nothing changed".
  */
-export function releaseRecordOf(sourceJson: string, releasedJson?: string | null): { format: string; changes: FigureContractChange[] | null } {
+export function releaseRecordOf(
+  sourceJson: string,
+  releasedJson?: string | null
+): { format: string; changes: FigureContractChange[] | null; metrics: FigureReleaseMetrics; topView: FigureTopView } {
   const asset = parseFigureAsset(sourceJson)
-  if (!releasedJson) return { format: asset.version, changes: [] }
+  const measured = { format: asset.version, metrics: figureReleaseMetricsOf(asset), topView: figureTopViewOf(asset, null) }
+  if (!releasedJson) return { ...measured, changes: [] }
   let before: FigureAsset
   try {
     before = parseFigureAsset(releasedJson)
   } catch {
-    return { format: asset.version, changes: null }
+    return { ...measured, changes: null }
   }
-  return { format: asset.version, changes: figureContractChanges(before, asset) }
+  return { ...measured, changes: figureContractChanges(before, asset) }
 }
 
 /**

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

@@ -1,4 +1,5 @@
 import { Field, ID, ObjectType, Float, Int } from 'type-graphql'
+import { GraphQLJSON } from 'graphql-scalars'
 import { Column, Entity, Index, ManyToOne, PrimaryGeneratedColumn, RelationId } from 'typeorm'
 
 import {
@@ -55,6 +56,10 @@ export class FigureHistory implements HistoryEntityInterface<Figure> {
   @Field({ nullable: true, description: 'The description at this version.' })
   description?: string
 
+  @Column('simple-json', { nullable: true, default: null })
+  @Field(type => GraphQLJSON, { nullable: true, description: 'Display names by language at this version.' })
+  names?: Record<string, string>
+
   @Column({ nullable: true })
   @Field({ nullable: true, description: 'The classification code at this version.' })
   category?: string
@@ -75,6 +80,15 @@ export class FigureHistory implements HistoryEntityInterface<Figure> {
   @Field({ nullable: true, description: 'The thumbnail as it looked at this version.' })
   thumbnail?: string
 
+  /*
+   * 그림의 내용 해시(SHA-256). 그림 자체는 attachment-base 가 갖고(refType `figure-thumbnail`, refBy 이 해시),
+   * `/figure-thumbnail/:id` 가 권한을 본 뒤 내준다(ADR-0104 결정 6). `thumbnail` 칸은 옛 base64 가 남은 행을
+   * 기동 때 옮기기 위한 칸이다 — 옮긴 뒤에는 비어 있고, 새 그림은 그 칸에 쓰지 않는다.
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'SHA-256 of the thumbnail picture; the picture is served by /figure-thumbnail/:id.' })
+  thumbnailHash?: string
+
   /*
    * 그때의 비용이다. 오늘 다시 계산하면 오늘의 형식으로 나온다 — 그 판을 설명하지 못한다.
    */
@@ -110,6 +124,21 @@ export class FigureHistory implements HistoryEntityInterface<Figure> {
   })
   changes?: string
 
+  @Column({ nullable: true, ...longTextColumn() })
+  @Field({
+    nullable: true,
+    description:
+      'What this version measured once, as JSON (figure-model figureReleaseMetricsOf): { atLargest?: { size, triangles, groups }, linear?: { scalable, parts, probe } }. Only for a figure that takes its size from the instance; {} otherwise.'
+  })
+  metrics?: string
+
+  @Column({ nullable: true, ...longTextColumn() })
+  @Field({
+    nullable: true,
+    description: 'The plan from above at the authored size, as JSON (figure-model figureTopViewOf): { shapes: [{ id, color, outline, holes, top, transparent }], size }.'
+  })
+  topView?: string
+
   @Column({ nullable: true })
   @Field({ nullable: true, description: 'When the original figure was created.' })
   createdAt?: Date

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

@@ -17,6 +17,15 @@ import { parseSource } from './figure-format.js'
 import { ProposeFigureFailure, proposeFigureSteps } from './figure-propose-steps.js'
 import { prepareFigureWrite, compareAndSwapFigure, pictureOf } from './figure-write.js'
 
+/** Display names by language: a language code to a name of 1-128 characters. Refused whole, with the bad entry named. */
+export function assertNames(names: unknown): asserts names is Record<string, string> {
+  if (!names || typeof names !== 'object' || Array.isArray(names)) throw new Error('names 는 { 언어: 이름 } 이어야 한다')
+  for (const [lang, name] of Object.entries(names)) {
+    if (!/^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/.test(lang)) throw new Error(`'${lang}' 는 언어 코드가 아니다`)
+    if (typeof name !== 'string' || !name.trim() || name.length > 128) throw new Error(`'${lang}' 의 이름은 1~128자 글이어야 한다`)
+  }
+}
+
 @Resolver(Figure)
 export class FigureMutation {
   @Directive('@transaction')
@@ -56,7 +65,7 @@ export class FigureMutation {
     if (!id) {
       if (!creationId || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(creationId))
         throw Error('새 모델 저장에는 생성 요청 식별자가 필요합니다.')
-      const prepared = { ...prepareFigureWrite(source), ...pictureOf(thumbnail) }
+      const prepared = { ...prepareFigureWrite(source), ...(await pictureOf(tx, domain, user, thumbnail)) }
       const previous = await repository.findOne({ where: { id: creationId, domain: { id: domain.id } } })
       if (previous) {
         if (previous.source !== prepared.source) throw Error('이 생성 요청은 이미 다른 내용으로 저장되었습니다. 저장된 모델을 다시 열어 주세요.')
@@ -91,7 +100,7 @@ export class FigureMutation {
     // Exact tenant ownership: an inherited catalog entry is not writable in the child domain.
     const figure = await repository.findOne({ where: { id, domain: { id: domain.id } } })
     if (!figure) throw Error('편집할 Figure를 찾을 수 없습니다.')
-    const prepared = { ...prepareFigureWrite(source, figure, expectedSource), ...pictureOf(thumbnail, figure) }
+    const prepared = { ...prepareFigureWrite(source, figure, expectedSource), ...(await pictureOf(tx, domain, user, thumbnail, figure)) }
     // Compare-and-swap in the UPDATE itself: supported by SQLite as well as PostgreSQL.
     // A pessimistic row lock is not supported by the product's SQLite deployment.
     await compareAndSwapFigure(criteria => repository.update(criteria, { ...prepared, updater: user }),
@@ -119,12 +128,13 @@ export class FigureMutation {
     // 형식을 어기면 여기서 던진다. 파생값은 서버가 계산한다.
     const { source, derived, violations } = parseSource(figure.source)
 
+    const { thumbnail, ...rest } = figure
     const saved = await repository.save({
-      ...figure,
+      ...rest,
       source,
       ...derived,
       state: figure.state ?? 'draft',
-      thumbnailUpdatedAt: figure.thumbnail ? new Date() : undefined,
+      ...(await pictureOf(tx, domain, user, thumbnail)),
       domain,
       creator: user,
       updater: user
@@ -174,6 +184,11 @@ export class FigureMutation {
       행과 정본 둘 다 고친다. 정본 안에도 `type` 이 있어서 한쪽만 고치면 저장된 JSON 과
       행이 다른 이름을 말하고, 발행할 때 어느 쪽이 도면에 적히는지가 갈린다.
     */
+    if (patch.names !== undefined) assertNames(patch.names)
+    /* The picture is kept by its content; the patch's data URL is never written to the row. */
+    const { thumbnail: picturePatch, ...patchRest } = patch
+    const picture = await pictureOf(tx, domain, user, picturePatch, figure)
+
     let renamed: string | undefined
     if (patch.type !== undefined && patch.type !== figure.type) {
       const change = await this.renameType(figure, domain, patch.type, source, tx)
@@ -195,7 +210,7 @@ export class FigureMutation {
       */
       domain,
       ...figure,
-      ...patch,
+      ...patchRest,
       /* 앞뒤 공백을 떼고 겹침까지 본 이름. `patch.type` 을 그대로 두면 다듬기 전 값이 들어간다. */
       ...(renamed !== undefined ? { type: renamed } : {}),
       source,
@@ -209,10 +224,8 @@ export class FigureMutation {
       state: 'draft',
       ...(derived ?? {}),
       // 썸네일이 **썸네일로서** 바뀐 때만 시각을 갱신한다. 이름·설명 변경에는 안 건드린다.
-      thumbnailUpdatedAt:
-        patch.thumbnail !== undefined && patch.thumbnail !== figure.thumbnail
-          ? new Date()
-          : figure.thumbnailUpdatedAt,
+      thumbnail: figure.thumbnail ?? null,
+      ...picture,
       updater: user
     })
 
@@ -338,7 +351,9 @@ export class FigureMutation {
       /* 판본 구독자가 이것들을 판본의 comment · assetFormat · changes 로 옮긴다. Figure 의 칸이 아니다. */
       __releaseComment: comment ?? null,
       __releaseFormat: record.format,
-      __releaseChanges: record.changes
+      __releaseChanges: record.changes,
+      __releaseMetrics: record.metrics,
+      __releaseTopView: record.topView
     } as any)
   }
 
@@ -408,6 +423,37 @@ export class FigureMutation {
     return true
   }
 
+  /**
+   * 퇴역시키거나 되살린다(ADR-0104 결정 6).
+   *
+   * 표시일 뿐이다. 발행판은 그대로 남고 받는 쪽은 그대로 받는다 — 발행판은 지우지 않는다. 그래서 **발행을 풀지 않는다**:
+   * 행을 엔티티로 저장하지 않고 질의로 고친다. 엔티티로 저장하면 발행된 행이라 판본 구독자가 같은 번호로 판본을 또
+   * 뜬다. 대신 쓸 것(`supersededBy`)은 같은 도메인(또는 상위)에 있는 다른 type 이어야 한다.
+   */
+  @Directive('@transaction')
+  @Directive('@privilege(category: "figure", privilege: "mutation", domainOwnerGranted: true)')
+  @Mutation(returns => Figure, { description: 'Retires a figure or brings it back. It stays released and served; supersededBy names the type to use instead.' })
+  async setFigureDeprecation(
+    @Arg('id') id: string,
+    @Arg('deprecated') deprecated: boolean,
+    @Ctx() context: ResolverContext,
+    @Arg('supersededBy', { nullable: true }) supersededBy?: string
+  ): Promise<Figure> {
+    const { domain, tx } = context.state
+    const repository = tx.getRepository(Figure)
+    const scope = { id: In([domain.id, domain.parentId].filter(Boolean)) }
+    const figure = await repository.findOne({ where: { domain: scope, id } })
+    if (!figure) throw new Error(`Figure ${id} 를 찾을 수 없다`)
+    const instead = deprecated ? supersededBy?.trim() || null : null
+    if (instead) {
+      if (instead === figure.type) throw new Error(`Figure '${figure.type}' 는 자기 자신으로 대신할 수 없다`)
+      const other = await repository.findOne({ where: { domain: scope, type: instead } })
+      if (!other) throw new Error(`대신 쓸 Figure '${instead}' 가 이 도메인에 없다`)
+    }
+    await repository.createQueryBuilder().update(Figure).set({ deprecated, supersededBy: instead }).where('id = :id', { id }).callListeners(false).execute()
+    return await repository.findOneOrFail({ where: { id } })
+  }
+
   /**
    * 저작 보조에게 제안을 시킨다(ADR-0094).
    *

package/server/service/figure/figure-release-record-db.test.ts

@@ -63,6 +63,8 @@ describe('a release record on its history row', () => {
     expect(row.assetFormat).toBe('figure-asset-1')
     expect(JSON.parse(row.changes)).toEqual(changes)
     expect(row.comment).toBe('first')
+    expect(row.metrics).toBeNull()
+    expect(row.topView).toBeNull()
   })
   it('[] stays nothing changed, null stays not compared', async () => {
     expect((await release({ __releaseFormat: 'figure-asset-1', __releaseChanges: [] })).changes).toBe('[]')
@@ -90,5 +92,8 @@ describe('releaseFigure records it', () => {
     expect(rows[0].changes).toBe('[]')
     const codes = JSON.parse(rows[1].changes).map((c: any) => c.code)
     expect(codes).toContain('occupancy-changed')
+    /* What each release measured, and its plan from above, are on its own row. */
+    expect(JSON.parse(rows[0].metrics)).toEqual({ origin: { centred: true, off: [] } })
+    expect(JSON.parse(rows[1].topView).shapes.map((s: any) => s.id)).toEqual(['body'])
   })
 })

package/server/service/figure/figure-replaced-draft.ts

@@ -47,6 +47,15 @@ export class FigureReplacedDraft {
   @Column({ nullable: true, ...longTextColumn() })
   thumbnail?: string
 
+  /*
+   * 그림의 내용 해시(SHA-256). 그림 자체는 attachment-base 가 갖고(refType `figure-thumbnail`, refBy 이 해시),
+   * `/figure-thumbnail/:id` 가 권한을 본 뒤 내준다(ADR-0104 결정 6). `thumbnail` 칸은 옛 base64 가 남은 행을
+   * 기동 때 옮기기 위한 칸이다 — 옮긴 뒤에는 비어 있고, 새 그림은 그 칸에 쓰지 않는다.
+   */
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'SHA-256 of the thumbnail picture; the picture is served by /figure-thumbnail/:id.' })
+  thumbnailHash?: string
+
   @Column({ nullable: true })
   @Field({ nullable: true, description: 'The state the figure was in.' })
   state?: string