@things-factory/kpi 9.0.21 → 9.0.23

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

@@ -5,7 +5,7 @@ import { ObjectType, Field, InputType, Int, ID, registerEnumType } from 'type-gr
 import { ObjectRef, ScalarObject } from '@things-factory/shell'
 
 import { Kpi, KpiStatus, KpiVizType } from './kpi'
-import { KpiGrades } from './kpi-grade.types'
+import { KpiScores } from './kpi-grade.types'
 
 @InputType({ description: 'Input type for creating a new KPI. Used in mutations to provide KPI details.' })
 export class NewKpi {
@@ -15,8 +15,8 @@ export class NewKpi {
   @Field({ nullable: true, description: 'Detailed description of the KPI.' })
   description?: string
 
-  @Field(type => ID, { nullable: true, description: 'ID of the category to which this KPI belongs.' })
-  categoryId?: string
+  @Field(type => ObjectRef, { nullable: true, description: 'Reference to the category to which this KPI belongs.' })
+  category?: ObjectRef
 
   @Field({ nullable: true, description: 'Calculation formula for the KPI, using metric codes and operators.' })
   formula?: string
@@ -57,9 +57,15 @@ export class NewKpi {
 
   @Field(type => ScalarObject, {
     nullable: true,
-    description: 'Grade configuration for this KPI version'
+    description: 'Score lookup table for this KPI version'
   })
-  grades?: KpiGrades
+  grades?: KpiScores
+
+  @Field({
+    nullable: true,
+    description: 'Score calculation formula for this KPI. Converts KPI value to performance score (0-1).'
+  })
+  scoreFormula?: string
 }
 
 @InputType({ description: 'Input type for updating an existing KPI. Used in mutations to patch KPI details.' })
@@ -73,8 +79,8 @@ export class KpiPatch {
   @Field({ nullable: true, description: 'Detailed description of the KPI.' })
   description?: string
 
-  @Field(type => ID, { nullable: true, description: 'ID of the category to which this KPI belongs.' })
-  categoryId?: string
+  @Field(type => ObjectRef, { nullable: true, description: 'Reference to the category to which this KPI belongs.' })
+  category?: ObjectRef
 
   @Field({ nullable: true, description: 'Calculation formula for the KPI, using metric codes and operators.' })
   formula?: string
@@ -118,9 +124,15 @@ export class KpiPatch {
 
   @Field(type => ScalarObject, {
     nullable: true,
-    description: 'Grade configuration for this KPI version'
+    description: 'Score lookup table for this KPI version'
+  })
+  grades?: KpiScores
+
+  @Field({
+    nullable: true,
+    description: 'Score calculation formula for this KPI. Converts KPI value to performance score (0-1).'
   })
-  grades?: KpiGrades
+  scoreFormula?: string
 }
 
 @ObjectType()

package/server/service/kpi/kpi.ts

@@ -19,7 +19,7 @@ import { KpiCategory } from '../kpi-category/kpi-category'
 import { config } from '@things-factory/env'
 import { ScalarObject } from '@things-factory/shell'
 
-import { KpiGrades } from './kpi-grade.types'
+import { KpiScores } from './kpi-grade.types'
 
 const ORMCONFIG = config.get('ormconfig', {})
 const DATABASE_TYPE = ORMCONFIG.type
@@ -53,7 +53,9 @@ export enum KpiPeriodType {
   WEEK = 'WEEK',
   MONTH = 'MONTH',
   QUARTER = 'QUARTER',
-  RANGE = 'RANGE'
+  YEAR = 'YEAR',
+  RANGE = 'RANGE',
+  ALLTIME = 'ALLTIME'
 }
 
 registerEnumType(KpiStatus, {
@@ -68,7 +70,7 @@ registerEnumType(KpiVizType, {
 
 registerEnumType(KpiPeriodType, {
   name: 'KpiPeriodType',
-  description: 'Aggregation period type for KPI (DAY, WEEK, MONTH, QUARTER, RANGE)'
+  description: 'Aggregation period type for KPI (DAY, WEEK, MONTH, QUARTER, RANGE, ALLTIME)'
 })
 
 @Entity()
@@ -182,6 +184,33 @@ export class Kpi {
   @Field({ nullable: true, description: 'Weight for aggregation in parent category.' })
   weight?: number
 
+  @Column({ type: 'simple-json', nullable: true })
+  @Field(type => ScalarObject, {
+    nullable: true,
+    description:
+      'Performance index lookup table for complex transformations. @deprecated 향후 제거 예정. performanceFormula 사용 권장.'
+  })
+  grades?: KpiScores
+
+  @Column({
+    nullable: true,
+    type:
+      DATABASE_TYPE == 'mysql' || DATABASE_TYPE == 'mariadb'
+        ? 'longtext'
+        : DATABASE_TYPE == 'oracle'
+          ? 'clob'
+          : DATABASE_TYPE == 'mssql'
+            ? 'nvarchar'
+            : 'varchar',
+    length: DATABASE_TYPE == 'mssql' ? 'MAX' : undefined
+  })
+  @Field({
+    nullable: true,
+    description:
+      'Score calculation formula for this KPI. Converts KPI value to performance score (0-100). For complex mappings, use grades lookup table instead. Example: "if(value >= 90, 100, if(value >= 80, 85, 70))" or "value * 0.8 + 20"'
+  })
+  scoreFormula?: string
+
   @CreateDateColumn()
   @Field({ nullable: true, description: 'Timestamp when this KPI was created.' })
   createdAt?: Date
@@ -212,11 +241,4 @@ export class Kpi {
 
   @Field(type => String, { nullable: true, description: 'Thumbnail image or file path for this KPI.' })
   thumbnail?: string
-
-  @Column({ type: 'simple-json', nullable: true })
-  @Field(type => ScalarObject, {
-    nullable: true,
-    description: 'Grade configuration for this KPI version'
-  })
-  grades?: KpiGrades
 }

package/server/service/kpi-category/kpi-category-mutation.ts

@@ -10,14 +10,14 @@ export class KpiCategoryMutation {
   @Directive('@transaction')
   @Mutation(returns => KpiCategory, { description: 'Create a new KPI category with the provided details.' })
   async createKpiCategory(
-    @Arg('category', { description: 'Input object containing details for the new KPI category.' })
-    category: NewKpiCategory,
+    @Arg('kpiCategory', { description: 'Input object containing details for the new KPI category.' })
+    kpiCategory: NewKpiCategory,
     @Ctx() context: ResolverContext
   ): Promise<KpiCategory> {
     const { domain, user, tx } = context.state
 
     const result = await getRepository(KpiCategory, tx).save({
-      ...category,
+      ...kpiCategory,
       domain,
       creator: user,
       updater: user

package/server/service/kpi-category/kpi-category-query.ts

@@ -1,9 +1,44 @@
-import { Resolver, Query, FieldResolver, Root, Args, Arg, Ctx, Directive } from 'type-graphql'
+import { Resolver, Query, FieldResolver, Float, Root, Args, Arg, Ctx, Directive, ObjectType, Field } from 'type-graphql'
 import { Domain, getQueryBuilderFromListParams, getRepository, ListParam } from '@things-factory/shell'
 import { User } from '@things-factory/auth-base'
 import { KpiCategory } from './kpi-category'
 import { KpiCategoryList } from './kpi-category-type'
 import { Kpi } from '../kpi/kpi'
+import { KpiValue } from '../kpi-value/kpi-value'
+import { parseFormula } from '../../calculator/parser'
+import { evaluateFormula } from '../../calculator/evaluator'
+import { builtinFunctions } from '../../calculator/functions'
+import { KpiValueProvider } from '../../controllers/kpi-value-provider'
+import { getDefaultValueDate } from '../utils/value-date-util'
+import { KpiPeriodType } from '../kpi/kpi'
+import { KpiValueScoreService } from '../kpi-value/kpi-value-score.service'
+
+@ObjectType()
+class KpiValueItem {
+  @Field()
+  kpiId: string
+
+  @Field(type => Float, { nullable: true })
+  value: number
+}
+
+@ObjectType()
+class KpiCategoryValueResult {
+  @Field(type => Float, { nullable: true })
+  value?: number
+
+  @Field(type => Float, { nullable: true, description: 'Performance score for this category (0-1 range)' })
+  score?: number
+
+  @Field({ nullable: true })
+  valueDate?: string
+
+  @Field({ nullable: true })
+  group?: string
+
+  @Field(type => [KpiValueItem])
+  kpiValues: KpiValueItem[]
+}
 
 @Resolver(KpiCategory)
 export class KpiCategoryQuery {
@@ -41,6 +76,145 @@ export class KpiCategoryQuery {
     return { items, total }
   }
 
+  @Query(returns => KpiCategoryValueResult, { description: '카테고리 단위 KPI 실적값 집계/조회' })
+  async calculateKpiValue(
+    @Arg('categoryId') categoryId: string,
+    @Arg('valueDate', { nullable: true }) valueDate: string,
+    @Arg('group', { nullable: true }) group: string,
+    @Ctx() context: ResolverContext
+  ): Promise<KpiCategoryValueResult> {
+    const { domain, tx } = context.state
+    // 1. 카테고리 정보 조회 (formula 포함)
+    const category = await getRepository(KpiCategory).findOne({
+      where: { domain: { id: domain.id }, id: categoryId }
+    })
+    if (!category) return { value: null, score: null, kpiValues: [] }
+
+    // 기본 계산 기준일 설정 (카테고리 periodType 사용)
+    const defaultDate = valueDate || getDefaultValueDate(category.periodType || KpiPeriodType.DAY, 'last')
+
+    // 2. 카테고리 formula가 있으면 formula로 계산
+    if (category.formula) {
+      const ast = parseFormula(category.formula)
+      const provider = new KpiValueProvider({
+        valueDate: defaultDate,
+        group,
+        domainId: domain.id,
+        tx
+      })
+      const evalContext = { functions: builtinFunctions, provider }
+      const value = await evaluateFormula(ast, evalContext)
+      // 카테고리 formula 결과를 score로 변환 (0-1 범위)
+      const score = value !== null && value !== undefined && !isNaN(value) ? Math.max(0, Math.min(1, value)) : null
+
+      return {
+        value,
+        score,
+        valueDate: defaultDate,
+        group,
+        kpiValues: [] // 카테고리 formula 기반이므로 개별 KPI 값은 제공하지 않음
+      }
+    }
+
+    // 3. formula가 없으면 KPI score들의 가중 평균으로 category score 계산
+    const kpis = await getRepository(Kpi).find({
+      where: { domain: { id: domain.id }, category: { id: categoryId } }
+    })
+    if (!kpis.length) return { value: null, score: null, kpiValues: [] }
+
+    let totalWeight = 0
+    let weightedScoreSum = 0
+    const kpiValues: KpiValueItem[] = []
+
+    for (const kpi of kpis) {
+      // KPI value 계산
+      let value = null
+      if (kpi.formula) {
+        const ast = parseFormula(kpi.formula)
+        const provider = new KpiValueProvider({
+          valueDate: defaultDate,
+          group,
+          domainId: domain.id,
+          tx
+        })
+        const evalContext = { functions: builtinFunctions, provider }
+        value = await evaluateFormula(ast, evalContext)
+      } else {
+        const kpiValue = await getRepository(KpiValue).findOne({
+          where: {
+            kpi: { id: kpi.id },
+            valueDate: defaultDate,
+            group: group ?? '',
+            domain: { id: domain.id }
+          }
+        })
+        value = kpiValue?.value ?? 0
+      }
+
+      // KPI score 계산
+      const scoreService = new KpiValueScoreService()
+      let kpiScore = null
+      if (value !== null && value !== undefined) {
+        let scoreResult = await scoreService.calculateScoreFromFormula(kpi, value)
+        if (!scoreResult) {
+          scoreResult = scoreService.calculateScoreFromLookup(kpi, value)
+        }
+        kpiScore = scoreResult?.score ?? null
+      }
+
+      const weight = kpi.weight ?? 1
+      if (kpiScore !== null) {
+        weightedScoreSum += kpiScore * weight
+        totalWeight += weight
+      }
+
+      kpiValues.push({ kpiId: kpi.id, value })
+    }
+
+    // category score 계산 (KPI score들의 가중 평균)
+    const categoryScore = totalWeight ? weightedScoreSum / totalWeight : null
+
+    // category value는 기존 방식대로 계산 (호환성 유지)
+    let totalValueWeight = 0
+    let weightedValueSum = 0
+    for (const kpi of kpis) {
+      let value = null
+      if (kpi.formula) {
+        const ast = parseFormula(kpi.formula)
+        const provider = new KpiValueProvider({
+          valueDate: defaultDate,
+          group,
+          domainId: domain.id,
+          tx
+        })
+        const evalContext = { functions: builtinFunctions, provider }
+        value = await evaluateFormula(ast, evalContext)
+      } else {
+        const kpiValue = await getRepository(KpiValue).findOne({
+          where: {
+            kpi: { id: kpi.id },
+            valueDate: defaultDate,
+            group: group ?? '',
+            domain: { id: domain.id }
+          }
+        })
+        value = kpiValue?.value ?? 0
+      }
+      const weight = kpi.weight ?? 1
+      weightedValueSum += (value ?? 0) * weight
+      totalValueWeight += weight
+    }
+    const resultValue = totalValueWeight ? weightedValueSum / totalValueWeight : null
+
+    return {
+      value: resultValue,
+      score: categoryScore,
+      valueDate: defaultDate,
+      group,
+      kpiValues
+    }
+  }
+
   @FieldResolver(type => [Kpi])
   async kpis(@Root() kpiCategory: KpiCategory): Promise<Kpi[]> {
     return await getRepository(Kpi).find({

package/server/service/kpi-category/kpi-category-type.ts

@@ -1,10 +1,7 @@
-import type { FileUpload } from 'graphql-upload/GraphQLUpload.js'
-import GraphQLUpload from 'graphql-upload/GraphQLUpload.js'
-import { ObjectType, Field, InputType, Int, ID, registerEnumType } from 'type-graphql'
-
-import { ObjectRef, ScalarObject } from '@things-factory/shell'
+import { ObjectType, Field, InputType, Int, ID } from 'type-graphql'
 
 import { KpiCategory } from './kpi-category'
+import { KpiPeriodType } from '../kpi/kpi'
 
 @InputType({
   description: 'Input type for creating a new KPI category. Used in mutations to provide category details.'
@@ -24,6 +21,13 @@ export class NewKpiCategory {
 
   @Field({ nullable: true, description: 'Weight for aggregation in higher-level summary.' })
   weight?: number
+
+  @Field(type => KpiPeriodType, {
+    nullable: true,
+    description:
+      'Calculation formula for category score using KPI score variables. Example: "avg(sales_score, profit_score)" or "sales_score * 0.6 + profit_score * 0.4". If not provided, weighted average of child KPI scores will be used.'
+  })
+  periodType?: KpiPeriodType
 }
 
 @InputType({
@@ -42,12 +46,19 @@ export class KpiCategoryPatch {
   @Field({ nullable: true, description: 'Whether this category is active (usable) or not.' })
   active?: boolean
 
-  @Field({ nullable: true, description: 'Aggregation formula using child KPI codes.' })
+  @Field({
+    nullable: true,
+    description:
+      'Calculation formula for category score using KPI score variables. Example: "avg(sales_score, profit_score)" or "sales_score * 0.6 + profit_score * 0.4". If not provided, weighted average of child KPI scores will be used.'
+  })
   formula?: string
 
   @Field({ nullable: true, description: 'Weight for aggregation in higher-level summary.' })
   weight?: number
 
+  @Field(type => KpiPeriodType, { nullable: true, description: 'Aggregation period type for this category.' })
+  periodType?: KpiPeriodType
+
   @Field({ nullable: true, description: 'Custom flag for update operations (internal use).' })
   cuFlag?: string
 }

package/server/service/kpi-category/kpi-category.ts

@@ -14,6 +14,7 @@ import { ObjectType, Field, Int, ID } from 'type-graphql'
 import { Domain } from '@things-factory/shell'
 import { User } from '@things-factory/auth-base'
 import { Kpi } from '../kpi/kpi'
+import { KpiPeriodType } from '../kpi/kpi'
 
 @Entity()
 @Index('ix_kpi_category_0', (kpiCategory: KpiCategory) => [kpiCategory.domain, kpiCategory.name], {
@@ -49,13 +50,21 @@ export class KpiCategory {
   active?: boolean
 
   @Column({ nullable: true })
-  @Field({ nullable: true, description: 'Aggregation formula using child KPI codes.' })
+  @Field({
+    nullable: true,
+    description:
+      'Calculation formula for category score using KPI score variables. Example: "avg(sales_score, profit_score)" or "sales_score * 0.6 + profit_score * 0.4". If not provided, weighted average of child KPI scores will be used.'
+  })
   formula?: string
 
   @Column({ type: 'float', nullable: true, default: 1 })
   @Field({ nullable: true, description: 'Weight for aggregation in higher-level summary.' })
   weight?: number
 
+  @Column({ default: 'DAY' })
+  @Field(type => KpiPeriodType, { description: 'Aggregation period type for this category.' })
+  periodType: KpiPeriodType
+
   @ManyToOne(type => User, { nullable: true })
   @Field(type => User, { nullable: true, description: 'User who created this KPI category.' })
   creator?: User

package/server/service/kpi-metric/kpi-metric-type.ts

@@ -2,7 +2,9 @@ import type { FileUpload } from 'graphql-upload/GraphQLUpload.js'
 import GraphQLUpload from 'graphql-upload/GraphQLUpload.js'
 import { ObjectType, Field, InputType, Int, ID, registerEnumType } from 'type-graphql'
 
-import { KpiMetric, KpiMetricPeriodType, KpiMetricCollectType } from './kpi-metric'
+import { KpiPeriodType } from '../kpi/kpi'
+import { KpiMetricCollectType } from './kpi-metric'
+import { KpiMetric } from './kpi-metric'
 
 @InputType({ description: 'Input type for creating a new KPI metric. Used in mutations to provide metric details.' })
 export class NewKpiMetric {
@@ -41,8 +43,8 @@ export class NewKpiMetric {
   @Field({ nullable: true, description: 'Schedule ID for the registered cron job.' })
   scheduleId?: string
 
-  @Field(type => KpiMetricPeriodType, { nullable: true, description: 'Aggregation period type for this metric.' })
-  periodType?: KpiMetricPeriodType
+  @Field(type => KpiPeriodType, { nullable: true, description: 'Aggregation period type for this metric.' })
+  periodType?: KpiPeriodType
 
   @Field(type => KpiMetricCollectType, { nullable: true, description: '데이터 수집 방식' })
   collectType?: KpiMetricCollectType
@@ -89,8 +91,8 @@ export class KpiMetricPatch {
   @Field({ nullable: true, description: 'Schedule ID for the registered cron job.' })
   scheduleId?: string
 
-  @Field(type => KpiMetricPeriodType, { nullable: true, description: 'Aggregation period type for this metric.' })
-  periodType?: KpiMetricPeriodType
+  @Field(type => KpiPeriodType, { nullable: true, description: 'Aggregation period type for this metric.' })
+  periodType?: KpiPeriodType
 
   @Field({ nullable: true })
   cuFlag?: string

package/server/service/kpi-metric/kpi-metric.ts

@@ -14,19 +14,7 @@ import { ObjectType, Field, Int, ID, registerEnumType } from 'type-graphql'
 import { Domain } from '@things-factory/shell'
 import { User } from '@things-factory/auth-base'
 import { DataSet } from '@things-factory/dataset'
-
-export enum KpiMetricPeriodType {
-  DAY = 'DAY',
-  WEEK = 'WEEK',
-  MONTH = 'MONTH',
-  QUARTER = 'QUARTER',
-  RANGE = 'RANGE'
-}
-
-registerEnumType(KpiMetricPeriodType, {
-  name: 'KpiMetricPeriodType',
-  description: 'Aggregation period type for metric (DAY, WEEK, MONTH, QUARTER, RANGE)'
-})
+import { KpiPeriodType } from '../kpi/kpi'
 
 export enum KpiMetricCollectType {
   AUTO = 'AUTO', // 데이터셋 등 자동 수집
@@ -110,8 +98,8 @@ export class KpiMetric {
   collectType: KpiMetricCollectType
 
   @Column({ default: 'DAY' })
-  @Field(type => KpiMetricPeriodType, { description: 'Aggregation period type for this metric.' })
-  periodType: KpiMetricPeriodType
+  @Field(type => KpiPeriodType, { description: 'Aggregation period type for this metric.' })
+  periodType: KpiPeriodType
 
   @CreateDateColumn()
   @Field({ nullable: true, description: 'Timestamp when this KPI metric was created.' })

package/server/service/kpi-metric-value/kpi-metric-value-mutation.ts

@@ -8,37 +8,7 @@ import { KpiMetricValue } from './kpi-metric-value'
 import { NewKpiMetricValue, KpiMetricValuePatch } from './kpi-metric-value-type'
 import { KpiMetric } from '../kpi-metric/kpi-metric'
 import { ScalarObject } from '@things-factory/shell'
-
-function getISOWeek(date: Date): number {
-  const tmp = new Date(date.getTime())
-  tmp.setHours(0, 0, 0, 0)
-  tmp.setDate(tmp.getDate() + 4 - (tmp.getDay() || 7))
-  const yearStart = new Date(tmp.getFullYear(), 0, 1)
-  const weekNo = Math.ceil(((tmp.getTime() - yearStart.getTime()) / 86400000 + 1) / 7)
-  return weekNo
-}
-
-function getDefaultValueDate(periodType: KpiPeriodType): string {
-  const now = new Date()
-  switch (periodType) {
-    case KpiPeriodType.DAY:
-      return now.toISOString().slice(0, 10)
-    case KpiPeriodType.MONTH:
-      return now.toISOString().slice(0, 7)
-    case KpiPeriodType.QUARTER: {
-      const year = now.getFullYear()
-      const quarter = Math.floor(now.getMonth() / 3) + 1
-      return `${year}-Q${quarter}`
-    }
-    case KpiPeriodType.WEEK: {
-      const year = now.getFullYear()
-      const week = getISOWeek(now)
-      return `${year}-W${week}`
-    }
-    default:
-      return now.toISOString().slice(0, 10)
-  }
-}
+import { getDefaultValueDate } from '../utils/value-date-util'
 
 @Resolver(KpiMetricValue)
 export class KpiMetricValueMutation {
@@ -55,11 +25,26 @@ export class KpiMetricValueMutation {
       ? await getRepository(KpiMetric).findOne({ where: { id: metricValue.metricId } })
       : undefined
 
+    // valueDate 자동 생성/보정 로직 추가
+    let periodType = metricValue.periodType
+    if (!periodType && metric) {
+      periodType = metric.periodType
+    }
+    if (!periodType) {
+      periodType = KpiPeriodType.DAY
+    }
+    // periodType을 string으로 변환 후 KpiPeriodType으로 강제 변환
+    periodType = KpiPeriodType[String(periodType) as keyof typeof KpiPeriodType]
+    let valueDate = metricValue.valueDate
+    if (!valueDate || !isValueDateValidForPeriodType(valueDate, periodType)) {
+      valueDate = getDefaultValueDate(periodType)
+    }
+
     const entity: Partial<KpiMetricValue> = {
       metric,
       metricId: metricValue.metricId,
-      valueDate: metricValue.valueDate,
-      periodType: metricValue.periodType,
+      valueDate,
+      periodType,
       value: metricValue.value,
       group: metricValue.group,
       unit: metricValue.unit,
@@ -86,24 +71,40 @@ export class KpiMetricValueMutation {
     const { domain, user, tx } = context.state
     const metric = await getRepository(KpiMetric).findOne({ where: { name: metricName, domain: { id: domain.id } } })
     if (!metric) throw new Error(`Metric not found: ${metricName}`)
-    const periodType = (metric.periodType as unknown as KpiPeriodType) || KpiPeriodType.DAY
-    const valueDateToUse = getDefaultValueDate(periodType)
+    const periodType = metric.periodType || KpiPeriodType.DAY
+    const valueDate = getDefaultValueDate(periodType)
     if (value == null && meta == null) {
       throw new Error('Either value or meta must be provided.')
     }
-    const entity: Partial<KpiMetricValue> = {
-      metric,
-      metricId: metric.id,
-      value,
-      meta,
-      valueDate: valueDateToUse,
-      periodType,
-      group,
-      domain,
-      creator: user,
-      updater: user
+    const repo = getRepository(KpiMetricValue, tx)
+    let entity = await repo.findOne({
+      where: {
+        metric: { id: metric.id },
+        valueDate,
+        periodType,
+        group,
+        domain: { id: domain.id }
+      }
+    })
+    if (entity) {
+      entity.value = value
+      entity.meta = meta
+      entity.updater = user
+    } else {
+      entity = repo.create({
+        metric,
+        metricId: metric.id,
+        value,
+        meta,
+        valueDate,
+        periodType,
+        group,
+        domain,
+        creator: user,
+        updater: user
+      })
     }
-    return await getRepository(KpiMetricValue, tx).save(entity)
+    return await repo.save(entity)
   }
 
   @Directive('@transaction')
@@ -213,3 +214,22 @@ export class KpiMetricValueMutation {
     return true
   }
 }
+
+// valueDate와 periodType의 일치 여부를 검사하는 유틸리티 함수(임시, 아래에 추가)
+function isValueDateValidForPeriodType(valueDate: string, periodType: KpiPeriodType): boolean {
+  if (!valueDate) return false
+  switch (periodType) {
+    case KpiPeriodType.DAY:
+      return /^\d{4}-\d{2}-\d{2}$/.test(valueDate)
+    case KpiPeriodType.MONTH:
+      return /^\d{4}-\d{2}$/.test(valueDate)
+    case KpiPeriodType.QUARTER:
+      return /^\d{4}-Q[1-4]$/.test(valueDate)
+    case KpiPeriodType.WEEK:
+      return /^\d{4}-W\d{1,2}$/.test(valueDate)
+    case KpiPeriodType.ALLTIME:
+      return valueDate === 'ALLTIME'
+    default:
+      return true
+  }
+}

package/server/service/kpi-metric-value/kpi-metric-value.ts

@@ -3,6 +3,7 @@ import {
   PrimaryGeneratedColumn,
   Column,
   ManyToOne,
+  Index,
   JoinColumn,
   CreateDateColumn,
   UpdateDateColumn,
@@ -15,6 +16,7 @@ import { KpiPeriodType } from '../kpi/kpi'
 import { User } from '@things-factory/auth-base'
 
 @Entity()
+@Index('ix_kpi_metric_value_latest', ['domain', 'metric', 'valueDate', 'group'], { unique: true })
 @ObjectType({ description: 'Current value for each KPI metric (can be used for both state and history).' })
 export class KpiMetricValue {
   @PrimaryGeneratedColumn('uuid')
@@ -46,7 +48,7 @@ export class KpiMetricValue {
   @Field({ nullable: true })
   unit?: string
 
-  @Column({ type: 'varchar', length: 20 })
+  @Column()
   @Field({
     description:
       'Date or period for which this metric value is recorded (e.g., day: YYYY-MM-DD, month: YYYY-MM, range: YYYY-MM-DD~YYYY-MM-DD).'
@@ -57,7 +59,7 @@ export class KpiMetricValue {
   @Field(type => KpiPeriodType)
   periodType: KpiPeriodType
 
-  @Column({ nullable: true })
+  @Column({ default: '' })
   @Field({ nullable: true, description: 'Group key for this value (organization, line, user, etc.)' })
   group?: string