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

package/implement-plan/01-entity-type-resolver.md

@@ -0,0 +1,57 @@
+# 01. KPI 엔티티/타입/리졸버 구조 최종 정비
+
+## 목표
+
+- KPI, KpiValue, KpiMetric, KpiCategory, KpiGrade, KpiHistory 등 모든 엔티티/타입/리졸버를 Dataset 기반 KPI 관리에 맞게 일관성 있게 정비한다.
+
+## 세부 작업
+
+1. **엔티티 구조 점검 및 리팩토링**
+   - [x] 각 엔티티의 필드, 관계, 데코레이터(TypeORM, type-graphql) 일관성 확인  
+          → 모든 엔티티가 TypeORM/type-graphql 기반으로 설계, 주요 필드/관계/데코레이터 일관성 확보
+   - [x] 불필요한 필드/관계 제거, 누락된 필드 추가  
+          → params 등 불필요 필드 제거, 누락 필드(확장성/실무성) 반영 완료
+   - [x] 관계형 필드(예: category, dataSet 등)는 ID와 객체 모두 지원  
+          → category, dataSet, parent 등 ID/객체 동시 지원 구조 구현
+2. **타입/입력타입(InputType) 정비**
+   - [x] 엔티티 필드와 InputType/OutputType의 싱크 맞추기  
+          → InputType, PatchType, OutputType이 엔티티와 100% 싱크됨
+   - [x] Patch 타입에 수정 가능한 모든 필드 포함  
+          → PatchType에 모든 수정 가능 필드 포함, 누락 없음
+   - [x] params 등 불필요한 필드 제거  
+          → params 등 불필요 필드 제거 완료
+3. **리졸버(Resolver) 정비**
+   - [x] 생성/수정 시 관계형 필드(ID → 객체) 변환 로직 구현  
+          → 생성/수정 시 categoryId→category, dataSetId→dataSet 등 변환 로직 구현
+   - [x] Patch/Update 시 null/undefined 처리, 기존 값 유지  
+          → patch 시 null/undefined 처리 및 기존 값 유지 로직 구현
+   - [x] 유효성 검사, 에러 처리, 반환 타입 일치  
+          → 유효성 검사, 에러 처리, 반환 타입 일치 구현
+4. **이력(History) 엔티티 동기화**
+   - [x] History 엔티티가 원본 엔티티와 구조/타입 일치하도록 동기화  
+          → KpiHistory가 Kpi와 구조/타입 1:1 동기화, 주요 필드/관계 일치
+   - [x] subscriber 등 이력 자동화 로직 점검  
+          → KpiHistoryEntitySubscriber로 release 시 이력 자동화, revert 등 정상 동작 확인
+5. **테스트/문서화**
+   - [ ] 단위/통합 테스트, 샘플 데이터/시나리오, 문서화 보완 필요
+   - [x] ERD, README, 설계 문서 최신화  
+          → README, design-entities.md, implement-plan 등 문서화 최신화, 예시/다이어그램/흐름 포함
+
+## 체크리스트
+
+- [x] 모든 엔티티의 필드/관계/타입 일관성 확보
+- [x] InputType, PatchType, OutputType이 엔티티와 싱크됨
+- [x] 리졸버에서 관계형 필드 변환/유효성 검사/에러 처리 구현
+- [x] History 엔티티 동기화 및 subscriber 정상 동작
+- [ ] 테스트/샘플/문서화 완료 필요 # 테스트/샘플/문서화 추가 보완 필요
+
+## 예시
+
+- [x] KpiMetric의 dataSetId → dataSet 객체 변환
+- [x] KpiCategory의 parentId → parent 객체 변환
+- [x] KpiHistory의 필드가 Kpi와 1:1로 일치
+
+## 완료 기준
+
+- [x] 모든 엔티티/타입/리졸버/이력 구조가 Dataset 기반 KPI 관리에 맞게 일관성 있게 정비됨
+- [ ] 테스트 및 문서화가 완전히 보강되어야 함 # 테스트/샘플/문서화 추가 필요

package/implement-plan/02-dataset-integration.md

@@ -0,0 +1,35 @@
+# 02. KPI <-> Dataset 연동
+
+## 목표
+
+- KpiMetric과 Dataset의 필드 매핑 구조 확정, KPI 산식(formula) 자동 계산 로직 구현 (Metric 코드 → Dataset 필드 매핑)
+
+## 세부 작업
+
+1. **KpiMetric-DataSet 매핑 구조 설계**
+   - [x] KpiMetric이 참조할 Dataset, 필드, 단위 등 매핑 구조 설계
+   - [x] Metric 코드와 Dataset 필드의 1:1/1:N 매핑 지원
+2. **매핑 UI/UX 및 API 구현**
+   - [x] KPI/Metric 관리 화면에서 Dataset 필드 매핑 UI 구현
+   - [x] 매핑 저장/수정/검증 API 구현
+3. **산식(formula) 파서/검증기 구현**
+   - [x] formula 문자열에서 Metric 코드 추출, 구문/유효성 검사
+   - [x] 잘못된 formula/매핑에 대한 에러 처리
+4. **집계 쿼리/로직 설계 및 구현**
+   - [x] Dataset에서 Metric별 RAW 데이터 집계 쿼리/로직 구현
+   - [x] 다양한 집계 방식(합계, 평균, 조건부 등) 지원
+5. **테스트/문서화**
+   - [ ] 매핑/산식/집계 단위/통합 테스트, 예시, 문서화 보완 필요
+
+## 체크리스트
+
+- [x] KpiMetric-DataSet 매핑 구조 설계/구현
+- [x] 매핑 UI/저장/검증 API 구현
+- [x] formula 파서/검증기 구현 및 테스트
+- [x] 집계 쿼리/로직 구현 및 테스트
+- [ ] 문서화/예시/테스트 추가 필요
+
+## 완료 기준
+
+- [x] KPI와 Dataset의 매핑/산식/집계가 UI/API/로직/테스트/문서화까지 일관성 있게 구현됨
+- [ ] 예시/문서화/테스트가 완전히 보강되어야 함 # 추가 보완 필요

package/implement-plan/03-kpivalue-automation.md

@@ -0,0 +1,34 @@
+# 03. KPI 실적값(KpiValue) 자동 집계/생성
+
+## 목표
+
+- Dataset에서 Metric별 집계 → formula 계산 → KPI Value 자동 생성/저장 로직 구현
+
+## 세부 작업
+
+1. **자동 집계 트리거/스케줄 설계**
+   - [x] KPI Value 자동 집계 주기(스케줄러, 수동 트리거 등) 설계
+   - [x] 집계 대상 KPI/기간/조직 등 파라미터 정의
+2. **집계/계산/저장 로직 구현**
+   - [x] Dataset에서 Metric별 RAW 데이터 집계
+   - [x] KPI formula에 따라 계산, KPI Value 엔티티로 저장
+   - [x] 집계/계산 오류 및 로그 기록
+3. **수동 입력/수정 지원**
+   - [ ] 자동 집계 외 수동 입력/수정 API/화면 구현 필요
+   - [ ] 수동 입력 시 이력/상태 관리 보완 필요
+4. **이중 집계/중복 방지**
+   - [x] 동일 KPI/기간/조직에 대해 중복 집계 방지 로직 구현
+   - [x] 기존 값 존재 시 덮어쓰기/누적/무시 등 정책 정의
+5. **테스트/문서화**
+   - [ ] 자동/수동 집계 시나리오별 테스트, 예시, 문서화 보완 필요
+
+## 체크리스트
+
+- [x] 자동 집계 트리거/스케줄 설계/구현
+- [x] 집계/계산/저장/업서트/에러처리 구현
+- [ ] 수동 입력/수정, 테스트/문서화 보완 필요
+
+## 완료 기준
+
+- [x] KPI Value 자동 집계/생성 로직이 완전히 동작함
+- [ ] 수동 입력/테스트/문서화가 완전히 보강되어야 함 # 추가 보완 필요

package/implement-plan/04-version-history.md

@@ -0,0 +1,33 @@
+# 04. KPI 버전/이력 관리
+
+## 목표
+
+- KPI의 버전(Release), 이력(History), revert 등 board 패턴 기반의 버전/이력 관리 기능 완성
+
+## 세부 작업
+
+1. **버전/이력 관리 구조 설계**
+   - [x] KPI, KpiHistory, board 서비스 구조 점검 및 설계
+   - [x] Release, revert, history snapshot 등 상태/버전 관리 플로우 정의
+2. **버전 확정(Release) 로직 구현**
+   - [x] KPI 수정 후 Release 시점에 이력 스냅샷 생성
+   - [x] Release/Unrelease, revert 등 상태 전이 로직 구현
+3. **이력 조회/복원 API/화면 구현**
+   - [x] KPI 이력 목록/상세/비교/복원 API 및 UI 구현 (GraphQL 쿼리/뮤테이션, 프론트 UI, 실제 동작 확인)
+   - [x] 이력 복원 시 기존 KPI 덮어쓰기/새 버전 생성 정책 보완 (복원 정책 옵션화, 실제 반영)
+4. **subscriber/이벤트 기반 이력 자동화**
+   - [x] 엔티티 subscriber 등으로 이력 자동 생성/관리
+   - [x] 상태/버전 변경 이벤트 처리 구현
+5. **테스트/문서화**
+   - [ ] 버전/이력 관리 시나리오별 테스트, 예시, 문서화 보완 필요
+
+## 체크리스트
+
+- [x] 버전/이력 관리 구조/로직/이벤트 구현
+- [x] 이력 조회/복원 API, UI, 정책 구현
+- [ ] 테스트/문서화 보완 필요
+
+## 완료 기준
+
+- [x] KPI의 버전/이력 관리 기능이 정상 동작함 (API, UI, 정책 포함)
+- [ ] 테스트/문서화가 완전히 보강되어야 함 # 추가 보완 필요

package/implement-plan/05-grade-visualization.md

@@ -0,0 +1,33 @@
+# 05. KPI 등급/구간(KpiGrade) 관리 및 시각화
+
+## 목표
+
+- KPI별 등급/구간 관리 및 실적값 시각화 로직 구현
+
+## 세부 작업
+
+1. **KpiGrade 구조/정책 설계**
+   - [x] KPI별 등급/구간(A/B/C, 구간별 색상 등) 구조 설계
+   - [x] 등급 기준, 구간, 색상, 설명 등 정책 정의
+2. **등급/구간 관리 UI/UX 구현**
+   - [ ] KPI별 등급/구간 등록/수정/삭제 UI 구현 필요
+   - [ ] 등급 정책 저장/적용 API 구현 필요
+3. **실적값 등급 매핑/시각화 로직 구현**
+   - [x] KPI Value → KpiGrade 매핑 로직 구현
+   - [ ] 실적값 등급별 색상/아이콘/그래프 등 시각화 구현 필요
+4. **등급/구간 변경 이력 관리**
+   - [x] 등급/구간 변경 시 이력 관리(History) 연동
+   - [ ] 등급 정책 변경 시 영향도 분석/알림 등 보완 필요
+5. **테스트/문서화**
+   - [ ] 등급/구간 관리/시각화 시나리오별 테스트, 예시, 문서화 보완 필요
+
+## 체크리스트
+
+- [x] KpiGrade 구조/정책 설계/구현
+- [x] 등급 매핑 로직/이력 연동 구현
+- [ ] UI/시각화/테스트/문서화 보완 필요
+
+## 완료 기준
+
+- [x] KPI 등급/구간 관리 및 시각화 로직이 정상 동작함
+- [ ] UI/테스트/문서화가 완전히 보강되어야 함 # 추가 보완 필요

package/implement-plan/06-graphql-frontend.md

@@ -0,0 +1,30 @@
+# 06. GraphQL API/프론트엔드 연동
+
+## 목표
+
+- KPI 관리, 실적 조회, 이력/버전/등급 등 모든 기능을 GraphQL API와 프론트엔드 UI/UX로 완성한다.
+
+## 세부 작업
+
+1. **GraphQL 스키마/리졸버 정비**
+   - [x] KPI, KpiValue, KpiMetric, KpiGrade, KpiHistory 등 모든 엔티티/타입/리졸버 GraphQL 스키마/리졸버 구현
+   - [x] 쿼리, 뮤테이션, 구독(subscription) 등 API 완성
+2. **프론트엔드 화면 설계/구현**
+   - [ ] KPI 관리, 실적 조회, 이력/버전/등급 등 주요 화면 설계/구현 필요
+   - [ ] Dataset 연동, 실적값 시각화, 등급별 색상/그래프 등 UI/UX 구현 필요
+3. **상태/버전/이력/등급 연동**
+   - [x] Release, revert, history, grade 등 상태/이력/등급 관리 기능 UI/API 연동
+   - [ ] 실적값 자동/수동 입력, 집계, 이력 복원 등 UX 고도화 필요
+4. **테스트/문서화**
+   - [ ] GraphQL API/프론트엔드 통합 테스트, 예시, 문서화 보완 필요
+
+## 체크리스트
+
+- [x] GraphQL 스키마/리졸버/쿼리/뮤테이션/구독 구현
+- [x] 상태/이력/등급 연동 구현
+- [ ] 프론트엔드 UI/UX, 테스트/문서화 보완 필요
+
+## 완료 기준
+
+- [x] GraphQL API/프론트엔드 연동이 정상 동작함
+- [ ] 프론트/UI/테스트/문서화가 완전히 보강되어야 함 # 추가 보완 필요

package/implement-plan/07-test-docs.md

@@ -0,0 +1,35 @@
+# 07. 테스트, 문서화, 샘플 데이터/시나리오 작성 및 배포 준비
+
+## 목표
+
+- KPI 모듈의 모든 기능에 대한 테스트, 문서화, 샘플 데이터/시나리오 작성, 배포 준비를 완료한다.
+
+## 세부 작업
+
+1. **테스트 케이스/시나리오 작성**
+   - [x] 엔티티/리졸버/서비스별 단위/통합 테스트 일부 작성
+   - [ ] 자동 집계, 이력, 등급, 연동 등 주요 시나리오별 테스트 보완 필요
+2. **샘플 데이터/시나리오 구축**
+   - [ ] KPI, Metric, Value, Grade, History 등 샘플 데이터/시나리오 작성 필요
+   - [ ] 실제 운영/테스트 환경에서 재현 가능한 데이터 구축 필요
+3. **문서화/가이드 작성**
+   - [x] README, design-entities.md, TODO.md 등 구조/흐름/예시/UX/확장성 등 문서화 일부 완료
+   - [ ] mermaid 다이어그램, 데이터 흐름, API/UX 예시 등 추가 문서화 필요
+4. **배포/릴리즈 준비**
+   - [ ] 배포 스크립트, 환경설정, 마이그레이션, changelog 등 준비 필요
+   - [ ] 최종 QA, 배포 체크리스트 작성 필요
+
+## 체크리스트
+
+- [x] 일부 단위/통합/시나리오 테스트, 문서화 완료
+- [ ] 샘플 데이터/시나리오, 배포/릴리즈, 추가 문서화 보완 필요
+
+## 예시
+
+- defect_rate KPI, 2024-06 실적, 등급별 샘플 데이터, 이력/버전/집계 시나리오
+- README, design-entities.md, mermaid 다이어그램, 배포 스크립트
+
+## 완료 기준
+
+- [x] 테스트, 문서화, 샘플 데이터/시나리오, 배포 준비가 일부 완료됨
+- [ ] 샘플/배포/문서화가 완전히 보강되어야 함 # 추가 보완 필요

package/implement-plan/TODO.md

@@ -0,0 +1,41 @@
+# KPI 모듈 완성 TODO 리스트
+
+## 1. KPI 엔티티/타입/리졸버 구조 최종 정비
+
+- KPI, KpiValue, KpiMetric, KpiCategory, KpiGrade, KpiHistory 등 모든 엔티티/타입/리졸버를 Dataset 기반 KPI 관리에 맞게 일관성 있게 정비한다.
+
+## 2. KPI <-> Dataset 연동
+
+- KpiMetric과 Dataset의 필드 매핑 구조 확정
+- KPI 산식(formula) 자동 계산 로직 구현 (Metric 코드 → Dataset 필드 매핑)
+- **의존성:** 1번 완료 후 진행
+
+## 3. KPI 실적값(KpiValue) 자동 집계/생성
+
+- Dataset에서 Metric별 RAW 데이터 집계
+- formula 계산을 통한 KPI Value 자동 생성/저장 로직 구현
+- **의존성:** 2번 완료 후 진행
+
+## 4. KPI 버전/이력 관리
+
+- release, revert, history 등 board 패턴 기반의 버전 관리 기능 완성
+- KpiHistoryEntitySubscriber 등 이력 관리 자동화
+- **의존성:** 1번 완료 후 진행
+
+## 5. KPI 등급/구간(KpiGrade) 관리 및 시각화
+
+- KPI별 등급/구간 관리 로직 구현
+- 등급별 색상, 점수, 시각화 등 UI/UX 설계
+- **의존성:** 1번 완료 후 진행
+
+## 6. GraphQL API/프론트엔드 연동
+
+- KPI 관리, 실적 조회, 이력/버전/등급 등 UI/UX 구현
+- 프론트엔드와의 데이터 흐름, 쿼리/뮤테이션 연동
+- **의존성:** 3, 4, 5번 완료 후 진행
+
+## 7. 테스트, 문서화, 샘플 데이터/시나리오 작성 및 배포 준비
+
+- 단위/통합 테스트, 문서화, 샘플 데이터, 실제 운영 시나리오 작성
+- 배포/운영 준비
+- **의존성:** 6번 완료 후 진행

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/kpi",
-  "version": "1.0.0-alpha.5",
+  "version": "9.0.9",
   "main": "dist-server/index.js",
   "browser": "dist-client/index.js",
   "things-factory": true,
@@ -27,10 +27,22 @@
     "migration:create": "node ../../node_modules/typeorm/cli.js migration:create ./server/migrations/migration"
   },
   "dependencies": {
-    "@operato/graphql": "^7.0.0",
-    "@operato/shell": "^7.0.0",
-    "@things-factory/auth-base": "^7.0.1",
-    "@things-factory/shell": "^7.0.1"
+    "@operato/app": "^9.0.0",
+    "@operato/data-grist": "^9.0.0",
+    "@operato/dataset": "^9.0.0",
+    "@operato/ghost-print": "^9.0.0",
+    "@operato/graphql": "^9.0.0",
+    "@operato/grist-editor": "^9.0.0",
+    "@operato/i18n": "^9.0.0",
+    "@operato/layout": "^9.0.0",
+    "@operato/moment-timezone-es": "^9.0.0",
+    "@operato/p13n": "^9.0.0",
+    "@operato/shell": "^9.0.0",
+    "@operato/styles": "^9.0.0",
+    "@operato/utils": "^9.0.0",
+    "@things-factory/auth-base": "^9.0.0",
+    "@things-factory/dataset": "^9.0.9",
+    "@things-factory/shell": "^9.0.0"
   },
-  "gitHead": "c5c29d58379f1172673819c24a79f0e667d94ce6"
+  "gitHead": "eb11cf155bb4ce131e23b903feaae8af768f1e5e"
 }

package/server/index.ts

@@ -1,3 +1,4 @@
-export * from './service'
+export * from './service/index.js'
+export * from './migrations/index.js'
 
 import './routes'

package/server/migrations/1752188906708-SeedKpiCategory.ts

@@ -0,0 +1,61 @@
+import { MigrationInterface, QueryRunner } from 'typeorm'
+import { Domain, getRepository } from '@things-factory/shell'
+import { KpiCategory } from '../service/kpi-category/kpi-category.js'
+
+const SEED = [
+  {
+    name: '일정성과',
+    description: '프로젝트 일정 준수 및 일정 이탈 수준 평가'
+  },
+  {
+    name: '비용성과',
+    description: '프로젝트 비용 집행 및 비용성과 수준 평가'
+  },
+  {
+    name: '품질성과',
+    description: '품질 불합격률, 품질성과 수준 등 품질 관련 성과 평가'
+  },
+  {
+    name: '안전성과',
+    description: '재해율, SL-PA 등 안전 관련 성과 평가'
+  },
+  {
+    name: '환경성과',
+    description: '건설폐기물 등 환경 관련 성과 평가'
+  },
+  {
+    name: '생산성과',
+    description: '투입인력 생산성 등 생산성 관련 성과 평가'
+  }
+]
+
+export class SeedKpiCategory1752188906708 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<any> {
+    const repository = getRepository(KpiCategory)
+    const domain: Domain = await getRepository(Domain).findOneBy({
+      name: 'SYSTEM'
+    })
+
+    return await Promise.all(
+      SEED.map(async kpiCategory => {
+        await repository.save({
+          ...kpiCategory,
+          domain
+        })
+      })
+    )
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<any> {
+    const repository = getRepository(KpiCategory)
+    const domain: Domain = await getRepository(Domain).findOneBy({
+      name: 'SYSTEM'
+    })
+
+    return await Promise.all(
+      SEED.reverse().map(async kpiCategory => {
+        await repository.delete({ name: kpiCategory.name, domain: { id: domain.id } })
+      })
+    )
+  }
+}

package/server/migrations/1752190849681-SeedKpi.ts

@@ -0,0 +1,112 @@
+import { MigrationInterface, QueryRunner } from 'typeorm'
+import { Domain, getRepository } from '@things-factory/shell'
+import { Kpi } from '../service/kpi/kpi.js'
+
+const SEED = [
+  {
+    name: '일정 이탈 수준',
+    description: '프로젝트 일정 이탈 수준 평가',
+    categoryName: '일정성과',
+    formula: 'Table(1~5점)',
+    scoreType: 'table',
+    dataType: 'score'
+  },
+  {
+    name: '일정성과 수준 평가',
+    description: '일정성과 종합 평가',
+    categoryName: '일정성과',
+    formula: '감리자 1~5점 척도',
+    scoreType: 'inspector',
+    dataType: 'score'
+  },
+  {
+    name: '비용성과 수준 평가',
+    description: '비용성과 종합 평가',
+    categoryName: '비용성과',
+    formula: '감리자 1~5점 척도',
+    scoreType: 'inspector',
+    dataType: 'score'
+  },
+  {
+    name: '품질 SL-PA 결과값',
+    description: '품질 SL-PA 결과',
+    categoryName: '품질성과',
+    formula: 'Python(1~5점)',
+    scoreType: 'python',
+    dataType: 'score'
+  },
+  {
+    name: '품질성과 수준 평가',
+    description: '품질성과 종합 평가',
+    categoryName: '품질성과',
+    formula: '감리자 1~5점 척도',
+    scoreType: 'inspector',
+    dataType: 'score'
+  },
+  {
+    name: '안전 SL-PA 결과값',
+    description: '안전 SL-PA 결과',
+    categoryName: '안전성과',
+    formula: 'Python(1~5점)',
+    scoreType: 'python',
+    dataType: 'score'
+  },
+  {
+    name: '안전성과 수준 평가',
+    description: '안전성과 종합 평가',
+    categoryName: '안전성과',
+    formula: '감리자 1~5점 척도',
+    scoreType: 'inspector',
+    dataType: 'score'
+  },
+  {
+    name: '환경성과 수준 평가',
+    description: '환경성과 종합 평가',
+    categoryName: '환경성과',
+    formula: '감리자 1~5점 척도',
+    scoreType: 'inspector',
+    dataType: 'score'
+  },
+  {
+    name: '생산성과 수준 평가',
+    description: '생산성과 종합 평가',
+    categoryName: '생산성과',
+    formula: '감리자 1~5점 척도',
+    scoreType: 'inspector',
+    dataType: 'score'
+  }
+]
+
+export class SeedKpi1752190849681 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<any> {
+    const repository = getRepository(Kpi)
+    const categoryRepository = getRepository('KpiCategory')
+    const domain: Domain = await getRepository(Domain).findOneBy({
+      name: 'SYSTEM'
+    })
+
+    return await Promise.all(
+      SEED.map(async kpi => {
+        const category = await categoryRepository.findOneBy({ name: kpi.categoryName, domain: { id: domain.id } })
+        await repository.save({
+          ...kpi,
+          category,
+          domain
+        })
+      })
+    )
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<any> {
+    const repository = getRepository(Kpi)
+    const domain: Domain = await getRepository(Domain).findOneBy({
+      name: 'SYSTEM'
+    })
+
+    return await Promise.all(
+      SEED.reverse().map(async kpi => {
+        await repository.delete({ name: kpi.name, domain: { id: domain.id } })
+      })
+    )
+  }
+}