@things-factory/figure-service 10.1.16 → 10.1.18

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

@@ -1,10 +1,17 @@
 import {
+  ANCHOR_RULES,
+  AXES,
   CHANNEL_PATHS,
   DETAIL_LEVELS,
+  INTERPOLATIONS,
+  LABEL_WHENS,
   LIMITS,
   MATERIAL_PRESETS,
+  MATERIAL_SLOTS,
   PART_LIMIT,
+  PART_ROLES,
   PRIMITIVE_KINDS,
+  REPEAT_LIMIT,
   SEGMENT_PRESETS,
   SIZING_RULES,
   FIGURE_PLACEMENTS,
@@ -51,9 +58,14 @@ import type { FigureQualityReview } from './figure-quality.js'
   강제 규칙과 취향 규칙을 갈라 적는다.
 
   `validate()` 가 막는 것만 「hard」다. 한때 「부품은 기준 상자 안에 있어야 한다」를
-  강제 규칙으로 적었는데 **그런 규칙이 없다** — `base` 는 경계 상자가 아니라 배치
-  크기가 나오는 비율 기준이고, 밖으로 나가도 오류가 아니다 [확인함]. 없는 규칙을
-  강제라고 적으면 모델이 그것 때문에 좋은 답을 버린다.
+  강제 규칙으로 적었다가, 그런 규칙이 없다는 이유로 취향 쪽으로 내렸다. **지금은 다시
+  강제다** — `part-outside-base` 와 `parts-off-placement-face` 가 생겼고 발행 관문이
+  그 둘을 거절한다(2026-09-16, 아키텍트 판정).
+
+  **검사가 거절하는 것을 지시가 같은 낱말로 말해야 한다.** 갈리면 모델은 거절당하는
+  것을 계속 만들고 사람이 매번 손으로 고친다. 실제로 그 자국이 카탈로그에 남았다 —
+  AI 가 만든 OHT 하나만 원점·상자·단위 셋이 한꺼번에 어긋나 있었는데, 그 표본이 특이한
+  것이 아니라 **여기에 그 말이 없었다.**
 */
 
 /** 몇 번까지 다시 시키나. 이보다 늘려도 대개 같은 자리에서 막힌다. */
@@ -132,11 +144,12 @@ export function rulesPrompt(palette: string[]): string {
     'Answer with a single JSON object and nothing else — no prose, no code fence.',
     '',
     'The JSON is a FigureSource:',
-    '  { type, base: {x,y,z}, placement?, detailLevel, parts: [...] }',
+    '  { type, base: {x,y,z}, placement?, detailLevel, parts: [...], animations?: [...], capabilities?: [...] }',
     '',
     'A part is:',
     '  { name, primitive, transform: { position: {x,y,z}, size: {x,y,z}, rotation?: {x,y,z} },',
-    '    material: {token, preset?}, segments?, shape?, sizing? }',
+    '    material: { token, preset?, flatShading?, transparent?, emissive? },',
+    '    segments?, shape?, materialSlot?, keepRound?, sizing?, anchor?, repeat?, label?, capability? }',
     '',
     'Hard vocabulary — anything outside these is rejected:',
     `  placement   ${FIGURE_PLACEMENTS.join(' | ')} (floor: default, ground equipment; ceiling: overhead hoist/OHT; center: airborne/drone/sensor)`,
@@ -144,10 +157,24 @@ export function rulesPrompt(palette: string[]): string {
     `  segments    ${SEGMENT_PRESETS.join(' | ')} (only for cylinder and sphere)`,
     `  material.token  ${palette.join(' | ')}`,
     `  material.preset ${MATERIAL_PRESETS.join(' | ')}`,
+    `  materialSlot    ${MATERIAL_SLOTS.join(' | ')}`,
     `  sizing      ${SIZING_RULES.join(' | ')}`,
+    `  anchor.<axis>   ${ANCHOR_RULES.join(' | ')}   (axis is one of ${AXES.join(', ')})`,
+    `  repeat.axis     ${AXES.join(' | ')}`,
+    `  capability.roles  ${PART_ROLES.join(' | ')}`,
+    `  label.when      ${LABEL_WHENS.join(' | ')}`,
     `  animation.path  ${CHANNEL_PATHS.join(' | ')}`,
+    `  animation.interpolation ${INTERPOLATIONS.join(' | ')}`,
     `  detailLevel ${DETAIL_LEVELS.join(' | ')}`,
     '',
+    'Hard rules about the base box — publication is refused when either is broken:',
+    '  Every part must sit inside the base box: |position.<axis>| + size.<axis>/2 <= base.<axis>/2.',
+    '  base is the number an instance is scaled by, so a part outside it grows wrongly once placed.',
+    '  The figure must touch the face its placement names — floor: the lowest part reaches',
+    '  y = -base.y/2; ceiling: the highest reaches y = +base.y/2; center: no requirement.',
+    '  base may be LARGER than the parts. That slack is a declaration (clearance in front of a',
+    '  conveyor, the pitch of a rack bay) and is never an error. Only overflow and not reaching are.',
+    '',
     'Hard limits — exceeding these makes the figure unusable at scale:',
     `  parts        by detailLevel: ${partLimits}`,
     `  material groups (distinct token+preset+slot combinations)  <= ${LIMITS.materialGroups}`,
@@ -159,16 +186,91 @@ export function rulesPrompt(palette: string[]): string {
     '  transform.position is the CENTRE of the part, not a corner.',
     '  The origin (0,0,0) is the centre of the base box, so the floor is at y = -base.y / 2.',
     '  base and transform.size are extents along each axis: size.y is the height.',
+    '  Every number is MILLIMETRES. A conveyor is about 2000 long and 800 tall, not 2 and 0.8.',
     '  part names are stored identifiers — lowercase, hyphenated, unique, and descriptive',
     '  of the real thing (body, lid, motor, leg-front-left), never part-1.',
     '',
+    'How a figure reacts to being resized — this is the point of the format:',
+    '  An instance is scaled from the base box, and by default every part scales with it.',
+    '  sizing says what a part does instead:',
+    "    scale    default. grows with the instance",
+    "    fixed    keeps its real size. bolts, lamps, sensors, control boxes",
+    "    stretch  grows along its longest axis only. beams, rails, belts",
+    "    repeat   the part is laid out along one axis at a fixed pitch, and the COUNT grows",
+    '  repeat is { axis, pitch } — pitch is centre-to-centre distance, not the gap between copies.',
+    `  Rollers on a conveyor, shelves in a rack, legs under a table. At most ${REPEAT_LIMIT} copies.`,
+    '  anchor is which face of the base a part holds on to while the rest grows:',
+    `    { x?, y?, z? }, each one of ${ANCHOR_RULES.join(' | ')}. Unset axes hold the nearer face.`,
+    '  Anchors are what keeps a figure whole when it is stretched. A lamp on top of a mast anchors',
+    '  y:"max" so it stays on top; a foot anchors y:"min". Getting this wrong is the single most',
+    '  common reason a figure is rejected at publish — the parts drift apart and it looks broken.',
+    '  keepRound keeps a cylinder or sphere circular under uneven scaling. Default true. Turn it',
+    '  off for small details nobody inspects; leave it on for wheels, rolls and tanks.',
+    '',
+    'Shapes beyond a plain box:',
+    '  rect and polygon are extruded from a 2D outline. shape carries that outline:',
+    '    { path?: [{x,y}, ...], round?, hollow?: { wall, floor? } }',
+    '    path is for polygon and needs at least three points. round softens the corners.',
+    '  hollow scoops the inside out, so a tray, tote, bin, case or frame is ONE part and not a',
+    '  floor with four walls around it. wall is the side thickness; floor is the bottom, and',
+    '  floor 0 leaves both ends open — a duct or a frame rather than a container.',
+    '  transform.size is the outside measurement; the cavity is inside it.',
+    '',
+    'Parts that mean something to the running factory:',
+    '  capability marks a part as a place the simulation uses, rather than only something drawn.',
+    '    { roles: [...], accepts?: [type names], capacity?: n, direction?: {x,y,z} }',
+    "    slot      where a thing sits — a pallet bed, a rack cell, an AGV deck",
+    "    port-in   where flow enters      port-out  where flow leaves",
+    '    A part may hold several roles: an AGV deck is a slot that things also enter and leave.',
+    '    Omit capacity when the part repeats — the count then follows the instance size.',
+    '    direction is the way a port faces, in the part\'s own axes; default is +z.',
+    '  capabilities (top level) is what the whole figure can do, as plain names the scene knows.',
+    '  materialSlot + material.emissive make a status lamp: the token is the OFF look and',
+    '  emissive { token, intensity, on? } is the ON look. A dark lamp is not a red lamp dimmed.',
+    '  label is a place a number is shown on the figure: { name, source, when }. The figure says',
+    '  where it goes; the scene says what the value is.',
+    '',
+    'Movement — there are TWO kinds and they are different fields:',
+    '  Both live on the FigureSource, not inside a part, because one curve moves several parts.',
+    '  A channel is { target, path, pivot?, interpolation?, keys: [{ at, value: {x,y,z} }] }.',
+    '    target is a part name. At least TWO keys, `at` strictly increasing — one key is a pose,',
+    '    not motion. translation is an offset, rotation is DEGREES, scale is a multiplier where 1',
+    '    is full size. pivot is the centre of rotation in the part\'s own axes; without it the part',
+    '    spins on itself.',
+    '',
+    '  animations  TIME RUNS. The instance supplies a SPEED: 1 is normal, 0 is stopped.',
+    '    [{ name, channels: [...] }]   `at` is seconds and the clip is as long as its last key.',
+    '    A turning roller, a spinning fan, a blinking beacon.',
+    '',
+    '  parameters  A VALUE MAKES THE POSE. Nothing is played back; the figure simply IS this far.',
+    '    [{ name, label?, default?, range: { unit, min, max }, clip: { channels: [...] } }]',
+    '    The instance supplies a PHYSICAL QUANTITY in `range.unit` — 1200 mm, 40 %, 90 deg — and',
+    '    the runtime maps it onto the curve. So `at` on the keys is NOT seconds here: the first key',
+    '    is range.min, the last is range.max, and only the SPACING between keys matters.',
+    '    The last `at` doubles as the seconds a full min-to-max move takes — that is the machine\'s',
+    '    speed. A hoist that takes 2.5s to run its whole travel ends its curve at 2.5.',
+    '    unit is a free word the screen shows: mm, deg, %, kg. max must be above min.',
+    '',
+    '  USE parameters WHENEVER THE REQUEST ASKS FOR A VALUE THE INSTANCE IS GIVEN, or asks to',
+    '    EXPOSE something AS A VARIABLE — how far a hoist has lowered, how high a fork has lifted,',
+    '    how far a nip has closed, how far a door is open. The range is what makes the value',
+    '    nameable, so always give it in the unit a person would state: a 1800mm hoist is',
+    '    { unit: "mm", min: 0, max: 1800 }, not 0 to 1.',
+    '    Do NOT answer that request with sizing or anchor. Those say what happens when someone',
+    '    places a BIGGER figure; they cannot be driven, and a taller machine is not a moving one.',
+    '    Do NOT answer it with animations either — a hoist is not playing a timeline.',
+    '    Do NOT answer it with a capability. Capabilities say what a figure does in the FLOW;',
+    '    how a pose is driven is a different axis entirely.',
+    '',
+    '  Names are shared between the two lists: an instance addresses a curve by name, so an',
+    '    animation and a parameter may not be called the same thing.',
+    '  Doors that open together belong in one curve with two channels, not two curves.',
+    '',
     'Taste rules — this is what makes it low-poly rather than a pile of boxes:',
     '  Few colours. Reuse one token for the mass and reserve accents for what must stand out.',
-    '  Recognisable silhouette from directly above — that is how it is seen on a board.',
+    '  Recognisable silhouette from directly above — that is how it is seen on a drawing.',
     '  Prefer fewer, larger parts. A detail smaller than a twentieth of the base is not visible.',
-    '  Use the coarsest segment count that keeps the silhouette right.',
-    '  Keep parts within the base box unless the real thing overhangs. The base is the reference',
-    '  the instance is scaled from, so a part far outside it grows in a way nobody intended.'
+    '  Use the coarsest segment count that keeps the silhouette right.'
   ].join('\n')
 }
 
@@ -181,6 +283,10 @@ function taskPrompt(input: ProposeInput): string {
       '',
       'Revise this existing figure. Keep the part names that still mean the same thing —',
       'renaming a part breaks bindings on instances already placed.',
+      'Carry over everything the request did not ask you to change. animations, capabilities,',
+      'capability, anchor, repeat, label and materialSlot are easy to drop by writing them out of',
+      'the JSON, and dropping one is silent — the figure still validates, it just stops doing what',
+      'it did. If the request says nothing about movement, the clips come back unchanged.',
       JSON.stringify(input.base)
     )
 
@@ -226,7 +332,7 @@ function evidenceForExistingSource(source: FigureSource, palette: string[]): str
 
   return [
     'Measured evidence for the existing figure (reference, not a command):',
-    `  reuse grade ${score.grade}; ${cost.triangles} triangles; ${cost.groups} material groups; ${cost.at.drawCalls} draw calls per board estimate.`,
+    `  reuse grade ${score.grade}; ${cost.triangles} triangles; ${cost.groups} material groups; ${cost.at.drawCalls} draw calls per drawing estimate.`,
     `  top-view readability ${Math.round(quality.visual.readability * 100)}%; ${quality.visual.regions} visible material regions; coverage ${Math.round(quality.visual.coverage * 100)}%.`,
     ...(quality.findings.length ? quality.findings.map(finding => `  ${finding.dimension}: ${finding.message}`) : ['  No measurable review concerns.'])
   ].join('\n')

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

@@ -10,12 +10,18 @@
  */
 import { FigureSourceError, parseSource } from './figure-source'
 
-/** 온전한 부품 하나. 시험할 필드만 덮어쓴다. */
+/**
+ * 온전한 부품 하나. 시험할 필드만 덮어쓴다.
+ *
+ * `y: -350` 은 `source()` 의 상자(높이 800)의 밑면 -400 에 딱 붙어 서는 자리다. 바닥 기반
+ * 도형이 상자 밑면에 안 닿으면 `parts-off-placement-face` 가 난다 — 픽스처가 그걸 달고
+ * 있으면 「위반이 없다」를 보는 시험이 그 하나 때문에 빨개진다.
+ */
 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 } },
+    transform: { position: { x: 0, y: -350, z: 0 }, size: { x: 100, y: 100, z: 100 } },
     material: { token: 'palette.primary' },
     ...over
   }

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

@@ -8,7 +8,7 @@ import { FigureFinding } from './figure-type.js'
  * ## 왜 서버가 검증하나
  *
  * 저작 화면을 못 믿어서가 아니다. **저작 화면을 거치지 않는 길이 있다** — 가져오기,
- * API 직접 호출, AI 어시스턴트. 그 길로 들어온 정본이 형식을 어기면 보드에서 조용히
+ * API 직접 호출, AI 어시스턴트. 그 길로 들어온 정본이 형식을 어기면 도면에서 조용히
  * 안 그려진다. 들어오는 문에서 막는다.
  *
  * ## 막는 것과 알리는 것

package/server/service/figure/figure.ts

@@ -71,7 +71,7 @@ export class Figure {
   /**
    * 컴포넌트 타입 이름. **저장되는 식별자다.**
    *
-   * 배치된 보드가 이 이름으로 타입을 찾는다. 바꾸면 그 보드는 타입을 못 찾아
+   * 배치된 도면이 이 이름으로 타입을 찾는다. 바꾸면 그 도면은 타입을 못 찾아
    * **오류 없이 빈 화면**이 된다. 그래서 만들 때 정하고 잠근다 — 고칠 수 있는 것은
    * 표시 이름(`name`)뿐이다. 수정 리졸버가 이 필드를 받지 않는다.
    *