@things-factory/kpi 10.0.0-zeta.9 → 10.0.1

package/RFC-production-readiness.md

@@ -0,0 +1,161 @@
+# RFC: `@things-factory/kpi` 프로덕션 완성도 향상
+
+- **상태**: Draft
+- **대상 모듈**: `@things-factory/kpi` (v10.0.0-zeta.10)
+- **목적**: 이 프레임워크 모듈 자체의 완성도·재사용성 향상. (특정 앱 — 예: `@dssp/dkpi` — 을 위한 것이 아님)
+- **작성 근거**: 모듈 소스 코드 감사(2026-07-14). 인용된 `file:line`은 감사 시점 기준.
+
+---
+
+## 1. 배경 & 문제의식
+
+`@things-factory/kpi`는 **계층형 KPI + metric 집계 + 통계**를 갖춘 범용 KPI 프레임워크다. 골격(엔티티, AST 계산기, 통계 엔진)은 견고하다. 그러나 실전 적용(예: DSSP KPI POC)에서 **앱이 프레임워크 관심사를 대신 떠안는** 패턴이 반복 관찰됐다:
+
+- metric ↔ 소스 바인딩(`collectType/dataSet/fieldName`)이 있으나 **쓰기 불편해 앱이 하드코딩 매핑으로 우회**.
+- 값 입력 UI가 **metric 이름 추측·하드코딩 위젯** 기반 → admin이 metric을 추가/변경하면 UI가 자동 대응 못 함.
+- `(domain, metric, valueDate, org)` upsert·`valueDate` 규칙이 **앱 코드로 샘**.
+- "데이터 없음"과 "계산 실패"가 구분되지 않아 앱에서 시나리오가 중단(HALT)되는 사고.
+
+프레임워크의 존재 이유는 **"코드 없이 런타임 설정으로 KPI를 구성"** 하는 것이다. 위 gap들은 그 전제를 프로덕션 규모에서 무너뜨린다. 본 RFC는 이를 메우기 위한 우선순위·설계를 제안한다.
+
+## 2. 목표 / 비목표
+
+**목표**
+- 선언(정의)만으로 **수집·입력 UI·검증·계산**이 자동으로 따라오는 구조.
+- 계산의 **정확성·안전성·테스트가능성** 확보.
+- metric/kpi 정의 **진화(버전)** 를 데이터 정합성 손상 없이 수용.
+
+**비목표**
+- 건설 등 특정 도메인 기능 추가(범용성 유지).
+- 기존 데이터 파괴적 마이그레이션(모두 하위호환 경로 제공).
+- 대시보드/시각화 렌더링 자체(모듈은 정의·저장, 표현은 소비자 몫 — 단 vizMeta 스펙은 문서화).
+
+## 3. 현재 상태 요약 (감사 기반)
+
+| 영역 | 상태 | 완성도 | 핵심 gap |
+|---|---|---|---|
+| 엔티티 모델 | 있음 | 70% | metric 버전 추적 부재, 렌더힌트 스키마 부재, scope 필드 중복(`group` vs `kpiOrgScope`) |
+| 계산 엔진 | 있음(AST 파서/평가기 분리) | 60% | **집계 경로가 `Function()` eval 사용**(안전한 AST 평가기 미사용), 논리연산 부재, 전량 재계산, 결측/실패 미구분 |
+| Score 계산 | 있음 | 75% | scoreFormula 검증 부재, formula 변경 후 자동 재계산 트리거 없음, `grades`(deprecated) 혼재 |
+| 수집 AUTO/MANUAL | 있음 | 70~80% | EXTERNAL 미구현, metric `schedule` 자동 호출 미연결, collectType별 UI 분기 없음 |
+| 통계 | 있음 | 85% | N+1 쿼리 |
+| Alert | GraphQL 타입만 | 10% | rule/trigger 엔진 전무 (`kpi-alert-type.ts`, DB 엔티티 아님) |
+| 클라이언트 UI | 부분 | 40% | **metadata 기반 제네릭 렌더러 부재**, metric 정의 에디터 부재, 동적 metric 코드수정 없이 렌더 불가 |
+| 버전관리 | 부분 | 50% | Kpi는 `@VersionColumn`+`KpiHistory` 있음, **KpiMetricValue는 metric 버전 미스탬프** |
+| 테스트 | 없음 | 0% | calculator/formula/aggregate 전부 무테스트 |
+| 보안 | 부분 | 50% | **formula `Function()` eval → injection 위험** (`aggregate-kpi.ts:53`) |
+
+강점(유지): AST 파서/평가기 분리(`server/calculator/parser.ts`, `evaluator.ts`, `functions.ts`), 통계 엔진(`kpi-statistic-calculation.service.ts`), 계층형 KPI + KpiHistory 스냅샷, 다차원 scope(KpiScope level1~5).
+
+## 4. 설계 원칙
+
+1. **선언적, 비-마법적(declarative, not magical)**: 동작은 정의(메타데이터)에서 결정한다. 이름 추측·값 추론 금지.
+2. **프레임워크가 관심사를 소유**: valueDate/upsert/집계 규칙은 모듈 API 뒤로 숨긴다. 앱은 "무엇을/언제"만 말한다.
+3. **80/20 + 탈출구**: 제네릭이 80%를 자동 처리, 예외는 커스텀 레지스트리로.
+4. **결측 ≠ 실패**: 데이터 없음은 정상 상태(1급), 실패는 별도.
+5. **진화 가능**: 정의 변경이 과거 데이터를 깨지 않도록 버전 스탬프.
+
+---
+
+## 5. 제안 (우선순위별)
+
+### P0 — 정확성·안전성·신뢰 (선행 필수)
+
+#### P0-1. 안전한 단일 계산 경로로 통일 (eval 제거)
+- **문제**: 안전한 AST 파서/평가기(`server/calculator/*`)가 있음에도, 집계는 `new Function(...)`로 formula를 eval한다 → **코드 인젝션 위험 + 검증 불가 + silent fail**. 근거: `server/service/kpi/aggregate-kpi.ts:53`.
+- **제안**: 모든 formula/scoreFormula 평가를 **AST 평가기 하나로 통일**하고 `Function()` 경로 삭제. 평가기에 논리/비교 연산(`&&`, `||`, `>`, `<`, `>=`, `<=`, `==`), 삼항 대체(`if()`는 유지) 추가.
+- **효과**: 보안 + 정적 검증 가능 + 결정적 테스트 가능.
+
+#### P0-2. Formula 검증기 완성
+- **문제**: `validateFormula()`가 metric 존재·순환참조는 보나 **문법(괄호/토큰)·함수 존재 검증은 주석만**. 근거: `server/service/kpi/kpi-formula.service.ts:33-65`.
+- **제안**: 파서를 재사용해 (a) 구문 파싱 성공, (b) 사용 함수가 `functions.ts` 화이트리스트에 존재, (c) 미정의 변수 없음 을 **정의 저장 시점에 검증·거부**. 저장 mutation에서 강제.
+
+#### P0-3. 결측 vs 실패 시맨틱 + 상태/프로버넌스
+- **문제**: metric 값 부재는 저장 안 함, 계산 실패도 `value=null` 후 skip → **구분 불가·추적 불가**. 근거: `aggregate-kpi.ts:60`, `kpi-value-score.service.ts`(null 반환).
+- **제안**: `KpiValue`/`KpiMetricValue`에 **상태 개념** 도입 — `OK | NO_DATA | ERROR`(+ `meta.error`). 계산기는 예외를 삼키지 말고 `ERROR` 상태 + 사유 기록. 조회/집계는 `NO_DATA`를 정상 전파(null propagation 규칙 명문화).
+- **효과**: 앱이 "없음"에 중단하지 않고 진행(HALT 방지), 운영 모니터링 가능.
+
+#### P0-4. Metric 버전 스탬프
+- **문제**: `Kpi`는 `@VersionColumn`+`KpiHistory` 스냅샷이 있으나(`kpi.ts`, `kpi-history.ts`), **`KpiMetricValue`는 metric 버전을 안 남김**(`kpi-metric-value.ts:1-93`). metric 정의(periodType/unit/dataSet) 변경 후 과거 값 해석 불가.
+- **제안**: `KpiMetric`에 version, `KpiMetricValue`에 기록 시점 `metricVersion` 스탬프. 정의 변경 시 `KpiMetricHistory` 스냅샷(기존 KpiHistory 패턴 재사용).
+
+#### P0-5. 테스트 스위트 구축
+- **문제**: `*.test.ts`/`*.spec.ts` 전무, package.json test script 없음.
+- **제안**: 최우선으로 **순수 로직**(parser, evaluator, functions, formula.service, score.service, aggregate)에 단위테스트. CI 게이트. (P0-1~3의 회귀 안전망)
+
+### P1 — 선언적 자동화 (프레임워크의 본질)
+
+#### P1-1. 선언적 정의 스키마 + 렌더 힌트 (핵심 레버)
+- **문제**: 정의에 "입력/표현을 어떻게 할지" 메타가 없어, UI가 **이름 추측**(예: scoreType 추론 `kpi-list-page.ts:54-60`)과 하드코딩에 의존. `unit`도 자유 문자열.
+- **제안**: metric/kpi 정의를 확장:
+  ```ts
+  // KpiMetric 확장
+  kind: 'attribute' | 'performance'          // 고정속성 vs 시계열성과
+  source: { type: 'entityField' | 'dataset' | 'external' | 'manual', ... }
+  input: { widget: 'number'|'rating'|'select'|'date'|'text',
+           min?, max?, step?, options?, required? }   // 렌더/검증 힌트
+  aggregation?: 'sum'|'avg'|'last'|'min'|'max'
+  ```
+  - `kind`는 **reference(고정 속성) vs performance(성과)** 를 모델에 각인 → 소비 앱의 "속성↔KPI 양방향 sync" 같은 안티패턴 원천 차단.
+  - `input`은 위젯·검증을 **정의가 소유**. (별점 0.5→1점 같은 요구가 코드가 아니라 `input.step`로 해결)
+
+#### P1-2. Metadata-driven 제네릭 렌더러 + 커스텀 레지스트리
+- **문제**: 값 입력 UI가 하드코딩, 동적 metric은 코드 수정 없이 못 뜬다(`kpi-metric-value-manual-entry-form.ts`, `kpi-value-editor-page.ts`).
+- **제안**: `input` 힌트를 읽어 위젯을 렌더하는 **제네릭 렌더러 1개** + 예외용 **custom renderer registry**(80/20). periodType(단일/월별그리드/기간) 인지 레이아웃 포함.
+
+#### P1-3. 값 인입 API (upsert/valueDate 캡슐화)
+- **문제**: `(domain,metric,valueDate,org)` upsert·MONTH/ALLTIME valueDate 규칙이 앱으로 샘.
+- **제안**: `kpi.record({ metric, value, org, period, at? })` 단일 진입점이 valueDate 정규화·upsert·버전스탬프·상태를 내부 처리. period/bucket을 문자열 관례 대신 타입으로.
+
+#### P1-4. 수집(collector) 추상화
+- **문제**: `collectType` enum은 있으나 EXTERNAL 미구현, metric `schedule` 자동 호출 미연결(스케줄은 KPI에만 `registerSchedule` — `kpi-mutation.ts:76-110`), 수집이 앱/시나리오에 의존.
+- **제안**: metric별 **Collector 인터페이스**(`collect(): {found, value, provenance}`)와 스케줄러 연동을 모듈이 제공. AUTO(dataset)·MANUAL은 기본 제공, EXTERNAL/IMPORT는 소비자가 collector 등록. "found=false"는 정상.
+
+### P2 — 정리·운영
+
+- **P2-1. Deprecated 필드 정리**: `grades`→`scoreFormula`(`kpi-value-score.service.ts:51`), `KpiValue.group`(string)→`kpiOrgScope`(ref). 마이그레이션 + 이중지원 종료 계획.
+- **P2-2. Scope 필드 통합**: `org`/`group`/`kpiOrgScope`/`project`를 **하나의 scope(dimension) 모델**로 수렴, 나머지 deprecate.
+- **P2-3. 통계 N+1 제거**: `kpi-statistic-calculation.service.ts:154-210`, `aggregate-kpi-metric.ts:66` batch/조인.
+- **P2-4. Alert rule 엔진**: 현 `kpi-alert-type.ts`는 타입만 → 조건·트리거·저장 엔티티 설계.
+- **P2-5. 권한 세분화**: 현 `kpi:mutation|query` 2단계 → metric정의/값입력/조회 분리.
+- **P2-6. 문서화**: formula/scoreFormula 문법·함수 목록, `vizMeta` 스펙(vizType별 필드), KpiScope(scope01~05) taxonomy, cron 가이드.
+
+---
+
+## 6. 마이그레이션 & 하위호환
+
+- 신규 필드(kind/source/input, metricVersion, status)는 **nullable + 기본값**으로 추가 → 기존 데이터 무손상.
+- 기존 정의에 `kind`/`input` 미지정 시: 렌더러는 **안전한 폴백**(number 위젯) + 콘솔 경고. (점진 채택)
+- eval→AST 전환은 기존 formula 문법을 **파서가 수용하는지 회귀테스트**(P0-5) 후 전환. 미수용 문법은 마이그레이션 스크립트로 정규화.
+- `grades`/`group`은 **읽기 이중지원 유지**하며 한 마이너 버전 뒤 제거 공지.
+
+## 7. 리스크
+
+- **eval→AST 전환**이 기존 프로덕션 formula를 깨뜨릴 수 있음 → 회귀 코퍼스 + 파서 수용성 검증 선행(P0-5, P0-1 순서 고정).
+- 선언 스키마 확장은 **소비 앱들이 서서히 채택**해야 효과 → 폴백을 보장해 강제 마이그레이션 회피.
+- 범용성 훼손 위험 → 모든 신규는 **도메인 중립 메타**만(건설 특화 금지).
+
+## 8. 단계 로드맵
+
+- **Phase 1 (신뢰 기반)**: P0-5 테스트 → P0-1 eval 제거/통일 → P0-2 검증기 → P0-3 상태 시맨틱 → P0-4 버전 스탬프.
+- **Phase 2 (선언 자동화)**: P1-1 스키마 → P1-3 record API → P1-2 제네릭 렌더러 → P1-4 collector.
+- **Phase 3 (정리·운영)**: P2-*.
+
+각 Phase는 독립 배포 가능하며 하위호환을 유지한다.
+
+---
+
+## 부록 A. 핵심 근거 (file:line)
+
+- 계산 eval: `server/service/kpi/aggregate-kpi.ts:53`, null skip `:60`
+- AST 계산기(재사용 대상): `server/calculator/parser.ts`, `evaluator.ts`, `functions.ts:4-67`
+- formula 검증 미흡: `server/service/kpi/kpi-formula.service.ts:33-65`
+- score/ grades deprecated: `server/service/kpi-value/kpi-value-score.service.ts:51`
+- metric 정의(버전/렌더힌트 부재): `server/service/kpi-metric/kpi-metric.ts:1-138`
+- metric value(버전 미스탬프): `server/service/kpi-metric-value/kpi-metric-value.ts:1-93`
+- scope 중복: `server/service/kpi-value/kpi-value.ts` (`group` vs `kpiOrgScope`)
+- 하드코딩 UI: `client/pages/kpi-metric-value/kpi-metric-value-manual-entry-form.ts`, `client/pages/kpi-value/kpi-value-editor-page.ts`
+- 이름 추측: `client/pages/kpi/kpi-list-page.ts:54-60`
+- alert 타입만: `server/service/kpi-alert/kpi-alert-type.ts:1-20`
+- 통계 N+1: `server/service/kpi-statistic/kpi-statistic-calculation.service.ts:154-210`
+- 스케줄(KPI만): `server/service/kpi/kpi-mutation.ts:76-110`

package/client/pages/kpi-metric/kpi-metric-list-page.ts

@@ -9,7 +9,7 @@ import { PageView } from '@operato/shell'
 import { css, html, PropertyValues } from 'lit'
 import { customElement, property, query, state } from 'lit/decorators.js'
 import { ScopedElementsMixin } from '@open-wc/scoped-elements'
-import { ColumnConfig, DataGrist, FetchOption } from '@operato/data-grist'
+import { ColumnConfig, DataGrist, FetchOption, registerEditor } from '@operato/data-grist'
 import { client } from '@operato/graphql'
 import { i18next, localize } from '@operato/i18n'
 import { notify, openPopup } from '@operato/layout'
@@ -20,6 +20,10 @@ import { p13n } from '@operato/p13n'
 import gql from 'graphql-tag'
 
 import { KpiMetricImporter } from './kpi-metric-importer'
+import { OxGristEditorMetricInputHint } from '../../viewparts/ox-grist-editor-metric-input-hint'
+
+// KpiMetric.meta 입력힌트 편집용 커스텀 grist 에디터 등록 (셀 클릭 → 구조화 팝업).
+registerEditor('metric-input-hint', OxGristEditorMetricInputHint)
 
 @customElement('kpi-metric-list-page')
 export class KpiMetricListPage extends p13n(localize(i18next)(ScopedElementsMixin(PageView))) {   static styles = [
@@ -205,6 +209,27 @@ export class KpiMetricListPage extends p13n(localize(i18next)(ScopedElementsMixi
  },
           width: 80
  },
+        {
+          type: 'metric-input-hint',
+          name: 'meta',
+          header: '입력힌트',
+          record: {
+            editable: true,
+            renderer: (v: any, c: any, r: any) => {
+              const input = r?.meta?.input
+              if (!input?.widget) return ''
+              const extra = [
+                input.max !== undefined ? `max ${input.max}` : '',
+                input.step !== undefined ? `step ${input.step}` : '',
+                input.readonly ? 'RO' : ''
+              ]
+                .filter(Boolean)
+                .join('·')
+              return extra ? `${input.widget} (${extra})` : input.widget
+            }
+          },
+          width: 150
+        },
         { type: 'integer', name: 'rank', header: '순서', sortable: true, record: { editable: true, align: 'center' }, width: 70 },
         { type: 'checkbox', name: 'active', label: true, header: '활성', record: { editable: true }, width: 60 },
         { type: 'crontab', name: 'schedule', header: '스케줄', record: { editable: true }, width: 120 },
@@ -247,6 +272,7 @@ export class KpiMetricListPage extends p13n(localize(i18next)(ScopedElementsMixi
               source
               collectType
               rank
+              meta
               dataSet {                 id
                 name
  }

package/client/viewparts/kpi-metric-input.ts

@@ -0,0 +1,130 @@
+import { html, css, LitElement, nothing } from 'lit'
+import { customElement, property } from 'lit/decorators.js'
+
+import { resolveInputHint, InputHint, KpiMetricLike } from './metric-input-hint'
+import { MetricRendererRegistry } from './metric-renderer-registry'
+
+/**
+ * metric 정의(meta.input)에 따라 입력 위젯을 **선언적으로 자동 렌더**하는 제네릭 컴포넌트.
+ * 이름 추측(isRating 등) 없이 `resolveInputHint` 로 위젯을 결정한다.
+ *
+ *   <kpi-metric-input .metric=${metric} .value=${v}
+ *      @metric-input-change=${e => (v = e.detail.value)}></kpi-metric-input>
+ *
+ * 예외 UI 는 MetricRendererRegistry 로 등록(제네릭 우선순위보다 먼저 적용).
+ */
+@customElement('kpi-metric-input')
+export class KpiMetricInput extends LitElement {
+  static styles = css`
+    :host {
+      display: inline-flex;
+      align-items: baseline;
+      gap: 2px;
+      font: 13px/18px var(--theme-font, sans-serif);
+    }
+    input,
+    select {
+      font: inherit;
+      padding: 2px 4px;
+    }
+    input[type='number'] {
+      width: 5em;
+      text-align: right;
+    }
+    .stars {
+      display: inline-flex;
+      cursor: pointer;
+      font-size: 18px;
+      line-height: 1;
+      color: var(--md-sys-color-primary, #2e79be);
+    }
+    .stars[readonly] {
+      cursor: default;
+      opacity: 0.85;
+    }
+    .star {
+      width: 1em;
+    }
+    .unit {
+      color: var(--md-sys-color-on-surface-variant, #888);
+      font-size: 11px;
+    }
+  `
+
+  @property({ type: Object }) metric: KpiMetricLike = {}
+  @property() value: any
+  /** 상위에서 강제 비활성화(권한 등). readonly 힌트와 별개. */
+  @property({ type: Boolean }) disabled = false
+
+  private _emit(value: any) {
+    this.value = value
+    this.dispatchEvent(new CustomEvent('metric-input-change', { detail: { value }, bubbles: true, composed: true }))
+  }
+
+  render() {
+    const custom = MetricRendererRegistry.resolve(this.metric)
+    if (custom) return custom(this.metric, this.value, v => this._emit(v))
+
+    const hint = resolveInputHint(this.metric)
+    const ro = this.disabled || !!hint.readonly
+    const unit = (this.metric as any)?.unit
+
+    // 값(우측정렬) 바로 옆에 단위 — 값이 단위에 붙어 자연스럽게. (rating/toggle 등엔 unit 보통 없음)
+    return html`
+      ${this._renderWidget(hint, ro)}${unit ? html`<span class="unit">${unit}</span>` : nothing}
+    `
+  }
+
+  private _renderWidget(hint: InputHint, ro: boolean) {
+    switch (hint.widget) {
+      case 'rating':
+        return this._renderRating(hint, ro)
+      case 'select':
+        return this._renderSelect(hint, ro)
+      case 'date':
+        return html`<input type="date" .value=${this.value ?? ''} ?disabled=${ro}
+          @change=${(e: Event) => this._emit((e.target as HTMLInputElement).value)} />`
+      case 'toggle':
+        return html`<input type="checkbox" .checked=${!!this.value} ?disabled=${ro}
+          @change=${(e: Event) => this._emit((e.target as HTMLInputElement).checked)} />`
+      case 'text':
+        return html`<input type="text" .value=${this.value ?? ''} ?disabled=${ro}
+          placeholder=${hint.placeholder ?? ''} @input=${(e: Event) => this._emit((e.target as HTMLInputElement).value)} />`
+      case 'number':
+      default:
+        return html`<input type="number" .value=${this.value ?? ''} ?disabled=${ro}
+          min=${hint.min ?? nothing} max=${hint.max ?? nothing} step=${hint.step ?? nothing}
+          placeholder=${hint.placeholder ?? ''}
+          @input=${(e: Event) => {
+            const raw = (e.target as HTMLInputElement).value
+            this._emit(raw === '' ? null : Number(raw))
+          }} />`
+    }
+  }
+
+  private _renderRating(hint: InputHint, ro: boolean) {
+    const max = hint.max ?? 5
+    const score = Number(this.value ?? 0)
+    const stars = Array.from({ length: max }, (_, idx) => {
+      const i = idx + 1
+      const filled = i <= Math.round(score)
+      return html`<span class="star" @click=${() => (ro ? null : this._emit(i))}>${filled ? '★' : '☆'}</span>`
+    })
+    return html`<span class="stars" ?readonly=${ro} title=${`${score}/${max}`}>${stars}</span>`
+  }
+
+  private _renderSelect(hint: InputHint, ro: boolean) {
+    const options = hint.options ?? []
+    return html`<select ?disabled=${ro} @change=${(e: Event) => {
+      const raw = (e.target as HTMLSelectElement).value
+      // 옵션의 원래 타입(숫자 등)을 보존해 방출 — 문자열 강제 방지.
+      const opt = options.find(o => String(o.value) === raw)
+      this._emit(raw === '' ? null : opt ? opt.value : raw)
+    }}>
+      <option value="" ?selected=${this.value == null || this.value === ''}>-</option>
+      ${options.map(
+        o => html`<option value=${o.value} ?selected=${String(this.value) === String(o.value)}>${o.label}</option>`
+      )}
+    </select>`
+  }
+}

package/client/viewparts/kpi-metric-meta-editor.ts

@@ -0,0 +1,277 @@
+import '@material/web/icon/icon.js'
+
+import { css, html, LitElement } from 'lit'
+import { customElement, property, state } from 'lit/decorators.js'
+import { CommonHeaderStyles } from '@operato/styles'
+
+/**
+ * KpiMetric.meta.input(입력 위젯 힌트) 구조화 에디터.
+ *
+ * metric 관리 화면(kpi-metric-list-page)에서 팝업으로 열려 meta.input 을 편집한다.
+ * raw JSON 을 직접 만지지 않고 위젯/필드를 폼으로 구성 → 내부적으로 meta 객체 생성.
+ * meta 의 다른 키(kind/source…)는 보존하고 input 만 교체/삭제한다.
+ *
+ *  - `metric-meta-save`  detail:{ meta } — 저장 (widget 미선택 시 input 제거된 meta)
+ *  - `metric-meta-cancel`               — 취소
+ */
+@customElement('kpi-metric-meta-editor')
+export class KpiMetricMetaEditor extends LitElement {
+  static styles = [
+    CommonHeaderStyles,
+    css`
+      :host {
+        display: flex;
+        flex-direction: column;
+        height: 100%;
+        box-sizing: border-box;
+        width: 100%;
+        min-width: 520px;
+        font-size: 14px;
+        color: #212529;
+      }
+      /* 스크롤되는 내용부 — 버튼은 아래에 고정 (kpi-metric-value-manual-entry-form 패턴) */
+      .content {
+        flex: 1;
+        overflow-y: auto;
+        padding: 20px 24px 8px 24px;
+      }
+      h3 {
+        margin: 0 0 4px 0;
+        font-size: 15px;
+      }
+      .sub {
+        color: #6b7684;
+        margin-bottom: 14px;
+      }
+      .field {
+        display: grid;
+        grid-template-columns: 96px 1fr;
+        align-items: center;
+        gap: 8px 10px;
+        margin-bottom: 10px;
+      }
+      label {
+        color: #35618e;
+        font-weight: 500;
+      }
+      input[type='text'],
+      input[type='number'],
+      select,
+      textarea {
+        width: 100%;
+        box-sizing: border-box;
+        padding: 6px 8px;
+        border: 1px solid #cdd5df;
+        border-radius: 5px;
+        font-size: 13px;
+      }
+      textarea {
+        min-height: 72px;
+        resize: vertical;
+        font-family: monospace;
+      }
+      .checks {
+        display: flex;
+        gap: 16px;
+        flex-wrap: wrap;
+        margin: 4px 0 12px 0;
+      }
+      .checks label {
+        display: inline-flex;
+        align-items: center;
+        gap: 5px;
+        color: #212529;
+        font-weight: 400;
+      }
+      .hint {
+        color: #8b95a1;
+        font-size: 11px;
+        grid-column: 2;
+        margin-top: -4px;
+      }
+    `
+  ]
+
+  /** { name, meta, collectType } */
+  @property({ type: Object }) metric: any = {}
+
+  @state() widget = ''
+  @state() min = ''
+  @state() max = ''
+  @state() step = ''
+  @state() decimals = ''
+  @state() placeholder = ''
+  @state() optionsText = ''
+  @state() readonly = false
+  @state() required = false
+  @state() hasPlan = false
+
+  connectedCallback() {
+    super.connectedCallback()
+    const input = this.metric?.meta?.input || {}
+    this.widget = input.widget || ''
+    this.min = input.min !== undefined ? String(input.min) : ''
+    this.max = input.max !== undefined ? String(input.max) : ''
+    this.step = input.step !== undefined ? String(input.step) : ''
+    this.decimals = input.decimals !== undefined ? String(input.decimals) : ''
+    this.placeholder = input.placeholder || ''
+    this.optionsText = (input.options || []).map((o: any) => `${o.value}|${o.label ?? o.value}`).join('\n')
+    this.readonly = !!input.readonly
+    this.required = !!input.required
+    this.hasPlan = !!input.hasPlan
+  }
+
+  render() {
+    const w = this.widget
+    return html`
+      <div class="content">
+      <h3>입력 힌트 · ${this.metric?.name || ''}</h3>
+      <div class="sub">값 입력 화면(월별/완료평가 등)이 이 힌트로 위젯을 그립니다. 위젯을 비우면 힌트가 제거되어 숫자 입력으로 폴백합니다.</div>
+
+      <div class="field">
+        <label>위젯</label>
+        <select .value=${w} @change=${(e: any) => (this.widget = e.target.value)}>
+          <option value="">(자동/폴백 — 숫자)</option>
+          <option value="number" ?selected=${w === 'number'}>number — 숫자</option>
+          <option value="rating" ?selected=${w === 'rating'}>rating — 별점</option>
+          <option value="select" ?selected=${w === 'select'}>select — 선택목록</option>
+          <option value="toggle" ?selected=${w === 'toggle'}>toggle — 스위치</option>
+          <option value="text" ?selected=${w === 'text'}>text — 텍스트</option>
+          <option value="date" ?selected=${w === 'date'}>date — 날짜</option>
+        </select>
+      </div>
+
+      ${w === 'number' || w === 'rating'
+        ? html`
+            ${w === 'number'
+              ? html`<div class="field">
+                  <label>최소</label>
+                  <input type="number" .value=${this.min} @input=${(e: any) => (this.min = e.target.value)} />
+                </div>`
+              : ''}
+            <div class="field">
+              <label>최대</label>
+              <input type="number" .value=${this.max} @input=${(e: any) => (this.max = e.target.value)} />
+              ${w === 'rating' ? html`<span class="hint">별 개수 (기본 5)</span>` : ''}
+            </div>
+            <div class="field">
+              <label>스텝</label>
+              <input type="number" .value=${this.step} @input=${(e: any) => (this.step = e.target.value)} />
+              ${w === 'rating' ? html`<span class="hint">1=정수, 0.5=반별 (기본 1)</span>` : ''}
+            </div>
+            ${w === 'number'
+              ? html`<div class="field">
+                  <label>소수자리</label>
+                  <input type="number" .value=${this.decimals} @input=${(e: any) => (this.decimals = e.target.value)} />
+                </div>`
+              : ''}
+          `
+        : ''}
+      ${w === 'select'
+        ? html`
+            <div class="field">
+              <label>옵션</label>
+              <textarea
+                .value=${this.optionsText}
+                placeholder="한 줄에 하나: 값|표시라벨&#10;예) 1|양호&#10;2|보통"
+                @input=${(e: any) => (this.optionsText = e.target.value)}
+              ></textarea>
+              <span class="hint">한 줄당 <code>값|라벨</code> (라벨 생략 시 값 사용)</span>
+            </div>
+          `
+        : ''}
+      ${w === 'text'
+        ? html`<div class="field">
+            <label>placeholder</label>
+            <input type="text" .value=${this.placeholder} @input=${(e: any) => (this.placeholder = e.target.value)} />
+          </div>`
+        : ''}
+
+      ${w
+        ? html`<div class="checks">
+            <label><input type="checkbox" .checked=${this.readonly} @change=${(e: any) => (this.readonly = e.target.checked)} /> 읽기전용</label>
+            <label><input type="checkbox" .checked=${this.required} @change=${(e: any) => (this.required = e.target.checked)} /> 필수</label>
+            <label><input type="checkbox" .checked=${this.hasPlan} @change=${(e: any) => (this.hasPlan = e.target.checked)} /> 계획/실제 2열</label>
+          </div>`
+        : ''}
+      </div>
+
+      <div class="footer">
+        ${this.metric?.meta?.input
+          ? html`<button danger @click=${this._clear}><md-icon>delete</md-icon>힌트 삭제</button>`
+          : ''}
+        <div filler></div>
+        <button @click=${this._cancel}><md-icon>cancel</md-icon>취소</button>
+        <button done @click=${this._save}><md-icon>done</md-icon>저장</button>
+      </div>
+    `
+  }
+
+  private _num(v: string): number | undefined {
+    if (v === '' || v === null || v === undefined) return undefined
+    const n = Number(v)
+    return Number.isNaN(n) ? undefined : n
+  }
+
+  private _buildInput(): any {
+    if (!this.widget) return undefined
+    const input: any = { widget: this.widget }
+
+    if (this.widget === 'number' || this.widget === 'rating') {
+      const min = this._num(this.min)
+      const max = this._num(this.max)
+      const step = this._num(this.step)
+      const decimals = this._num(this.decimals)
+      if (this.widget === 'number' && min !== undefined) input.min = min
+      if (max !== undefined) input.max = max
+      if (step !== undefined) input.step = step
+      if (this.widget === 'number' && decimals !== undefined) input.decimals = decimals
+    }
+
+    if (this.widget === 'select') {
+      const options = this.optionsText
+        .split('\n')
+        .map(line => line.trim())
+        .filter(Boolean)
+        .map(line => {
+          const [value, label] = line.split('|').map(s => s.trim())
+          return { value, label: label || value }
+        })
+      if (options.length) input.options = options
+    }
+
+    if (this.widget === 'text' && this.placeholder) input.placeholder = this.placeholder
+
+    if (this.readonly) input.readonly = true
+    if (this.required) input.required = true
+    if (this.hasPlan) input.hasPlan = true
+
+    return input
+  }
+
+  /** 기존 meta 는 보존하고 input 만 교체(또는 삭제). */
+  private _buildMeta(): any {
+    const rest = { ...(this.metric?.meta || {}) }
+    delete rest.input
+    const input = this._buildInput()
+    const meta = input ? { ...rest, input } : rest
+    return Object.keys(meta).length ? meta : null
+  }
+
+  private _save() {
+    this.dispatchEvent(
+      new CustomEvent('metric-meta-save', { detail: { meta: this._buildMeta() }, bubbles: true, composed: true })
+    )
+  }
+
+  private _clear() {
+    this.widget = ''
+    this.dispatchEvent(
+      new CustomEvent('metric-meta-save', { detail: { meta: this._buildMeta() }, bubbles: true, composed: true })
+    )
+  }
+
+  private _cancel() {
+    this.dispatchEvent(new CustomEvent('metric-meta-cancel', { bubbles: true, composed: true }))
+  }
+}

package/client/viewparts/metric-input-hint.ts

@@ -0,0 +1,41 @@
+// 클라이언트용 InputHint 타입 + resolveInputHint.
+//
+// ⚠️ 원본(진실의 원천): server/service/kpi-metric/kpi-metric-meta.ts
+//    client/server tsconfig 가 분리되어 server 를 import 할 수 없어 동형 복제한다.
+//    변경 시 양쪽을 함께 수정할 것.
+
+export type InputWidget = 'number' | 'rating' | 'select' | 'date' | 'text' | 'toggle'
+
+export interface InputHint {
+  widget: InputWidget
+  min?: number
+  max?: number
+  step?: number
+  options?: { value: string | number; label: string }[]
+  required?: boolean
+  decimals?: number
+  readonly?: boolean
+  hasPlan?: boolean
+  placeholder?: string
+  default?: any
+}
+
+export interface KpiMetricLike {
+  meta?: { input?: InputHint; [k: string]: any } | null
+  collectType?: string
+}
+
+/** meta.input 우선, 없으면 number 폴백(이름추측 금지). readonly 는 명시값 우선, 미지정+AUTO 면 true. */
+export function resolveInputHint(metric: KpiMetricLike | null | undefined): InputHint {
+  const isAuto = metric?.collectType === 'AUTO'
+  const hint = metric?.meta?.input
+
+  if (hint?.widget) {
+    const readonly = hint.readonly ?? isAuto
+    if (hint.widget === 'rating') {
+      return { ...hint, max: hint.max ?? 5, step: hint.step ?? 1, readonly }
+    }
+    return { ...hint, readonly }
+  }
+  return { widget: 'number', readonly: isAuto }
+}