# KPI 모듈 개요

## 1. KPI란?

- KPI(Key Performance Indicator)는 조직의 목표 달성도를 수치로 측정/관리하는 핵심 지표입니다.
- KPI는 산식(formula), 목표값(target), 버전(version), 상태(state) 등 다양한 속성을 가집니다.
- KPI의 실적값(Performance Value)은 특정 시점/조직/프로젝트별로 기록됩니다.

## 2. KPI 모듈의 주요 엔티티

- **Kpi**: KPI 정의(이름, 산식, 카테고리, 상태, 버전 등)
- **KpiValue**: KPI별 실적값(날짜, 값, 입력방식, 소스 등)
- **KpiMetric**: KPI 산식에 사용되는 원천 데이터 항목(코드, 단위, 데이터셋 등)
- **KpiGrade**: KPI별 등급/구간(구간별 점수, 색상 등)
- **KpiHistory**: KPI의 버전별 이력(스냅샷)

## 3. Dataset 모듈과의 관계

KPI 모듈은 Dataset 모듈의 RAW 데이터를 기반으로 KPI 실적을 산출/관리합니다.

### 3.1 Dataset 모듈이란?

- **Dataset**: 다양한 원천 데이터(센서, 수기입력, 외부시스템 등)를 수집/정의/저장하는 모듈
- **DataSample**: 실제 수집된 데이터 샘플(시간, 값, 입력자 등)
- **DataSpec, DataKeySet 등**: 데이터 구조, 키, 스펙 정의

### 3.2 KPI와 Dataset의 연결 구조

- **KpiMetric ↔ Dataset**: KpiMetric은 KPI 산식에 사용되는 원천 데이터 항목을 정의하며, 각 Metric은 Dataset(원천 데이터셋)의 특정 필드/코드와 연결됩니다.
- **Kpi.formula**: KPI의 formula는 여러 Metric(코드)와 연산자를 조합한 문자열입니다.
- **KpiValue의 생성**: KPI 실적값(KpiValue)은 관련 Dataset에서 Metric별 RAW 데이터를 집계/가공하여 formula에 따라 계산된 결과로 생성/저장됩니다.
- **자동/수동 입력**: 일부 KPI는 Dataset에서 자동 집계, 일부는 수기로 입력 가능합니다.

## 4. 전반적 흐름/관계 요약

```mermaid
graph TD
  DS[Dataset] -- 원천데이터 --> M[KpiMetric]
  M -- 산식코드 --> K[Kpi]
  K -- 계산/집계 --> V[KpiValue]
  DS -. 수집/입력 .-> S[DataSample]
```

1. Dataset에 다양한 원천 데이터가 수집/저장됨
2. KpiMetric이 Dataset의 특정 필드/코드를 참조하여 Metric을 정의
3. Kpi는 여러 Metric을 조합한 formula로 KPI를 정의
4. KpiValue는 특정 시점/조직/조건에 대해 Dataset에서 Metric별 집계 → formula 계산 → KPI 실적값으로 저장
5. KpiHistory는 KPI의 버전별 정의/산식/구조 이력을 관리

## 5. 실제 활용 예시

### 5.1 불량률 KPI

- Metric: defect_count, total_count (각각 inspection_data Dataset의 필드)
- Formula: defect_count / total_count \* 100
- 특정 월/공장/라인별로 Dataset에서 집계 → KPI 실적값 생성

### 5.2 생산성 KPI

- Metric: produced_qty, working_hours (각각 생산 Dataset의 필드)
- Formula: produced_qty / working_hours

## 6. 확장성 및 유연성

- KPI 정의, 실적, 이력, 등급 등은 모두 Dataset의 데이터 구조와 밀접하게 연결됩니다.
- 확장성, 유연성, 이력관리, 자동/수동 입력 등 다양한 KPI 관리 요구를 충족합니다.

---

## 7. 참고 문서

- [design-entities.md](./design-entities.md): KPI 엔티티 상세 설계
- [Dataset 모듈 문서](../dataset/README.md): Dataset 구조 및 활용