@things-factory/kpi 9.0.31 → 9.0.33

package/server/service/kpi-statistic/kpi-statistic-batch.service.ts

@@ -0,0 +1,231 @@
+import { getRepository } from '@things-factory/shell'
+import type ResolverContext from '@things-factory/auth-base'
+import { KpiStatisticCalculationService } from './kpi-statistic-calculation.service'
+import { KpiPeriodType } from '../kpi/kpi'
+import { Domain } from '@things-factory/shell'
+
+/**
+ * KPI 통계 배치 계산 서비스
+ * 정기적으로 실행하여 KpiValue 데이터를 집계해서 KpiStatistic을 생성/업데이트
+ */
+export class KpiStatisticBatchService {
+  
+  /**
+   * 일일 배치: 어제 날짜의 모든 통계 계산
+   */
+  static async runDailyBatch(domainId?: string): Promise<void> {
+    console.log('[KPI Statistics] Starting daily batch calculation...')
+    
+    const yesterday = new Date()
+    yesterday.setDate(yesterday.getDate() - 1)
+    const valueDate = yesterday.toISOString().split('T')[0] // YYYY-MM-DD
+    
+    await this.calculateForAllDomains(KpiPeriodType.DAY, valueDate, domainId)
+    
+    console.log(`[KPI Statistics] Daily batch completed for ${valueDate}`)
+  }
+  
+  /**
+   * 월간 배치: 지난 달의 모든 통계 계산
+   */
+  static async runMonthlyBatch(domainId?: string): Promise<void> {
+    console.log('[KPI Statistics] Starting monthly batch calculation...')
+    
+    const lastMonth = new Date()
+    lastMonth.setMonth(lastMonth.getMonth() - 1)
+    const valueDate = lastMonth.toISOString().substring(0, 7) // YYYY-MM
+    
+    await this.calculateForAllDomains(KpiPeriodType.MONTH, valueDate, domainId)
+    
+    console.log(`[KPI Statistics] Monthly batch completed for ${valueDate}`)
+  }
+  
+  /**
+   * 분기 배치: 지난 분기의 모든 통계 계산
+   */
+  static async runQuarterlyBatch(domainId?: string): Promise<void> {
+    console.log('[KPI Statistics] Starting quarterly batch calculation...')
+    
+    const now = new Date()
+    const currentQuarter = Math.floor(now.getMonth() / 3) + 1
+    const lastQuarter = currentQuarter === 1 ? 4 : currentQuarter - 1
+    const year = currentQuarter === 1 ? now.getFullYear() - 1 : now.getFullYear()
+    const valueDate = `${year}-Q${lastQuarter}`
+    
+    await this.calculateForAllDomains(KpiPeriodType.QUARTER, valueDate, domainId)
+    
+    console.log(`[KPI Statistics] Quarterly batch completed for ${valueDate}`)
+  }
+  
+  /**
+   * 연간 배치: 작년의 모든 통계 계산
+   */
+  static async runYearlyBatch(domainId?: string): Promise<void> {
+    console.log('[KPI Statistics] Starting yearly batch calculation...')
+    
+    const lastYear = new Date().getFullYear() - 1
+    const valueDate = lastYear.toString()
+    
+    await this.calculateForAllDomains(KpiPeriodType.YEAR, valueDate, domainId)
+    
+    console.log(`[KPI Statistics] Yearly batch completed for ${valueDate}`)
+  }
+  
+  /**
+   * 대시보드용 지역별 통계 계산
+   */
+  static async runDashboardBatch(
+    periodType: KpiPeriodType = KpiPeriodType.MONTH,
+    valueDate?: string,
+    domainId?: string
+  ): Promise<void> {
+    console.log('[KPI Statistics] Starting dashboard batch calculation...')
+    
+    if (!valueDate) {
+      const now = new Date()
+      if (periodType === KpiPeriodType.MONTH) {
+        now.setMonth(now.getMonth() - 1)
+        valueDate = now.toISOString().substring(0, 7) // YYYY-MM
+      } else {
+        now.setDate(now.getDate() - 1)
+        valueDate = now.toISOString().split('T')[0] // YYYY-MM-DD
+      }
+    }
+    
+    await this.calculateForAllDomains(periodType, valueDate, domainId)
+    
+    console.log(`[KPI Statistics] Dashboard batch completed for ${valueDate} (${periodType})`)
+  }
+  
+  /**
+   * 모든 도메인에 대해 통계 계산
+   */
+  private static async calculateForAllDomains(
+    periodType: KpiPeriodType,
+    valueDate: string,
+    domainId?: string
+  ): Promise<void> {
+    try {
+      const domains = domainId 
+        ? await getRepository(Domain).find({ where: { id: domainId } })
+        : await getRepository(Domain).find()
+      
+      for (const domain of domains) {
+        try {
+          await this.calculateForDomain(domain, periodType, valueDate)
+        } catch (error) {
+          console.error(`[KPI Statistics] Domain ${domain.name} calculation failed, continuing with next domain:`, error)
+          // 개별 도메인 실패가 전체 배치를 중단시키지 않도록 계속 진행
+          continue
+        }
+      }
+    } catch (error) {
+      console.error('[KPI Statistics] Batch calculation failed:', error)
+      throw error
+    }
+  }
+  
+  /**
+   * 특정 도메인에 대해 통계 계산
+   */
+  private static async calculateForDomain(
+    domain: Domain,
+    periodType: KpiPeriodType,
+    valueDate: string
+  ): Promise<void> {
+    console.log(`[KPI Statistics] Calculating for domain: ${domain.name} (${domain.id})`)
+    
+    // 가짜 ResolverContext 생성 (배치 작업용)
+    const context: ResolverContext = {
+      state: {
+        domain,
+        user: { id: 'system', name: 'System Batch' }, // 시스템 사용자
+        tx: null // 트랜잭션 없음 (각 계산마다 개별 트랜잭션)
+      }
+    } as any
+    
+    try {
+      const statistics = await KpiStatisticCalculationService.calculateAllStatistics(
+        periodType,
+        valueDate,
+        context
+      )
+      
+      console.log(`[KPI Statistics] Generated ${statistics.length} statistics for domain ${domain.name}`)
+      
+      // 성공 로깅
+      this.logBatchResult(domain.id, periodType, valueDate, statistics.length, 'SUCCESS')
+      
+    } catch (error) {
+      console.error(`[KPI Statistics] Failed to calculate for domain ${domain.name}:`, error)
+      
+      // 실패 로깅
+      this.logBatchResult(domain.id, periodType, valueDate, 0, 'FAILED', error.message)
+      
+      // 에러를 던져서 상위에서 처리
+      throw error
+    }
+  }
+  
+  /**
+   * 배치 실행 결과 로깅
+   */
+  private static logBatchResult(
+    domainId: string,
+    periodType: KpiPeriodType,
+    valueDate: string,
+    statisticsCount: number,
+    status: 'SUCCESS' | 'FAILED',
+    errorMessage?: string
+  ): void {
+    const logData = {
+      timestamp: new Date().toISOString(),
+      domainId,
+      periodType,
+      valueDate,
+      statisticsCount,
+      status,
+      errorMessage
+    }
+    
+    // 실제 운영에서는 로깅 시스템에 저장
+    console.log('[KPI Statistics Batch Log]', JSON.stringify(logData))
+  }
+  
+  /**
+   * 배치 작업 스케줄링 설정 예시
+   */
+  static setupBatchSchedule(): void {
+    // 실제 구현시에는 cron 등의 스케줄러 사용
+    console.log('[KPI Statistics] Batch schedule setup example:')
+    console.log('Daily batch: Run at 02:00 AM every day')
+    console.log('Monthly batch: Run at 03:00 AM on 1st of every month') 
+    console.log('Quarterly batch: Run at 04:00 AM on 1st of every quarter')
+    console.log('Yearly batch: Run at 05:00 AM on January 1st')
+    
+    /*
+    // Node-cron 사용 예시:
+    import cron from 'node-cron'
+    
+    // 매일 새벽 2시
+    cron.schedule('0 2 * * *', () => {
+      this.runDailyBatch()
+    })
+    
+    // 매월 1일 새벽 3시
+    cron.schedule('0 3 1 * *', () => {
+      this.runMonthlyBatch()
+    })
+    
+    // 매 분기 첫날 새벽 4시 (1, 4, 7, 10월)
+    cron.schedule('0 4 1 1,4,7,10 *', () => {
+      this.runQuarterlyBatch()
+    })
+    
+    // 매년 1월 1일 새벽 5시
+    cron.schedule('0 5 1 1 *', () => {
+      this.runYearlyBatch()
+    })
+    */
+  }
+}

package/server/service/kpi-statistic/kpi-statistic-calculation.service.ts

@@ -0,0 +1,410 @@
+import { getRepository } from '@things-factory/shell'
+import type ResolverContext from '@things-factory/auth-base'
+import { KpiStatistic } from './kpi-statistic'
+import { KpiValue } from '../kpi-value/kpi-value'
+import { Kpi, KpiPeriodType } from '../kpi/kpi'
+import { KpiOrgScope } from '../kpi-org-scope/kpi-org-scope'
+import { KpiScope } from '../kpi-scope/kpi-scope'
+
+/**
+ * KPI 통계 계산 서비스
+ * KpiValue 데이터로부터 통계값을 계산하여 KpiStatistic에 저장
+ */
+export class KpiStatisticCalculationService {
+  /**
+   * 전체 KPI에 대해 통계를 계산
+   */
+  static async calculateAllStatistics(
+    periodType: KpiPeriodType,
+    valueDate: string,
+    context: ResolverContext
+  ): Promise<KpiStatistic[]> {
+    const { domain } = context.state
+
+    // Leaf KPI들만 대상으로 함 (실제 값을 가진 KPI)
+    const leafKpis = await getRepository(Kpi).find({
+      where: { domain: { id: domain.id }, isLeaf: true }
+    })
+
+    const results: KpiStatistic[] = []
+
+    for (const kpi of leafKpis) {
+      // 1. 전체 통계 (scope 없음)
+      const overallStats = await this.calculateKpiStatistics(
+        kpi.id,
+        periodType,
+        valueDate,
+        null, // kpiOrgScope 없음 = 전체 통계
+        context
+      )
+      if (overallStats) results.push(overallStats)
+
+      // 2. 스코프별 통계
+      const scopedStats = await this.calculateScopedStatistics(kpi.id, periodType, valueDate, context)
+      results.push(...scopedStats)
+    }
+
+    return results
+  }
+
+  /**
+   * 특정 KPI의 통계를 계산
+   */
+  static async calculateKpiStatistics(
+    kpiId: string,
+    periodType: KpiPeriodType,
+    valueDate: string,
+    kpiOrgScope: KpiOrgScope | null,
+    context: ResolverContext
+  ): Promise<KpiStatistic | null> {
+    const { domain, user, tx } = context.state
+
+    // KPI 값들 조회
+    const whereCondition: any = {
+      kpi: { id: kpiId },
+      domain: { id: domain.id },
+      valueDate: this.buildDateFilter(valueDate, periodType)
+    }
+
+    if (kpiOrgScope) {
+      whereCondition.kpiOrgScope = { id: kpiOrgScope.id }
+    }
+
+    const kpiValues = await getRepository(KpiValue, tx).find({
+      where: whereCondition,
+      relations: ['kpi', 'kpiOrgScope']
+    })
+
+    if (kpiValues.length === 0) {
+      return null
+    }
+
+    // 통계 계산
+    const statistics = this.calculateStatistics(kpiValues.map(v => v.value).filter(v => v !== null))
+
+    // KpiStatistic 엔티티 생성/업데이트
+    const kpiStatisticRepo = getRepository(KpiStatistic, tx)
+
+    // 기존 통계 조회
+    const existingWhere: any = {
+      kpi: { id: kpiId },
+      domain: { id: domain.id },
+      periodType,
+      valueDate
+    }
+
+    if (kpiOrgScope) {
+      existingWhere.kpiOrgScope = { id: kpiOrgScope.id }
+    } else {
+      existingWhere.kpiOrgScope = null
+    }
+
+    let kpiStatistic = await kpiStatisticRepo.findOne({ where: existingWhere })
+
+    if (!kpiStatistic) {
+      kpiStatistic = kpiStatisticRepo.create()
+      kpiStatistic.kpi = kpiValues[0].kpi
+      kpiStatistic.kpiId = kpiId
+      kpiStatistic.domain = { id: domain.id } as any
+      kpiStatistic.periodType = periodType
+      kpiStatistic.valueDate = valueDate
+      kpiStatistic.creator = user
+      kpiStatistic.kpiOrgScope = kpiOrgScope
+      kpiStatistic.kpiOrgScopeId = kpiOrgScope?.id
+    }
+
+    // 통계값 적용
+    Object.assign(kpiStatistic, statistics)
+    kpiStatistic.updater = user
+    kpiStatistic.metadata = {
+      ...kpiStatistic.metadata,
+      calculationMethod: 'auto-calculated',
+      lastCalculated: new Date(),
+      dataCount: kpiValues.length,
+      calculatedFrom: 'kpi-values'
+    }
+
+    return await kpiStatisticRepo.save(kpiStatistic)
+  }
+
+  /**
+   * 스코프별 통계 계산 (KpiScope 기반)
+   */
+  static async calculateScopedStatistics(
+    kpiId: string,
+    periodType: KpiPeriodType,
+    valueDate: string,
+    context: ResolverContext
+  ): Promise<KpiStatistic[]> {
+    const { domain } = context.state
+
+    // 통계 계산에 사용할 스코프 정의 조회
+    const kpiScopes = await getRepository(KpiScope).find({
+      where: {
+        domain: { id: domain.id },
+        active: true,
+        includeInStatistics: true
+      },
+      order: { displayOrder: 'ASC' }
+    })
+
+    const results: KpiStatistic[] = []
+
+    for (const kpiScope of kpiScopes) {
+      const scopedStats = await this.calculateStatisticsByScope(kpiId, periodType, valueDate, kpiScope, context)
+      results.push(...scopedStats)
+    }
+
+    return results
+  }
+
+  /**
+   * 특정 스코프 차원별 통계 계산
+   */
+  static async calculateStatisticsByScope(
+    kpiId: string,
+    periodType: KpiPeriodType,
+    valueDate: string,
+    kpiScope: KpiScope,
+    context: ResolverContext
+  ): Promise<KpiStatistic[]> {
+    const { domain } = context.state
+    const scopeLevel = kpiScope.level
+    const fieldName = `scope${scopeLevel.toString().padStart(2, '0')}`
+
+    // 해당 스코프 레벨의 유니크한 값들 조회
+    const scopeValues = kpiScope.validValues || (await this.getDistinctScopeValues(fieldName, domain.id))
+
+    const results: KpiStatistic[] = []
+
+    for (const scopeValue of scopeValues) {
+      // 해당 스코프 값을 가진 KpiOrgScope들 조회
+      const kpiOrgScopes = await getRepository(KpiOrgScope).find({
+        where: {
+          domain: { id: domain.id },
+          [fieldName]: scopeValue
+        }
+      })
+
+      // 각 KpiOrgScope에 대해 통계 계산
+      for (const orgScope of kpiOrgScopes) {
+        const statistic = await this.calculateKpiStatistics(kpiId, periodType, valueDate, orgScope, context)
+        if (statistic) {
+          results.push(statistic)
+        }
+      }
+
+      // 스코프 값별 집계 통계도 생성 (선택적)
+      if (kpiOrgScopes.length > 1) {
+        const aggregatedStats = await this.calculateAggregatedScopeStatistics(
+          kpiId,
+          periodType,
+          valueDate,
+          kpiScope,
+          scopeValue,
+          kpiOrgScopes,
+          context
+        )
+        if (aggregatedStats) {
+          results.push(aggregatedStats)
+        }
+      }
+    }
+
+    return results
+  }
+
+  /**
+   * 스코프 값별 집계 통계 계산 (예: 서울 전체 평균)
+   */
+  private static async calculateAggregatedScopeStatistics(
+    kpiId: string,
+    periodType: KpiPeriodType,
+    valueDate: string,
+    kpiScope: KpiScope,
+    scopeValue: string,
+    kpiOrgScopes: KpiOrgScope[],
+    context: ResolverContext
+  ): Promise<KpiStatistic | null> {
+    const { domain, user, tx } = context.state
+
+    // 모든 KpiOrgScope에서 KpiValue들 수집
+    const allValues: number[] = []
+    for (const orgScope of kpiOrgScopes) {
+      const kpiValues = await getRepository(KpiValue, tx).find({
+        where: {
+          kpi: { id: kpiId },
+          domain: { id: domain.id },
+          kpiOrgScope: { id: orgScope.id },
+          valueDate: this.buildDateFilter(valueDate, periodType)
+        }
+      })
+      allValues.push(...kpiValues.map(v => v.value).filter(v => v !== null))
+    }
+
+    if (allValues.length === 0) return null
+
+    // 집계 통계 계산
+    const statistics = this.calculateStatistics(allValues)
+
+    // 가상의 KpiOrgScope 생성 (집계용)
+    const aggregatedOrgScope = {
+      id: `aggregated-${kpiScope.level}-${scopeValue}`,
+      entityType: 'AGGREGATED',
+      entityName: `${kpiScope.name}: ${scopeValue}`,
+      org: scopeValue,
+      [`scope${kpiScope.level.toString().padStart(2, '0')}`]: scopeValue
+    }
+
+    // KpiStatistic 생성
+    const kpiStatisticRepo = getRepository(KpiStatistic, tx)
+    const kpiStatistic = kpiStatisticRepo.create()
+
+    const kpi = await getRepository(Kpi).findOneBy({ id: kpiId })
+    kpiStatistic.kpi = kpi
+    kpiStatistic.kpiId = kpiId
+    kpiStatistic.domain = { id: domain.id } as any
+    kpiStatistic.periodType = periodType
+    kpiStatistic.valueDate = valueDate
+    kpiStatistic.creator = user
+    kpiStatistic.updater = user
+
+    // 통계값 적용
+    Object.assign(kpiStatistic, statistics)
+    kpiStatistic.metadata = {
+      ...kpiStatistic.metadata,
+      calculationMethod: 'scope-aggregated',
+      lastCalculated: new Date(),
+      dataCount: allValues.length,
+      kpiScope: {
+        id: kpiScope.id,
+        name: kpiScope.name,
+        level: kpiScope.level,
+        scopeType: kpiScope.scopeType
+      },
+      aggregatedScopeValue: scopeValue,
+      orgScopeCount: kpiOrgScopes.length
+    }
+
+    return await kpiStatisticRepo.save(kpiStatistic)
+  }
+
+  /**
+   * 특정 스코프 필드의 유니크한 값들 조회
+   */
+  private static async getDistinctScopeValues(fieldName: string, domainId: string): Promise<string[]> {
+    const query = `
+      SELECT DISTINCT ${fieldName} as value 
+      FROM kpi_org_scope 
+      WHERE domainId = ? AND ${fieldName} IS NOT NULL 
+      ORDER BY ${fieldName}
+    `
+
+    const results = await getRepository(KpiOrgScope).query(query, [domainId])
+    return results.map((r: any) => r.value).filter(Boolean)
+  }
+
+  /**
+   * 통계값 계산 로직
+   */
+  private static calculateStatistics(values: number[]) {
+    if (values.length === 0) return {}
+
+    const sortedValues = [...values].sort((a, b) => a - b)
+    const count = values.length
+    const sum = values.reduce((acc, val) => acc + val, 0)
+    const mean = sum / count
+
+    // 중앙값
+    const median =
+      count % 2 === 0
+        ? (sortedValues[Math.floor(count / 2) - 1] + sortedValues[Math.floor(count / 2)]) / 2
+        : sortedValues[Math.floor(count / 2)]
+
+    // 분산 및 표준편차
+    const variance = values.reduce((acc, val) => acc + Math.pow(val - mean, 2), 0) / count
+    const standardDeviation = Math.sqrt(variance)
+
+    // 최소/최대값 및 범위
+    const minimum = Math.min(...values)
+    const maximum = Math.max(...values)
+    const range = maximum - minimum
+
+    // 분위수 계산
+    const q1Index = Math.floor(count * 0.25)
+    const q3Index = Math.floor(count * 0.75)
+    const percentile25 = sortedValues[q1Index]
+    const percentile75 = sortedValues[q3Index]
+    const iqr = percentile75 - percentile25
+
+    // 이상치 감지를 위한 fence
+    const lowerFence = percentile25 - 1.5 * iqr
+    const upperFence = percentile75 + 1.5 * iqr
+
+    return {
+      count,
+      sum,
+      range,
+      mean,
+      median,
+      minimum,
+      maximum,
+      standardDeviation,
+      variance,
+      percentile25,
+      percentile75,
+      iqr,
+      lowerFence,
+      upperFence,
+      additionalStatistics: {
+        coefficientOfVariation: standardDeviation / mean,
+        skewness: this.calculateSkewness(values, mean, standardDeviation),
+        kurtosis: this.calculateKurtosis(values, mean, standardDeviation)
+      }
+    }
+  }
+
+  /**
+   * 왜도 계산
+   */
+  private static calculateSkewness(values: number[], mean: number, stdDev: number): number {
+    if (stdDev === 0) return 0
+    const n = values.length
+    const sum = values.reduce((acc, val) => acc + Math.pow((val - mean) / stdDev, 3), 0)
+    return (n / ((n - 1) * (n - 2))) * sum
+  }
+
+  /**
+   * 첨도 계산
+   */
+  private static calculateKurtosis(values: number[], mean: number, stdDev: number): number {
+    if (stdDev === 0) return 0
+    const n = values.length
+    const sum = values.reduce((acc, val) => acc + Math.pow((val - mean) / stdDev, 4), 0)
+    const kurtosis = ((n * (n + 1)) / ((n - 1) * (n - 2) * (n - 3))) * sum
+    const adjustment = (3 * Math.pow(n - 1, 2)) / ((n - 2) * (n - 3))
+    return kurtosis - adjustment
+  }
+
+  /**
+   * 기간 타입에 따른 날짜 필터 생성
+   */
+  private static buildDateFilter(valueDate: string, periodType: KpiPeriodType): string {
+    switch (periodType) {
+      case KpiPeriodType.DAY:
+        return valueDate // 정확한 날짜 매치
+      case KpiPeriodType.WEEK:
+        return `${valueDate.substring(0, 8)}%` // YYYY-MM-DD% -> 주 단위
+      case KpiPeriodType.MONTH:
+        return `${valueDate.substring(0, 7)}%` // YYYY-MM%
+      case KpiPeriodType.QUARTER:
+        const year = valueDate.substring(0, 4)
+        const quarter = valueDate.substring(5, 7) // Q1, Q2, Q3, Q4
+        return `${year}-${quarter}%`
+      case KpiPeriodType.YEAR:
+        return `${valueDate.substring(0, 4)}%` // YYYY%
+      default:
+        return valueDate
+    }
+  }
+}