@things-factory/kpi 1.0.0-alpha.5 → 9.0.9

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

@@ -0,0 +1,128 @@
+import { getRepository } from '@things-factory/shell'
+import { DataSummary } from '@things-factory/dataset'
+import { finalizeLatestDataCollection } from '@things-factory/dataset/dist-server/controllers/finalize-data-collection'
+import { KpiMetric } from './kpi-metric'
+import { KpiValue, KpiValueInputType } from '../kpi-value/kpi-value'
+import { Kpi } from '../kpi/kpi'
+import { KpiFormulaService } from '../kpi/kpi-formula.service'
+
+/**
+ * KPI-Metric 집계/자동화 서비스 함수 (formula 지원, KPI Value 저장)
+ * @param metricId KPI-Metric ID
+ * @param domainId 도메인 ID
+ * @param context ResolverContext (state에 domain, user, tx 등 포함)
+ * @returns 저장된 KPI Value 배열
+ */
+export async function aggregateKpiMetricValue(metricId: string, domainId: string, context: ResolverContext) {
+  const tx = context.state?.tx || getRepository(KpiMetric).manager
+
+  // 1. metric 정보 조회
+  const metric = await getRepository(KpiMetric).findOne({
+    where: { id: metricId, domain: { id: domainId } }
+  })
+  if (!metric) throw new Error('Metric 정보 없음')
+  if (!metric.active) throw new Error('비활성화된 Metric')
+
+  // 2. formula가 있으면 산식 계산, 없으면 dataset 집계
+  let values: any[] = []
+  if (metric.formula) {
+    // formula 파싱 및 metric code별 값 계산
+    const formulaService = new KpiFormulaService()
+    const metricCodes = formulaService.extractMetricCodes(metric.formula)
+    // code별 값 집계 (동일 기간/그룹 기준)
+    const codeValueMap: Record<string, any[]> = {}
+    for (const code of metricCodes) {
+      const subMetric = await getRepository(KpiMetric).findOne({ where: { name: code, domain: { id: domainId } } })
+      if (!subMetric) throw new Error(`Formula metric '${code}' not found`)
+      codeValueMap[code] = await aggregateKpiMetricValue(subMetric.id, domainId, context)
+    }
+    // group/date/period별로 값 매핑
+    // (여기서는 가장 최근 기간 기준, group key 조합으로 매핑)
+    const groupKey = v =>
+      [v.date, v.period, v.group?.key01, v.group?.key02, v.group?.key03, v.group?.key04, v.group?.key05].join('|')
+    const groupMap: Record<string, any> = {}
+    for (const code of metricCodes) {
+      for (const v of codeValueMap[code]) {
+        const key = groupKey(v)
+        groupMap[key] = groupMap[key] || { ...v, _values: {} }
+        groupMap[key]._values[code] = v.value
+      }
+    }
+    // formula 계산 (js eval, 보안상 제한적 사용)
+    for (const key in groupMap) {
+      const ctx = groupMap[key]._values
+      let value = null
+      try {
+        value = Function(...Object.keys(ctx), `return (${metric.formula})`)(...Object.values(ctx))
+      } catch (e) {
+        value = null
+      }
+      values.push({ ...groupMap[key], value })
+    }
+  } else {
+    // 3. dataset 집계/마감 실행 (최신 기간 기준)
+    if (!metric.dataSetId || !metric.fieldName) throw new Error('Metric 매핑 정보 누락')
+    await finalizeLatestDataCollection(metric.dataSetId, context)
+    // 4. 집계 결과(summary)에서 metric.fieldName 값 추출
+    const summaries = await getRepository(DataSummary).find({
+      where: { dataSet: { id: metric.dataSetId }, domain: { id: domainId } },
+      order: { date: 'DESC', period: 'DESC' }
+    })
+    values = summaries
+      .map(summary => {
+        if (summary.summary && metric.fieldName in summary.summary) {
+          return {
+            date: summary.date,
+            period: summary.period,
+            value: summary.summary[metric.fieldName],
+            group: {
+              key01: summary.key01,
+              key02: summary.key02,
+              key03: summary.key03,
+              key04: summary.key04,
+              key05: summary.key05
+            }
+          }
+        }
+        return null
+      })
+      .filter(Boolean)
+  }
+
+  // 5. KPI Value로 저장 (metric 단위, KPI 단위 formula는 후속)
+  // metric이 속한 KPI 정보 조회 (여기서는 metric.name == kpi.name인 KPI를 임시로 매핑, 실제 연동 구조에 맞게 보완 필요)
+  const kpi = await getRepository(Kpi).findOne({ where: { name: metric.name, domain: { id: domainId } } })
+  if (!kpi) throw new Error('KPI 정보 없음 (metric.name과 동일한 KPI name 기준, 실제 연동 구조에 맞게 보완 필요)')
+
+  // KPI Value version, valueDate, groupId, groupType 등 매핑
+  const savedValues = []
+  for (const v of values) {
+    const valueDate = v.date
+    const groupId = v.group?.key01
+    const groupType = v.group?.key02
+    const version = kpi.version || 1
+    const value = v.value
+    if (value == null || isNaN(value)) continue
+    // upsert(동일 KPI, valueDate, groupId, groupType, version) 기준으로 저장
+    const repo = getRepository(KpiValue, context.state?.tx)
+    const existing = await repo.findOne({
+      where: { kpi: { id: kpi.id }, valueDate, groupId, groupType, version, domain: { id: domainId } }
+    })
+    let entity = existing || repo.create()
+    entity.kpi = kpi
+    entity.kpiId = kpi.id
+    entity.version = version
+    entity.valueDate = valueDate
+    entity.value = value
+    entity.groupId = groupId
+    entity.groupType = groupType
+    entity.inputType = KpiValueInputType.AUTO
+    entity.source = 'AUTO'
+    entity.domain = kpi.domain
+    entity.creator = context.state?.user
+    entity.updater = context.state?.user
+    entity = await repo.save(entity)
+    savedValues.push(entity)
+  }
+  return savedValues
+}

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

@@ -1,9 +1,7 @@
 import { KpiMetric } from './kpi-metric'
-import { KpiMetricHistory } from './kpi-metric-history'
-import { KpiMetricHistoryEntitySubscriber } from './event-subscriber'
 import { KpiMetricQuery } from './kpi-metric-query'
 import { KpiMetricMutation } from './kpi-metric-mutation'
 
-export const entities = [KpiMetric, KpiMetricHistory]
+export const entities = [KpiMetric]
 export const resolvers = [KpiMetricQuery, KpiMetricMutation]
-export const subscribers = [KpiMetricHistoryEntitySubscriber]
+export const subscribers = []

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

@@ -1,31 +1,88 @@
 import { Resolver, Mutation, Arg, Ctx, Directive } from 'type-graphql'
 import { In } from 'typeorm'
 import { getRepository } from '@things-factory/shell'
+import { DataSet } from '@things-factory/dataset'
 
 import { createAttachment, deleteAttachmentsByRef } from '@things-factory/attachment-base'
 import { KpiMetric } from './kpi-metric'
 import { NewKpiMetric, KpiMetricPatch } from './kpi-metric-type'
+import { KpiFormulaService } from '../kpi/kpi-formula.service'
+import { registerSchedule, unregisterSchedule, CallbackBase, Application } from '@things-factory/scheduler-client'
 
 @Resolver(KpiMetric)
 export class KpiMetricMutation {
   @Directive('@transaction')
-  @Mutation(returns => KpiMetric, { description: 'To create new KpiMetric' })
-  async createKpiMetric(@Arg('kpiMetric') kpiMetric: NewKpiMetric, @Ctx() context: ResolverContext): Promise<KpiMetric> {
+  @Mutation(returns => KpiMetric, { description: 'Create a new KPI metric with the provided details.' })
+  async createKpiMetric(
+    @Arg('metric', { description: 'Input object containing details for the new KPI metric.' }) metric: NewKpiMetric,
+    @Ctx() context: ResolverContext
+  ): Promise<KpiMetric> {
     const { domain, user, tx } = context.state
 
+    let dataSet = metric.dataSetId
+      ? await getRepository(DataSet).findOne({ where: { id: metric.dataSetId } })
+      : undefined
+
+    if (metric.formula) {
+      const formulaService = new KpiFormulaService()
+      const result = await formulaService.validateFormula(metric.formula)
+      if (!result.valid) {
+        throw new Error(result.errors.join('\n'))
+      }
+    }
+
     const result = await getRepository(KpiMetric, tx).save({
-      ...kpiMetric,
+      ...metric,
+      dataSet,
       domain,
       creator: user,
       updater: user
     })
 
-    if (kpiMetric.thumbnail) {
+    // 스케줄러 등록
+    if (metric.schedule) {
+      const handle = await registerSchedule({
+        name: metric.name,
+        client: {
+          application: Application,
+          group: `${domain.id}`,
+          type: 'kpi-metric',
+          key: result.id,
+          operation: 'aggregate'
+        },
+        type: 'cron',
+        schedule: metric.schedule,
+        timezone: metric.timezone,
+        task: {
+          type: 'rest',
+          connection: {
+            host: `${CallbackBase}/callback-schedule-for-kpi-metric`,
+            headers: {
+              'Content-Type': 'application/json',
+              accept: '*/*'
+            }
+          },
+          data: {
+            domainId: domain.id,
+            metricId: result.id
+          },
+          history_check: true,
+          failed_policy: 'retry_dlq',
+          max_retry_count: 3,
+          retry_period: 60
+        }
+      })
+      result.scheduleId = handle
+      result.timezone = metric.timezone
+      await getRepository(KpiMetric, tx).save(result)
+    }
+
+    if (metric.thumbnail) {
       await createAttachment(
         null,
         {
           attachment: {
-            file: kpiMetric.thumbnail,
+            file: metric.thumbnail,
             refType: KpiMetric.name,
             refBy: result.id
           }
@@ -51,12 +108,67 @@ export class KpiMetricMutation {
       where: { domain: { id: domain.id }, id }
     })
 
+    let dataSet = patch.dataSetId
+      ? await getRepository(DataSet).findOne({ where: { id: patch.dataSetId } })
+      : kpiMetric.dataSet
+
+    if (patch.formula) {
+      const formulaService = new KpiFormulaService()
+      const result = await formulaService.validateFormula(patch.formula)
+      if (!result.valid) {
+        throw new Error(result.errors.join('\n'))
+      }
+    }
+
     const result = await repository.save({
       ...kpiMetric,
       ...patch,
+      dataSet,
       updater: user
     })
 
+    // 스케줄러 해제/등록 (변경 시)
+    if (kpiMetric.scheduleId && (patch.schedule !== kpiMetric.schedule || !patch.schedule)) {
+      await unregisterSchedule(kpiMetric.scheduleId)
+      result.scheduleId = null
+    }
+    if (patch.schedule) {
+      const handle = await registerSchedule({
+        name: patch.name || kpiMetric.name,
+        client: {
+          application: Application,
+          group: `${domain.id}`,
+          type: 'kpi-metric',
+          key: result.id,
+          operation: 'aggregate'
+        },
+        type: 'cron',
+        schedule: patch.schedule,
+        timezone: patch.timezone,
+        task: {
+          type: 'rest',
+          connection: {
+            host: `${CallbackBase}/callback-schedule-for-kpi-metric`,
+            headers: {
+              'Content-Type': 'application/json',
+              accept: '*/*'
+            }
+          },
+          data: {
+            domainId: domain.id,
+            metricId: result.id
+          },
+          history_check: true,
+          failed_policy: 'retry_dlq',
+          max_retry_count: 3,
+          retry_period: 60
+        }
+      })
+      result.scheduleId = handle
+      result.timezone = patch.timezone
+      await repository.save(result)
+    }
+
     if (patch.thumbnail) {
       await deleteAttachmentsByRef(null, { refBys: [result.id] }, context)
       await createAttachment(
@@ -154,8 +266,12 @@ export class KpiMetricMutation {
   @Mutation(returns => Boolean, { description: 'To delete KpiMetric' })
   async deleteKpiMetric(@Arg('id') id: string, @Ctx() context: ResolverContext): Promise<boolean> {
     const { domain, tx } = context.state
-
-    await getRepository(KpiMetric, tx).delete({ domain: { id: domain.id }, id })
+    const repo = getRepository(KpiMetric, tx)
+    const metric = await repo.findOne({ where: { domain: { id: domain.id }, id } })
+    if (metric?.scheduleId) {
+      await unregisterSchedule(metric.scheduleId)
+    }
+    await repo.delete({ domain: { id: domain.id }, id })
     await deleteAttachmentsByRef(null, { refBys: [id] }, context)
 
     return true

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

@@ -7,8 +7,11 @@ import { KpiMetricList } from './kpi-metric-type'
 
 @Resolver(KpiMetric)
 export class KpiMetricQuery {
-  @Query(returns => KpiMetric!, { nullable: true, description: 'To fetch a KpiMetric' })
-  async kpiMetric(@Arg('id') id: string, @Ctx() context: ResolverContext): Promise<KpiMetric> {
+  @Query(returns => KpiMetric!, { nullable: true, description: 'Fetch a single KPI metric by its unique identifier.' })
+  async kpiMetric(
+    @Arg('id', { description: 'Unique identifier of the KPI metric to fetch.' }) id: string,
+    @Ctx() context: ResolverContext
+  ): Promise<KpiMetric> {
     const { domain } = context.state
 
     return await getRepository(KpiMetric).findOne({
@@ -17,7 +20,10 @@ export class KpiMetricQuery {
   }
 
   @Query(returns => KpiMetricList, { description: 'To fetch multiple KpiMetrics' })
-  async kpiMetrics(@Args(type => ListParam) params: ListParam, @Ctx() context: ResolverContext): Promise<KpiMetricList> {
+  async kpiMetrics(
+    @Args(type => ListParam) params: ListParam,
+    @Ctx() context: ResolverContext
+  ): Promise<KpiMetricList> {
     const { domain } = context.state
 
     const queryBuilder = getQueryBuilderFromListParams({

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

@@ -4,27 +4,47 @@ import { ObjectType, Field, InputType, Int, ID, registerEnumType } from 'type-gr
 
 import { ObjectRef, ScalarObject } from '@things-factory/shell'
 
-import { KpiMetric, KpiMetricStatus } from './kpi-metric'
+import { KpiMetric } from './kpi-metric'
 
-@InputType()
+@InputType({ description: 'Input type for creating a new KPI metric. Used in mutations to provide metric details.' })
 export class NewKpiMetric {
-  @Field()
+  @Field({ description: 'Metric code, unique within the domain, used in KPI formulas.' })
   name: string
 
-  @Field({ nullable: true })
+  @Field({ nullable: true, description: 'User-friendly name or description of the metric.' })
   description?: string
 
-  @Field(type => KpiMetricStatus, { nullable: true })
-  state?: KpiMetricStatus
+  @Field({ nullable: true, description: 'Unit of measurement for this metric (e.g., %, count, hours).' })
+  unit?: string
 
-  @Field({ nullable: true })
+  @Field({ nullable: true, description: 'Source of the metric data (e.g., system, method, dataset).' })
+  source?: string
+
+  @Field(type => ID, { nullable: true, description: 'ID of the source dataset for this metric.' })
+  dataSetId?: string
+
+  @Field({ nullable: true, description: 'Name of the field in the dataset this metric maps to.' })
+  fieldName?: string
+
+  @Field({ nullable: true, description: 'Indicates whether this metric is active and usable.' })
   active?: boolean
 
-  @Field({ nullable: true })
-  params?: string
+  @Field({ nullable: true, description: 'Calculation formula for the metric, using other metric codes and operators.' })
+  formula?: string
 
-  @Field(type => GraphQLUpload, { nullable: true })
+  @Field({
+    nullable: true,
+    description: 'Cron schedule string for periodic KPI value aggregation (e.g., "0 0 * * *" for daily).'
+  })
+  schedule?: string
+
+  @Field(type => GraphQLUpload, { nullable: true, description: 'Thumbnail image or file for this metric.' })
   thumbnail?: FileUpload
+
+  @Field({ nullable: true, description: 'Timezone for the schedule.' })
+  timezone?: string
+  @Field({ nullable: true, description: 'Schedule ID for the registered cron job.' })
+  scheduleId?: string
 }
 
 @InputType()
@@ -38,17 +58,40 @@ export class KpiMetricPatch {
   @Field({ nullable: true })
   description?: string
 
-  @Field(type => KpiMetricStatus, { nullable: true })
-  state?: KpiMetricStatus
+  @Field({ nullable: true })
+  unit?: string
+
+  @Field({ nullable: true })
+  source?: string
+
+  @Field(type => ID, { nullable: true })
+  dataSetId?: string
+
+  @Field({ nullable: true })
+  fieldName?: string
 
   @Field({ nullable: true })
   active?: boolean
 
+  @Field({ nullable: true, description: 'Calculation formula for the metric, using other metric codes and operators.' })
+  formula?: string
+
+  @Field({
+    nullable: true,
+    description: 'Cron schedule string for periodic KPI value aggregation (e.g., "0 0 * * *" for daily).'
+  })
+  schedule?: string
+
   @Field(type => GraphQLUpload, { nullable: true })
   thumbnail?: FileUpload
-  
+
   @Field({ nullable: true })
   cuFlag?: string
+
+  @Field({ nullable: true, description: 'Timezone for the schedule.' })
+  timezone?: string
+  @Field({ nullable: true, description: 'Schedule ID for the registered cron job.' })
+  scheduleId?: string
 }
 
 @ObjectType()

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

@@ -7,92 +7,112 @@ import {
   Column,
   RelationId,
   ManyToOne,
-  VersionColumn,
   PrimaryGeneratedColumn
 } from 'typeorm'
 import { ObjectType, Field, Int, ID, registerEnumType } from 'type-graphql'
 
 import { Domain } from '@things-factory/shell'
 import { User } from '@things-factory/auth-base'
-
-export enum KpiMetricStatus {
-  STATUS_A = 'STATUS_A',
-  STATUS_B = 'STATUS_B'
-}
-
-registerEnumType(KpiMetricStatus, {
-  name: 'KpiMetricStatus',
-  description: 'state enumeration of a kpiMetric'
-})
+import { DataSet } from '@things-factory/dataset'
 
 @Entity()
 @Index('ix_kpi_metric_0', (kpiMetric: KpiMetric) => [kpiMetric.domain, kpiMetric.name], {
   where: '"deleted_at" IS NULL',
   unique: true
 })
-@ObjectType({ description: 'Entity for KpiMetric' })
+@ObjectType({ description: 'KPI metric entity. Represents a source data item used in KPI formulas.' })
 export class KpiMetric {
   @PrimaryGeneratedColumn('uuid')
-  @Field(type => ID)
+  @Field(type => ID, { description: 'Unique identifier for this KPI metric.' })
   readonly id: string
-  
-  @VersionColumn()
-  @Field({ nullable: true })
-  version?: number = 1
 
   @ManyToOne(type => Domain)
-  @Field({ nullable: true })
+  @Field({ nullable: true, description: 'Domain (tenant) to which this KPI metric belongs.' })
   domain?: Domain
 
-  @RelationId((kpiMetric: KpiMetric) => kpiMetric.domain)
+  @RelationId((metric: KpiMetric) => metric.domain)
+  @Field({ nullable: true, description: 'ID of the domain (tenant) for this KPI metric.' })
   domainId?: string
 
   @Column()
-  @Field({ nullable: true })
-  name?: string
+  @Field({ description: 'Metric code, unique within the domain, used in KPI formulas.' })
+  name: string
 
   @Column({ nullable: true })
-  @Field({ nullable: true })
+  @Field({ nullable: true, description: 'User-friendly name or description of the metric.' })
   description?: string
 
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Unit of measurement for this metric (e.g., %, count, hours).' })
+  unit?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Source of the metric data (e.g., system, method, dataset).' })
+  source?: string
+
+  @ManyToOne(type => DataSet, { nullable: true })
+  @Field(type => DataSet, { nullable: true, description: 'Reference to the source dataset for this metric.' })
+  dataSet?: DataSet
+
+  @RelationId((metric: KpiMetric) => metric.dataSet)
+  @Field({ nullable: true, description: 'ID of the referenced source dataset.' })
+  dataSetId?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Name of the field in the dataset this metric maps to.' })
+  fieldName?: string
+
   @Column({ nullable: false, default: false })
-  @Field({ nullable: true })
+  @Field({ nullable: true, description: 'Indicates whether this metric is active and usable.' })
   active?: boolean
 
   @Column({ nullable: true })
-  @Field({ nullable: true })
-  state?: KpiMetricStatus
+  @Field({ nullable: true, description: 'Calculation formula for the metric, using other metric codes and operators.' })
+  formula?: string
+
+  @Column({ nullable: true })
+  @Field({
+    nullable: true,
+    description: 'Cron schedule string for periodic KPI value aggregation (e.g., "0 0 * * *" for daily).'
+  })
+  schedule?: string
+
+  @Column({ nullable: true })
+  @Field({ nullable: true, description: 'Schedule ID for the registered cron job.' })
+  scheduleId?: string
 
   @Column({ nullable: true })
-  @Field({ nullable: true })
-  params?: string
+  @Field({ nullable: true, description: 'Timezone for the schedule.' })
+  timezone?: string
 
   @CreateDateColumn()
-  @Field({ nullable: true })
+  @Field({ nullable: true, description: 'Timestamp when this KPI metric was created.' })
   createdAt?: Date
 
   @UpdateDateColumn()
-  @Field({ nullable: true })
+  @Field({ nullable: true, description: 'Timestamp when this KPI metric was last updated.' })
   updatedAt?: Date
 
   @DeleteDateColumn()
-  @Field({ nullable: true })
+  @Field({ nullable: true, description: 'Timestamp when this KPI metric was deleted (soft delete).' })
   deletedAt?: Date
 
   @ManyToOne(type => User, { nullable: true })
-  @Field(type => User, { nullable: true })
+  @Field(type => User, { nullable: true, description: 'User who created this KPI metric.' })
   creator?: User
 
-  @RelationId((kpiMetric: KpiMetric) => kpiMetric.creator)
+  @RelationId((metric: KpiMetric) => metric.creator)
+  @Field({ nullable: true, description: 'ID of the user who created this KPI metric.' })
   creatorId?: string
 
   @ManyToOne(type => User, { nullable: true })
-  @Field(type => User, { nullable: true })
+  @Field(type => User, { nullable: true, description: 'User who last updated this KPI metric.' })
   updater?: User
 
-  @RelationId((kpiMetric: KpiMetric) => kpiMetric.updater)
+  @RelationId((metric: KpiMetric) => metric.updater)
+  @Field({ nullable: true, description: 'ID of the user who last updated this KPI metric.' })
   updaterId?: string
 
-  @Field(type => String, { nullable: true })
+  @Field(type => String, { nullable: true, description: 'Thumbnail image or file path for this KPI metric.' })
   thumbnail?: string
 }