@dssp/dkpi 1.0.0-alpha.7 → 1.0.0-alpha.71

package/kpi-module-service-tests.md

@@ -0,0 +1,1286 @@
+# KPI 모듈 서비스 레이어 테스트
+
+## 4. KPI 서비스 레이어 테스트 (kpi-service.spec.ts)
+
+```typescript
+import { describe, it, expect, beforeEach, jest } from '@jest/globals'
+import { Repository } from 'typeorm'
+import { KpiService } from '../server/service/kpi/kpi-service'
+import { Kpi, KpiStatus, KpiVizType } from '../server/service/kpi/kpi'
+import { KpiHistory } from '../server/service/kpi/kpi-history'
+import { Domain } from '@things-factory/shell'
+import { User } from '@things-factory/auth-base'
+
+// Mock 인터페이스
+interface MockRepository<T> extends Partial<Repository<T>> {
+  find: jest.Mock
+  findOne: jest.Mock
+  save: jest.Mock
+  delete: jest.Mock
+  softDelete: jest.Mock
+  count: jest.Mock
+  createQueryBuilder: jest.Mock
+}
+
+describe('KPI Service Layer Tests', () => {
+  let kpiService: KpiService
+  let mockKpiRepository: MockRepository<Kpi>
+  let mockKpiHistoryRepository: MockRepository<KpiHistory>
+  let mockDomainRepository: MockRepository<Domain>
+
+  let testDomain: Domain
+  let testUser: User
+
+  beforeEach(() => {
+    // Mock 리포지토리 생성
+    mockKpiRepository = {
+      find: jest.fn(),
+      findOne: jest.fn(),
+      save: jest.fn(),
+      delete: jest.fn(),
+      softDelete: jest.fn(),
+      count: jest.fn(),
+      createQueryBuilder: jest.fn()
+    }
+
+    mockKpiHistoryRepository = {
+      find: jest.fn(),
+      findOne: jest.fn(),
+      save: jest.fn(),
+      delete: jest.fn(),
+      softDelete: jest.fn(),
+      count: jest.fn(),
+      createQueryBuilder: jest.fn()
+    }
+
+    mockDomainRepository = {
+      find: jest.fn(),
+      findOne: jest.fn(),
+      save: jest.fn(),
+      delete: jest.fn(),
+      softDelete: jest.fn(),
+      count: jest.fn(),
+      createQueryBuilder: jest.fn()
+    }
+
+    // 서비스 생성 (의존성 주입)
+    kpiService = new KpiService(
+      mockKpiRepository as Repository<Kpi>,
+      mockKpiHistoryRepository as Repository<KpiHistory>,
+      mockDomainRepository as Repository<Domain>
+    )
+
+    // 테스트용 데이터
+    testDomain = {
+      id: 'domain-123',
+      name: 'TEST_DOMAIN',
+      description: 'Test Domain'
+    } as Domain
+
+    testUser = {
+      id: 'user-123',
+      name: 'Test User',
+      email: 'test@example.com',
+      domain: testDomain
+    } as User
+  })
+
+  describe('KPI 생성 서비스 테스트', () => {
+    it('새로운 KPI 생성이 성공해야 한다', async () => {
+      // Given
+      const newKpiData = {
+        name: '안전사고율',
+        description: '월별 안전사고 발생률',
+        formula: 'accident_count / total_hours * 1000',
+        isLeaf: true,
+        active: true,
+        state: KpiStatus.DRAFT,
+        vizType: KpiVizType.GAUGE,
+        vizMeta: { unit: '건/천시간', min: 0, max: 10 }
+      }
+
+      const expectedKpi = {
+        id: 'kpi-123',
+        ...newKpiData,
+        version: 1,
+        domain: testDomain,
+        creator: testUser,
+        createdAt: new Date(),
+        updatedAt: new Date()
+      } as Kpi
+
+      mockKpiRepository.save.mockResolvedValue(expectedKpi)
+
+      // When
+      const result = await kpiService.createKpi(newKpiData, testUser, testDomain)
+
+      // Then
+      expect(result).toEqual(expectedKpi)
+      expect(mockKpiRepository.save).toHaveBeenCalledWith(
+        expect.objectContaining({
+          name: '안전사고율',
+          formula: 'accident_count / total_hours * 1000',
+          version: 1,
+          domain: testDomain,
+          creator: testUser
+        })
+      )
+    })
+
+    it('부모 KPI가 있는 하위 KPI 생성이 성공해야 한다', async () => {
+      // Given
+      const parentKpi = {
+        id: 'parent-kpi-123',
+        name: '전체 안전 지수',
+        isLeaf: false
+      } as Kpi
+
+      const childKpiData = {
+        name: '안전사고율',
+        parent: { id: parentKpi.id },
+        isLeaf: true,
+        formula: 'accident_count / total_hours'
+      }
+
+      mockKpiRepository.findOne.mockResolvedValue(parentKpi)
+      mockKpiRepository.save.mockResolvedValue({
+        id: 'child-kpi-123',
+        ...childKpiData,
+        parent: parentKpi,
+        domain: testDomain,
+        creator: testUser
+      } as Kpi)
+
+      // When
+      const result = await kpiService.createKpi(childKpiData, testUser, testDomain)
+
+      // Then
+      expect(result.parent).toEqual(parentKpi)
+      expect(mockKpiRepository.findOne).toHaveBeenCalledWith({
+        where: { id: parentKpi.id, domain: { id: testDomain.id } }
+      })
+    })
+
+    it('존재하지 않는 부모 KPI 참조 시 에러가 발생해야 한다', async () => {
+      // Given
+      const invalidChildKpiData = {
+        name: '잘못된 하위 KPI',
+        parent: { id: 'non-existent-parent' },
+        isLeaf: true
+      }
+
+      mockKpiRepository.findOne.mockResolvedValue(null)
+
+      // When & Then
+      await expect(kpiService.createKpi(invalidChildKpiData, testUser, testDomain))
+        .rejects.toThrow('Parent KPI not found: non-existent-parent')
+    })
+
+    it('중복된 KPI 이름으로 생성 시 에러가 발생해야 한다', async () => {
+      // Given
+      const duplicateKpiData = {
+        name: '중복 KPI',
+        isLeaf: true
+      }
+
+      mockKpiRepository.findOne.mockResolvedValue({
+        id: 'existing-kpi-123',
+        name: '중복 KPI'
+      } as Kpi)
+
+      // When & Then
+      await expect(kpiService.createKpi(duplicateKpiData, testUser, testDomain))
+        .rejects.toThrow('KPI with name "중복 KPI" already exists in this domain')
+    })
+  })
+
+  describe('KPI 수정 서비스 테스트', () => {
+    it('DRAFT 상태 KPI 수정이 성공해야 한다', async () => {
+      // Given
+      const existingKpi = {
+        id: 'kpi-123',
+        name: '기존 KPI',
+        formula: 'old_formula',
+        state: KpiStatus.DRAFT,
+        version: 1,
+        domain: testDomain
+      } as Kpi
+
+      const updateData = {
+        name: '수정된 KPI',
+        formula: 'new_formula',
+        description: '수정된 설명'
+      }
+
+      const updatedKpi = {
+        ...existingKpi,
+        ...updateData,
+        version: 2,
+        updatedAt: new Date()
+      } as Kpi
+
+      mockKpiRepository.findOne.mockResolvedValue(existingKpi)
+      mockKpiRepository.save.mockResolvedValue(updatedKpi)
+
+      // When
+      const result = await kpiService.updateKpi('kpi-123', updateData, testUser, testDomain)
+
+      // Then
+      expect(result.name).toBe('수정된 KPI')
+      expect(result.formula).toBe('new_formula')
+      expect(result.version).toBe(2)
+      expect(mockKpiRepository.save).toHaveBeenCalledWith(
+        expect.objectContaining({
+          name: '수정된 KPI',
+          formula: 'new_formula',
+          version: 2
+        })
+      )
+    })
+
+    it('RELEASE 상태 KPI 수정 시 버전이 증가하고 DRAFT로 변경되어야 한다', async () => {
+      // Given
+      const releasedKpi = {
+        id: 'kpi-123',
+        name: '릴리즈된 KPI',
+        formula: 'released_formula',
+        state: KpiStatus.RELEASE,
+        version: 3,
+        domain: testDomain
+      } as Kpi
+
+      const updateData = {
+        formula: 'modified_formula'
+      }
+
+      mockKpiRepository.findOne.mockResolvedValue(releasedKpi)
+      mockKpiHistoryRepository.save.mockResolvedValue({} as KpiHistory) // 히스토리 저장
+      mockKpiRepository.save.mockResolvedValue({
+        ...releasedKpi,
+        formula: 'modified_formula',
+        state: KpiStatus.DRAFT,
+        version: 4
+      } as Kpi)
+
+      // When
+      const result = await kpiService.updateKpi('kpi-123', updateData, testUser, testDomain)
+
+      // Then
+      expect(result.formula).toBe('modified_formula')
+      expect(result.state).toBe(KpiStatus.DRAFT)
+      expect(result.version).toBe(4)
+
+      // 히스토리가 저장되었는지 확인
+      expect(mockKpiHistoryRepository.save).toHaveBeenCalledWith(
+        expect.objectContaining({
+          kpi: expect.objectContaining({ id: 'kpi-123' }),
+          version: 3,
+          snapshot: expect.any(Object)
+        })
+      )
+    })
+
+    it('ARCHIVED 상태 KPI는 수정할 수 없어야 한다', async () => {
+      // Given
+      const archivedKpi = {
+        id: 'kpi-123',
+        name: '폐기된 KPI',
+        state: KpiStatus.ARCHIVED,
+        domain: testDomain
+      } as Kpi
+
+      mockKpiRepository.findOne.mockResolvedValue(archivedKpi)
+
+      // When & Then
+      await expect(kpiService.updateKpi('kpi-123', { name: '수정 시도' }, testUser, testDomain))
+        .rejects.toThrow('Cannot modify archived KPI')
+    })
+  })
+
+  describe('KPI 삭제 서비스 테스트', () => {
+    it('하위 KPI가 없는 KPI 삭제가 성공해야 한다', async () => {
+      // Given
+      const kpiToDelete = {
+        id: 'kpi-123',
+        name: '삭제할 KPI',
+        isLeaf: true,
+        domain: testDomain
+      } as Kpi
+
+      mockKpiRepository.findOne.mockResolvedValue(kpiToDelete)
+      mockKpiRepository.find.mockResolvedValue([]) // 하위 KPI 없음
+      mockKpiRepository.softDelete.mockResolvedValue({ affected: 1 })
+
+      // When
+      const result = await kpiService.deleteKpi('kpi-123', testUser, testDomain)
+
+      // Then
+      expect(result).toBe(true)
+      expect(mockKpiRepository.softDelete).toHaveBeenCalledWith('kpi-123')
+    })
+
+    it('하위 KPI가 있는 부모 KPI 삭제 시 에러가 발생해야 한다', async () => {
+      // Given
+      const parentKpi = {
+        id: 'parent-kpi-123',
+        name: '부모 KPI',
+        isLeaf: false,
+        domain: testDomain
+      } as Kpi
+
+      const childKpis = [
+        { id: 'child-1', name: '하위 KPI 1' },
+        { id: 'child-2', name: '하위 KPI 2' }
+      ] as Kpi[]
+
+      mockKpiRepository.findOne.mockResolvedValue(parentKpi)
+      mockKpiRepository.find.mockResolvedValue(childKpis)
+
+      // When & Then
+      await expect(kpiService.deleteKpi('parent-kpi-123', testUser, testDomain))
+        .rejects.toThrow('Cannot delete KPI with child KPIs. Found 2 child KPIs.')
+    })
+
+    it('존재하지 않는 KPI 삭제 시 에러가 발생해야 한다', async () => {
+      // Given
+      mockKpiRepository.findOne.mockResolvedValue(null)
+
+      // When & Then
+      await expect(kpiService.deleteKpi('non-existent-kpi', testUser, testDomain))
+        .rejects.toThrow('KPI not found: non-existent-kpi')
+    })
+  })
+
+  describe('KPI 릴리즈 서비스 테스트', () => {
+    it('DRAFT 상태 KPI 릴리즈가 성공해야 한다', async () => {
+      // Given
+      const draftKpi = {
+        id: 'kpi-123',
+        name: '드래프트 KPI',
+        formula: 'valid_formula',
+        state: KpiStatus.DRAFT,
+        version: 2,
+        domain: testDomain
+      } as Kpi
+
+      mockKpiRepository.findOne.mockResolvedValue(draftKpi)
+      mockKpiHistoryRepository.save.mockResolvedValue({} as KpiHistory)
+      mockKpiRepository.save.mockResolvedValue({
+        ...draftKpi,
+        state: KpiStatus.RELEASE,
+        version: 3
+      } as Kpi)
+
+      // When
+      const result = await kpiService.releaseKpi('kpi-123', testUser, testDomain)
+
+      // Then
+      expect(result.state).toBe(KpiStatus.RELEASE)
+      expect(result.version).toBe(3)
+
+      // 릴리즈 전 상태가 히스토리에 저장되었는지 확인
+      expect(mockKpiHistoryRepository.save).toHaveBeenCalledWith(
+        expect.objectContaining({
+          kpi: expect.objectContaining({ id: 'kpi-123' }),
+          version: 2,
+          action: 'RELEASE',
+          snapshot: expect.any(Object)
+        })
+      )
+    })
+
+    it('수식이 없는 leaf KPI 릴리즈 시 에러가 발생해야 한다', async () => {
+      // Given
+      const invalidKpi = {
+        id: 'kpi-123',
+        name: '잘못된 KPI',
+        formula: null,
+        isLeaf: true,
+        state: KpiStatus.DRAFT,
+        domain: testDomain
+      } as Kpi
+
+      mockKpiRepository.findOne.mockResolvedValue(invalidKpi)
+
+      // When & Then
+      await expect(kpiService.releaseKpi('kpi-123', testUser, testDomain))
+        .rejects.toThrow('Cannot release leaf KPI without formula')
+    })
+
+    it('이미 RELEASE 상태인 KPI 릴리즈 시 에러가 발생해야 한다', async () => {
+      // Given
+      const releasedKpi = {
+        id: 'kpi-123',
+        name: '이미 릴리즈된 KPI',
+        state: KpiStatus.RELEASE,
+        domain: testDomain
+      } as Kpi
+
+      mockKpiRepository.findOne.mockResolvedValue(releasedKpi)
+
+      // When & Then
+      await expect(kpiService.releaseKpi('kpi-123', testUser, testDomain))
+        .rejects.toThrow('KPI is already in RELEASE state')
+    })
+  })
+
+  describe('KPI 조회 서비스 테스트', () => {
+    it('페이지네이션을 포함한 KPI 목록 조회가 성공해야 한다', async () => {
+      // Given
+      const mockKpis = [
+        { id: 'kpi-1', name: 'KPI 1' },
+        { id: 'kpi-2', name: 'KPI 2' },
+        { id: 'kpi-3', name: 'KPI 3' }
+      ] as Kpi[]
+
+      const mockQueryBuilder = {
+        where: jest.fn().mockReturnThis(),
+        andWhere: jest.fn().mockReturnThis(),
+        orderBy: jest.fn().mockReturnThis(),
+        skip: jest.fn().mockReturnThis(),
+        take: jest.fn().mockReturnThis(),
+        getManyAndCount: jest.fn().mockResolvedValue([mockKpis, 15])
+      }
+
+      mockKpiRepository.createQueryBuilder.mockReturnValue(mockQueryBuilder)
+
+      const queryOptions = {
+        page: 1,
+        limit: 10,
+        sortBy: 'name',
+        sortDirection: 'ASC' as const,
+        filters: {
+          active: true,
+          state: KpiStatus.RELEASE
+        }
+      }
+
+      // When
+      const result = await kpiService.getKpiList(testDomain, queryOptions)
+
+      // Then
+      expect(result.items).toEqual(mockKpis)
+      expect(result.total).toBe(15)
+      expect(result.page).toBe(1)
+      expect(result.pageSize).toBe(10)
+      expect(result.totalPages).toBe(2)
+
+      expect(mockQueryBuilder.where).toHaveBeenCalledWith('kpi.domainId = :domainId', { domainId: testDomain.id })
+      expect(mockQueryBuilder.andWhere).toHaveBeenCalledWith('kpi.active = :active', { active: true })
+      expect(mockQueryBuilder.andWhere).toHaveBeenCalledWith('kpi.state = :state', { state: KpiStatus.RELEASE })
+      expect(mockQueryBuilder.orderBy).toHaveBeenCalledWith('kpi.name', 'ASC')
+      expect(mockQueryBuilder.skip).toHaveBeenCalledWith(0)
+      expect(mockQueryBuilder.take).toHaveBeenCalledWith(10)
+    })
+
+    it('계층 구조를 포함한 KPI 상세 조회가 성공해야 한다', async () => {
+      // Given
+      const mockKpi = {
+        id: 'kpi-123',
+        name: '테스트 KPI',
+        parent: { id: 'parent-123', name: '부모 KPI' },
+        children: [
+          { id: 'child-1', name: '하위 KPI 1' },
+          { id: 'child-2', name: '하위 KPI 2' }
+        ]
+      } as Kpi
+
+      mockKpiRepository.findOne.mockResolvedValue(mockKpi)
+
+      // When
+      const result = await kpiService.getKpiById('kpi-123', testDomain, {
+        includeParent: true,
+        includeChildren: true,
+        includeHistory: false
+      })
+
+      // Then
+      expect(result).toEqual(mockKpi)
+      expect(mockKpiRepository.findOne).toHaveBeenCalledWith({
+        where: { id: 'kpi-123', domain: { id: testDomain.id } },
+        relations: ['parent', 'children']
+      })
+    })
+
+    it('검색 조건을 포함한 KPI 조회가 성공해야 한다', async () => {
+      // Given
+      const mockQueryBuilder = {
+        where: jest.fn().mockReturnThis(),
+        andWhere: jest.fn().mockReturnThis(),
+        orderBy: jest.fn().mockReturnThis(),
+        getMany: jest.fn().mockResolvedValue([
+          { id: 'kpi-1', name: '안전 관련 KPI' },
+          { id: 'kpi-2', name: '안전사고율' }
+        ])
+      }
+
+      mockKpiRepository.createQueryBuilder.mockReturnValue(mockQueryBuilder)
+
+      // When
+      const result = await kpiService.searchKpis(testDomain, {
+        keyword: '안전',
+        category: 'SAFETY',
+        isLeaf: true,
+        active: true
+      })
+
+      // Then
+      expect(result).toHaveLength(2)
+      expect(mockQueryBuilder.andWhere).toHaveBeenCalledWith(
+        'kpi.name ILIKE :keyword OR kpi.description ILIKE :keyword',
+        { keyword: '%안전%' }
+      )
+    })
+  })
+
+  describe('KPI 계층 구조 서비스 테스트', () => {
+    it('KPI 트리 구조 조회가 성공해야 한다', async () => {
+      // Given
+      const mockKpiTree = [
+        {
+          id: 'root-1',
+          name: '루트 KPI 1',
+          children: [
+            {
+              id: 'child-1-1',
+              name: '하위 KPI 1-1',
+              children: [
+                { id: 'leaf-1-1-1', name: '말단 KPI 1-1-1', children: [] }
+              ]
+            }
+          ]
+        },
+        {
+          id: 'root-2',
+          name: '루트 KPI 2',
+          children: []
+        }
+      ]
+
+      mockKpiRepository.find.mockResolvedValue([
+        { id: 'root-1', name: '루트 KPI 1', parent: null },
+        { id: 'root-2', name: '루트 KPI 2', parent: null },
+        { id: 'child-1-1', name: '하위 KPI 1-1', parent: { id: 'root-1' } },
+        { id: 'leaf-1-1-1', name: '말단 KPI 1-1-1', parent: { id: 'child-1-1' } }
+      ])
+
+      // When
+      const result = await kpiService.getKpiTree(testDomain)
+
+      // Then
+      expect(result).toHaveLength(2)
+      expect(result[0].name).toBe('루트 KPI 1')
+      expect(result[0].children).toHaveLength(1)
+      expect(result[0].children[0].children).toHaveLength(1)
+    })
+
+    it('특정 KPI의 경로(breadcrumb) 조회가 성공해야 한다', async () => {
+      // Given
+      const leafKpi = {
+        id: 'leaf-123',
+        name: '말단 KPI',
+        parent: {
+          id: 'middle-123',
+          name: '중간 KPI',
+          parent: {
+            id: 'root-123',
+            name: '루트 KPI',
+            parent: null
+          }
+        }
+      } as Kpi
+
+      mockKpiRepository.findOne.mockResolvedValue(leafKpi)
+
+      // When
+      const result = await kpiService.getKpiPath('leaf-123', testDomain)
+
+      // Then
+      expect(result).toEqual([
+        { id: 'root-123', name: '루트 KPI' },
+        { id: 'middle-123', name: '중간 KPI' },
+        { id: 'leaf-123', name: '말단 KPI' }
+      ])
+    })
+
+    it('순환 참조 검증이 성공해야 한다', async () => {
+      // Given - A -> B -> C -> A 순환 참조 시도
+      const kpiA = { id: 'kpi-a', name: 'KPI A' } as Kpi
+      const kpiB = { id: 'kpi-b', name: 'KPI B', parent: kpiA } as Kpi
+      const kpiC = { id: 'kpi-c', name: 'KPI C', parent: kpiB } as Kpi
+
+      mockKpiRepository.findOne
+        .mockResolvedValueOnce(kpiC) // kpi-c 조회
+        .mockResolvedValueOnce(kpiB) // kpi-b 조회
+        .mockResolvedValueOnce(kpiA) // kpi-a 조회
+
+      // When & Then - kpi-a의 부모를 kpi-c로 설정하려고 할 때
+      await expect(kpiService.updateKpi('kpi-a', { parent: { id: 'kpi-c' } }, testUser, testDomain))
+        .rejects.toThrow('Circular reference detected in KPI hierarchy')
+    })
+  })
+
+  describe('KPI 복사 서비스 테스트', () => {
+    it('KPI 복사가 성공해야 한다', async () => {
+      // Given
+      const sourceKpi = {
+        id: 'source-kpi-123',
+        name: '원본 KPI',
+        description: '원본 설명',
+        formula: 'source_formula',
+        vizType: KpiVizType.GAUGE,
+        vizMeta: { unit: '%', min: 0, max: 100 },
+        state: KpiStatus.RELEASE,
+        version: 5,
+        domain: testDomain
+      } as Kpi
+
+      const copiedKpi = {
+        id: 'copied-kpi-123',
+        name: '복사된 KPI',
+        description: '원본 설명',
+        formula: 'source_formula',
+        vizType: KpiVizType.GAUGE,
+        vizMeta: { unit: '%', min: 0, max: 100 },
+        state: KpiStatus.DRAFT, // 복사본은 DRAFT로 시작
+        version: 1,
+        domain: testDomain
+      } as Kpi
+
+      mockKpiRepository.findOne.mockResolvedValue(sourceKpi)
+      mockKpiRepository.save.mockResolvedValue(copiedKpi)
+
+      // When
+      const result = await kpiService.copyKpi('source-kpi-123', {
+        name: '복사된 KPI',
+        copyChildren: false
+      }, testUser, testDomain)
+
+      // Then
+      expect(result.name).toBe('복사된 KPI')
+      expect(result.state).toBe(KpiStatus.DRAFT)
+      expect(result.version).toBe(1)
+      expect(result.formula).toBe('source_formula')
+      expect(result.vizMeta).toEqual({ unit: '%', min: 0, max: 100 })
+    })
+
+    it('하위 KPI를 포함한 복사가 성공해야 한다', async () => {
+      // Given
+      const sourceParent = {
+        id: 'parent-123',
+        name: '부모 KPI',
+        children: [
+          { id: 'child-1', name: '하위 KPI 1' },
+          { id: 'child-2', name: '하위 KPI 2' }
+        ]
+      } as Kpi
+
+      mockKpiRepository.findOne.mockResolvedValue(sourceParent)
+      mockKpiRepository.save
+        .mockResolvedValueOnce({ id: 'copied-parent-123', name: '복사된 부모 KPI' } as Kpi)
+        .mockResolvedValueOnce({ id: 'copied-child-1', name: '복사된 하위 KPI 1' } as Kpi)
+        .mockResolvedValueOnce({ id: 'copied-child-2', name: '복사된 하위 KPI 2' } as Kpi)
+
+      // When
+      const result = await kpiService.copyKpi('parent-123', {
+        name: '복사된 부모 KPI',
+        copyChildren: true
+      }, testUser, testDomain)
+
+      // Then
+      expect(mockKpiRepository.save).toHaveBeenCalledTimes(3) // 부모 + 자식 2개
+    })
+  })
+
+  describe('KPI 벌크 작업 서비스 테스트', () => {
+    it('여러 KPI 일괄 활성화가 성공해야 한다', async () => {
+      // Given
+      const kpiIds = ['kpi-1', 'kpi-2', 'kpi-3']
+      const mockQueryBuilder = {
+        update: jest.fn().mockReturnThis(),
+        set: jest.fn().mockReturnThis(),
+        where: jest.fn().mockReturnThis(),
+        andWhere: jest.fn().mockReturnThis(),
+        execute: jest.fn().mockResolvedValue({ affected: 3 })
+      }
+
+      mockKpiRepository.createQueryBuilder.mockReturnValue(mockQueryBuilder)
+
+      // When
+      const result = await kpiService.bulkUpdateKpis(kpiIds, {
+        active: true
+      }, testUser, testDomain)
+
+      // Then
+      expect(result.affected).toBe(3)
+      expect(mockQueryBuilder.set).toHaveBeenCalledWith({ active: true })
+      expect(mockQueryBuilder.where).toHaveBeenCalledWith('id IN (:...ids)', { ids: kpiIds })
+    })
+
+    it('여러 KPI 일괄 삭제가 성공해야 한다', async () => {
+      // Given
+      const kpiIds = ['kpi-1', 'kpi-2']
+
+      // 삭제할 KPI들이 하위 KPI를 가지지 않음을 확인
+      mockKpiRepository.find.mockResolvedValue([])
+
+      const mockQueryBuilder = {
+        softDelete: jest.fn().mockReturnThis(),
+        where: jest.fn().mockReturnThis(),
+        andWhere: jest.fn().mockReturnThis(),
+        execute: jest.fn().mockResolvedValue({ affected: 2 })
+      }
+
+      mockKpiRepository.createQueryBuilder.mockReturnValue(mockQueryBuilder)
+
+      // When
+      const result = await kpiService.bulkDeleteKpis(kpiIds, testUser, testDomain)
+
+      // Then
+      expect(result.deleted).toBe(2)
+      expect(mockQueryBuilder.where).toHaveBeenCalledWith('id IN (:...ids)', { ids: kpiIds })
+    })
+
+    it('하위 KPI가 있는 경우 일괄 삭제가 실패해야 한다', async () => {
+      // Given
+      const kpiIds = ['parent-kpi-1', 'parent-kpi-2']
+
+      // 하위 KPI들이 존재
+      mockKpiRepository.find.mockResolvedValue([
+        { id: 'child-1', name: '하위 KPI 1', parent: { id: 'parent-kpi-1' } }
+      ])
+
+      // When & Then
+      await expect(kpiService.bulkDeleteKpis(kpiIds, testUser, testDomain))
+        .rejects.toThrow('Cannot delete KPIs with child KPIs')
+    })
+  })
+
+  describe('KPI 수식 검증 서비스 테스트', () => {
+    it('유효한 수식 검증이 성공해야 한다', async () => {
+      // Given
+      const validFormulas = [
+        'metric1 + metric2',
+        'sum(metric1, metric2) / count',
+        'if(metric1 > 0, metric2 / metric1 * 100, 0)',
+        'round(avg(metric1, metric2, metric3), 2)'
+      ]
+
+      // When & Then
+      for (const formula of validFormulas) {
+        const result = await kpiService.validateFormula(formula, testDomain)
+        expect(result.valid).toBe(true)
+        expect(result.errors).toHaveLength(0)
+      }
+    })
+
+    it('잘못된 수식 검증이 실패해야 한다', async () => {
+      // Given
+      const invalidFormulas = [
+        { formula: 'metric1 +', expectedError: 'Incomplete expression' },
+        { formula: 'unknown_func(metric1)', expectedError: 'Unknown function: unknown_func' },
+        { formula: 'if(metric1)', expectedError: 'Invalid number of arguments for function: if' },
+        { formula: 'metric1 ** metric2', expectedError: 'Unsupported operator: **' }
+      ]
+
+      // When & Then
+      for (const testCase of invalidFormulas) {
+        const result = await kpiService.validateFormula(testCase.formula, testDomain)
+        expect(result.valid).toBe(false)
+        expect(result.errors).toContain(testCase.expectedError)
+      }
+    })
+
+    it('수식에 사용된 메트릭 추출이 성공해야 한다', async () => {
+      // Given
+      const formula = 'defect_count / total_count * 100 + adjustment_factor'
+
+      // When
+      const result = await kpiService.extractMetricsFromFormula(formula)
+
+      // Then
+      expect(result).toEqual(['defect_count', 'total_count', 'adjustment_factor'])
+    })
+  })
+})
+```
+
+## 5. KPI 값 계산 서비스 테스트 (kpi-value-calculation.spec.ts)
+
+```typescript
+import { describe, it, expect, beforeEach, jest } from '@jest/globals'
+import { KpiValueCalculationService } from '../server/service/kpi-value/kpi-value-calculation.service'
+import { KpiValue } from '../server/service/kpi-value/kpi-value'
+import { Kpi } from '../server/service/kpi/kpi'
+import { KpiMetric } from '../server/service/kpi-metric/kpi-metric'
+import { DataSample } from '@things-factory/dataset'
+
+describe('KPI Value Calculation Service Tests', () => {
+  let calculationService: KpiValueCalculationService
+  let mockValueProvider: jest.Mock
+  let mockDataSampleRepository: jest.Mock
+
+  beforeEach(() => {
+    mockValueProvider = jest.fn()
+    mockDataSampleRepository = jest.fn()
+
+    calculationService = new KpiValueCalculationService(
+      mockDataSampleRepository,
+      mockValueProvider
+    )
+  })
+
+  describe('메트릭 기반 KPI 값 계산 테스트', () => {
+    it('간단한 비율 계산이 정확해야 한다', async () => {
+      // Given
+      const kpi = {
+        id: 'kpi-123',
+        name: '불량률',
+        formula: 'defect_count / total_count * 100',
+        metrics: [
+          { code: 'defect_count', datasetId: 'quality-ds' },
+          { code: 'total_count', datasetId: 'quality-ds' }
+        ]
+      } as any
+
+      mockValueProvider
+        .mockResolvedValueOnce(25)   // defect_count
+        .mockResolvedValueOnce(1000) // total_count
+
+      // When
+      const result = await calculationService.calculateKpiValue(kpi, {
+        startDate: new Date('2024-01-01'),
+        endDate: new Date('2024-01-31'),
+        orgScopeId: 'org-123'
+      })
+
+      // Then
+      expect(result.value).toBe(2.5) // 25 / 1000 * 100
+      expect(result.formula).toBe('defect_count / total_count * 100')
+      expect(result.calculatedAt).toBeDefined()
+    })
+
+    it('복합 수식 계산이 정확해야 한다', async () => {
+      // Given
+      const kpi = {
+        id: 'kpi-456',
+        name: '종합 성과 지수',
+        formula: 'round((quality_score * 0.4 + efficiency_score * 0.3 + safety_score * 0.3), 2)',
+        metrics: [
+          { code: 'quality_score', datasetId: 'kpi-ds' },
+          { code: 'efficiency_score', datasetId: 'kpi-ds' },
+          { code: 'safety_score', datasetId: 'kpi-ds' }
+        ]
+      } as any
+
+      mockValueProvider
+        .mockResolvedValueOnce(85)  // quality_score
+        .mockResolvedValueOnce(90)  // efficiency_score
+        .mockResolvedValueOnce(88)  // safety_score
+
+      // When
+      const result = await calculationService.calculateKpiValue(kpi, {
+        startDate: new Date('2024-01-01'),
+        endDate: new Date('2024-01-31'),
+        orgScopeId: 'org-123'
+      })
+
+      // Then
+      // 85*0.4 + 90*0.3 + 88*0.3 = 34 + 27 + 26.4 = 87.4
+      expect(result.value).toBe(87.4)
+    })
+
+    it('Zero Division 방지 로직이 동작해야 한다', async () => {
+      // Given
+      const kpi = {
+        id: 'kpi-789',
+        name: '생산성',
+        formula: 'if(input_hours > 0, output_qty / input_hours, 0)',
+        metrics: [
+          { code: 'output_qty', datasetId: 'prod-ds' },
+          { code: 'input_hours', datasetId: 'prod-ds' }
+        ]
+      } as any
+
+      mockValueProvider
+        .mockResolvedValueOnce(1200) // output_qty
+        .mockResolvedValueOnce(0)    // input_hours (0으로 나누기 상황)
+
+      // When
+      const result = await calculationService.calculateKpiValue(kpi, {
+        startDate: new Date('2024-01-01'),
+        endDate: new Date('2024-01-31'),
+        orgScopeId: 'org-123'
+      })
+
+      // Then
+      expect(result.value).toBe(0) // Zero division 방지로 0 반환
+    })
+  })
+
+  describe('시계열 집계 계산 테스트', () => {
+    it('일별 데이터를 월별로 집계가 정확해야 한다', async () => {
+      // Given
+      const kpi = {
+        id: 'kpi-daily',
+        name: '일일 처리량 월평균',
+        formula: 'avg(daily_volume)',
+        periodType: 'MONTH',
+        metrics: [{ code: 'daily_volume', datasetId: 'volume-ds' }]
+      } as any
+
+      const mockDailySamples = [
+        { date: '2024-01-01', value: 100 },
+        { date: '2024-01-02', value: 120 },
+        { date: '2024-01-03', value: 110 },
+        // ... 31일간 데이터
+      ]
+
+      mockDataSampleRepository.mockResolvedValue(mockDailySamples)
+
+      // When
+      const result = await calculationService.calculateKpiValueWithAggregation(kpi, {
+        startDate: new Date('2024-01-01'),
+        endDate: new Date('2024-01-31'),
+        aggregationType: 'MONTHLY',
+        orgScopeId: 'org-123'
+      })
+
+      // Then
+      expect(result.aggregationType).toBe('MONTHLY')
+      expect(result.sourceDataCount).toBe(mockDailySamples.length)
+      expect(result.value).toBeGreaterThan(0)
+    })
+
+    it('주간 단위 집계가 정확해야 한다', async () => {
+      // Given
+      const kpi = {
+        id: 'kpi-weekly',
+        name: '주간 안전 점수',
+        formula: 'sum(weekly_safety_incidents)',
+        periodType: 'WEEK',
+        metrics: [{ code: 'weekly_safety_incidents', datasetId: 'safety-ds' }]
+      } as any
+
+      const mockWeeklyData = [
+        { week: 1, value: 2 },
+        { week: 2, value: 1 },
+        { week: 3, value: 3 },
+        { week: 4, value: 0 }
+      ]
+
+      mockValueProvider.mockImplementation((metric) => {
+        return Promise.resolve(mockWeeklyData.reduce((sum, d) => sum + d.value, 0))
+      })
+
+      // When
+      const result = await calculationService.calculateKpiValue(kpi, {
+        startDate: new Date('2024-01-01'),
+        endDate: new Date('2024-01-28'),
+        aggregationType: 'WEEKLY',
+        orgScopeId: 'org-123'
+      })
+
+      // Then
+      expect(result.value).toBe(6) // 2 + 1 + 3 + 0 = 6
+    })
+  })
+
+  describe('성과 점수 계산 테스트', () => {
+    it('등급 기반 점수 계산이 정확해야 한다', async () => {
+      // Given
+      const kpi = {
+        id: 'kpi-grade',
+        name: '품질 등급',
+        grades: {
+          'A': { minValue: 90, maxValue: 100, score: 100, color: '#43a047' },
+          'B': { minValue: 80, maxValue: 90, score: 80, color: '#66bb6a' },
+          'C': { minValue: 70, maxValue: 80, score: 60, color: '#ffeb3b' },
+          'D': { minValue: 60, maxValue: 70, score: 40, color: '#ffa726' },
+          'F': { minValue: 0, maxValue: 60, score: 20, color: '#ff4757' }
+        }
+      } as any
+
+      const testCases = [
+        { value: 95, expectedScore: 100, expectedGrade: 'A' },
+        { value: 85, expectedScore: 80, expectedGrade: 'B' },
+        { value: 75, expectedScore: 60, expectedGrade: 'C' },
+        { value: 65, expectedScore: 40, expectedGrade: 'D' },
+        { value: 55, expectedScore: 20, expectedGrade: 'F' }
+      ]
+
+      for (const testCase of testCases) {
+        // When
+        const result = await calculationService.calculatePerformanceScore(
+          testCase.value,
+          kpi
+        )
+
+        // Then
+        expect(result.score).toBe(testCase.expectedScore)
+        expect(result.grade).toBe(testCase.expectedGrade)
+        expect(result.color).toBeDefined()
+      }
+    })
+
+    it('수식 기반 점수 계산이 정확해야 한다', async () => {
+      // Given
+      const kpi = {
+        id: 'kpi-formula-score',
+        name: '효율성 지수',
+        scoreFormula: 'if(value >= 95, 100, if(value >= 85, value * 0.9 + 15, value * 0.7))'
+      } as any
+
+      const testCases = [
+        { value: 98, expectedScore: 100 },      // >= 95: 100점
+        { value: 90, expectedScore: 96 },       // 85~95: 90*0.9+15 = 96
+        { value: 80, expectedScore: 56 }        // < 85: 80*0.7 = 56
+      ]
+
+      for (const testCase of testCases) {
+        // When
+        const result = await calculationService.calculatePerformanceScore(
+          testCase.value,
+          kpi
+        )
+
+        // Then
+        expect(result.score).toBe(testCase.expectedScore)
+      }
+    })
+
+    it('성과 지수 함수 기반 점수 계산이 정확해야 한다', async () => {
+      // Given
+      const kpi = {
+        id: 'kpi-performance-index',
+        name: '성과 지수',
+        scoreFormula: 'performance_index(value, 2.5, 3.2, 2.0, 3.5) * 100'
+      } as any
+
+      // When
+      const result = await calculationService.calculatePerformanceScore(0.85, kpi)
+
+      // Then
+      expect(result.score).toBeGreaterThanOrEqual(0)
+      expect(result.score).toBeLessThanOrEqual(100)
+      expect(Number.isFinite(result.score)).toBe(true)
+    })
+  })
+
+  describe('계산 에러 처리 테스트', () => {
+    it('메트릭 데이터가 없을 때 기본값 반환해야 한다', async () => {
+      // Given
+      const kpi = {
+        id: 'kpi-no-data',
+        name: '데이터 없는 KPI',
+        formula: 'missing_metric * 100',
+        metrics: [{ code: 'missing_metric', datasetId: 'empty-ds' }]
+      } as any
+
+      mockValueProvider.mockRejectedValue(new Error('No data found'))
+
+      // When
+      const result = await calculationService.calculateKpiValue(kpi, {
+        startDate: new Date('2024-01-01'),
+        endDate: new Date('2024-01-31'),
+        orgScopeId: 'org-123',
+        defaultValue: 0
+      })
+
+      // Then
+      expect(result.value).toBe(0)
+      expect(result.error).toBeDefined()
+      expect(result.error.message).toContain('No data found')
+    })
+
+    it('수식 계산 오류 시 적절한 에러 메시지를 반환해야 한다', async () => {
+      // Given
+      const kpi = {
+        id: 'kpi-invalid-formula',
+        name: '잘못된 수식 KPI',
+        formula: 'log(-1)', // 음수의 로그 (수학적 오류)
+        metrics: []
+      } as any
+
+      // When & Then
+      await expect(calculationService.calculateKpiValue(kpi, {
+        startDate: new Date('2024-01-01'),
+        endDate: new Date('2024-01-31'),
+        orgScopeId: 'org-123'
+      })).rejects.toThrow('Math domain error')
+    })
+
+    it('타임아웃 처리가 정상 동작해야 한다', async () => {
+      // Given
+      const kpi = {
+        id: 'kpi-timeout',
+        name: '타임아웃 KPI',
+        formula: 'slow_function(metric1)',
+        metrics: [{ code: 'metric1', datasetId: 'slow-ds' }]
+      } as any
+
+      // 10초 후에 응답하는 느린 함수 모킹
+      mockValueProvider.mockImplementation(() =>
+        new Promise(resolve => setTimeout(() => resolve(100), 10000))
+      )
+
+      // When & Then
+      await expect(calculationService.calculateKpiValue(kpi, {
+        startDate: new Date('2024-01-01'),
+        endDate: new Date('2024-01-31'),
+        orgScopeId: 'org-123',
+        timeout: 1000 // 1초 타임아웃
+      })).rejects.toThrow('Calculation timeout')
+    })
+  })
+
+  describe('배치 계산 테스트', () => {
+    it('여러 KPI 일괄 계산이 성공해야 한다', async () => {
+      // Given
+      const kpis = [
+        {
+          id: 'kpi-1',
+          name: 'KPI 1',
+          formula: 'metric1 * 100',
+          metrics: [{ code: 'metric1', datasetId: 'ds1' }]
+        },
+        {
+          id: 'kpi-2',
+          name: 'KPI 2',
+          formula: 'metric2 / 10',
+          metrics: [{ code: 'metric2', datasetId: 'ds2' }]
+        }
+      ] as any[]
+
+      mockValueProvider
+        .mockResolvedValueOnce(1.5)  // metric1
+        .mockResolvedValueOnce(200)  // metric2
+
+      // When
+      const results = await calculationService.calculateMultipleKpis(kpis, {
+        startDate: new Date('2024-01-01'),
+        endDate: new Date('2024-01-31'),
+        orgScopeId: 'org-123'
+      })
+
+      // Then
+      expect(results).toHaveLength(2)
+      expect(results[0].kpiId).toBe('kpi-1')
+      expect(results[0].value).toBe(150) // 1.5 * 100
+      expect(results[1].kpiId).toBe('kpi-2')
+      expect(results[1].value).toBe(20)  // 200 / 10
+    })
+
+    it('배치 계산 중 일부 실패해도 나머지는 계속 처리되어야 한다', async () => {
+      // Given
+      const kpis = [
+        { id: 'kpi-success', formula: 'metric1', metrics: [{ code: 'metric1' }] },
+        { id: 'kpi-fail', formula: 'missing_metric', metrics: [{ code: 'missing_metric' }] },
+        { id: 'kpi-success2', formula: 'metric2', metrics: [{ code: 'metric2' }] }
+      ] as any[]
+
+      mockValueProvider
+        .mockResolvedValueOnce(100)  // metric1 (성공)
+        .mockRejectedValueOnce(new Error('Data not found'))  // missing_metric (실패)
+        .mockResolvedValueOnce(200)  // metric2 (성공)
+
+      // When
+      const results = await calculationService.calculateMultipleKpis(kpis, {
+        startDate: new Date('2024-01-01'),
+        endDate: new Date('2024-01-31'),
+        orgScopeId: 'org-123',
+        continueOnError: true
+      })
+
+      // Then
+      expect(results).toHaveLength(3)
+      expect(results[0].success).toBe(true)
+      expect(results[0].value).toBe(100)
+      expect(results[1].success).toBe(false)
+      expect(results[1].error).toBeDefined()
+      expect(results[2].success).toBe(true)
+      expect(results[2].value).toBe(200)
+    })
+  })
+
+  describe('캐싱 메커니즘 테스트', () => {
+    it('동일한 조건의 계산 결과가 캐시되어야 한다', async () => {
+      // Given
+      const kpi = {
+        id: 'kpi-cache-test',
+        name: '캐시 테스트 KPI',
+        formula: 'expensive_calculation(metric1)',
+        metrics: [{ code: 'metric1', datasetId: 'cache-ds' }]
+      } as any
+
+      const calculationParams = {
+        startDate: new Date('2024-01-01'),
+        endDate: new Date('2024-01-31'),
+        orgScopeId: 'org-123'
+      }
+
+      mockValueProvider.mockResolvedValue(500)
+
+      // When - 첫 번째 호출
+      const result1 = await calculationService.calculateKpiValue(kpi, calculationParams)
+
+      // When - 동일한 조건으로 두 번째 호출
+      const result2 = await calculationService.calculateKpiValue(kpi, calculationParams)
+
+      // Then
+      expect(result1.value).toBe(result2.value)
+      expect(result2.fromCache).toBe(true)
+      expect(mockValueProvider).toHaveBeenCalledTimes(1) // 첫 번째만 실제 계산
+    })
+
+    it('캐시 만료 후 재계산이 수행되어야 한다', async () => {
+      // Given
+      const kpi = {
+        id: 'kpi-cache-expire',
+        name: '캐시 만료 테스트',
+        formula: 'time_sensitive_metric',
+        cacheExpiry: 100 // 100ms 후 만료
+      } as any
+
+      mockValueProvider
+        .mockResolvedValueOnce(100) // 첫 번째 호출
+        .mockResolvedValueOnce(200) // 캐시 만료 후 두 번째 호출
+
+      const params = {
+        startDate: new Date('2024-01-01'),
+        endDate: new Date('2024-01-31'),
+        orgScopeId: 'org-123'
+      }
+
+      // When
+      const result1 = await calculationService.calculateKpiValue(kpi, params)
+
+      // 캐시 만료 대기
+      await new Promise(resolve => setTimeout(resolve, 150))
+
+      const result2 = await calculationService.calculateKpiValue(kpi, params)
+
+      // Then
+      expect(result1.value).toBe(100)
+      expect(result2.value).toBe(200)
+      expect(result2.fromCache).toBe(false)
+      expect(mockValueProvider).toHaveBeenCalledTimes(2)
+    })
+  })
+})
+```
+
+단위 테스트를 매우 상세하게 작성했습니다. 주요 특징:
+
+1. **Mock 활용**: 외부 의존성을 모킹하여 격리된 테스트 환경 구성
+2. **Given-When-Then 패턴**: 명확한 테스트 구조
+3. **Edge Case 포함**: Zero Division, 타임아웃, 에러 처리 등
+4. **실제 사용 시나리오**: 복합 수식, 계층 구조, 배치 처리 등
+5. **성능 테스트**: 대용량 데이터, 캐싱 메커니즘
+6. **검증 로직**: 입력 검증, 순환 참조 검사 등
+
+각 테스트는 실제 production 환경에서 발생할 수 있는 상황들을 다루고 있어 실용적입니다.
+
+<function_calls>
+<invoke name="TodoWrite">
+<parameter name="todos">[{"content": "Create detailed unit test code examples for KPI module", "status": "completed", "activeForm": "Creating detailed unit test code examples for KPI module"}, {"content": "Write comprehensive entity validation tests", "status": "completed", "activeForm": "Writing comprehensive entity validation tests"}, {"content": "Create formula calculator test cases with edge cases", "status": "completed", "activeForm": "Creating formula calculator test cases with edge cases"}, {"content": "Write KPI value management test scenarios", "status": "completed", "activeForm": "Writing KPI value management test scenarios"}, {"content": "Add service layer unit tests with mocking", "status": "completed", "activeForm": "Adding service layer unit tests with mocking"}]