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

package/README.md

@@ -0,0 +1,74 @@
+# KPI 모듈 개요
+
+## 1. KPI란?
+
+- KPI(Key Performance Indicator)는 조직의 목표 달성도를 수치로 측정/관리하는 핵심 지표입니다.
+- KPI는 산식(formula), 목표값(target), 카테고리(category), 버전(version), 상태(state) 등 다양한 속성을 가집니다.
+- KPI의 실적값(Performance Value)은 특정 시점/조직/프로젝트별로 기록됩니다.
+
+## 2. KPI 모듈의 주요 엔티티
+
+- **Kpi**: KPI 정의(이름, 산식, 카테고리, 상태, 버전 등)
+- **KpiValue**: KPI별 실적값(날짜, 값, 입력방식, 소스 등)
+- **KpiCategory**: 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 구조 및 활용

package/client/pages/kpi/kpi-list-page.ts

@@ -23,7 +23,6 @@ import { KpiImporter } from './kpi-importer'
 
 @customElement('kpi-list-page')
 export class KpiListPage extends connect(store)(localize(i18next)(ScopedElementsMixin(PageView))) {
-
   static styles = [
     ScrollbarStyles,
     CommonGristStyles,
@@ -34,8 +33,8 @@ export class KpiListPage extends connect(store)(localize(i18next)(ScopedElements
 
         width: 100%;
 
-        --grid-record-emphasized-background-color: #8B0000;
-        --grid-record-emphasized-color: #FF6B6B;
+        --grid-record-emphasized-background-color: #8b0000;
+        --grid-record-emphasized-color: #ff6b6b;
       }
 
       ox-grist {
@@ -101,11 +100,7 @@ export class KpiListPage extends connect(store)(localize(i18next)(ScopedElements
     const mode = this.mode || (isMobileDevice() ? 'CARD' : 'GRID')
 
     return html`
-      <ox-grist
-        .mode=${mode}
-        .config=${this.gristConfig}
-        .fetchHandler=${this.fetchHandler.bind(this)}
-      >
+      <ox-grist .mode=${mode} .config=${this.gristConfig} .fetchHandler=${this.fetchHandler.bind(this)}>
         <div slot="headroom" class="header">
           <div class="filters">
             <ox-filters-form autofocus without-search></ox-filters-form>
@@ -121,7 +116,6 @@ export class KpiListPage extends connect(store)(localize(i18next)(ScopedElements
                 <md-icon>add</md-icon>
               </button>
             </ox-record-creator>
-
           </div>
         </div>
       </ox-grist>
@@ -131,8 +125,42 @@ export class KpiListPage extends connect(store)(localize(i18next)(ScopedElements
   async pageInitialized(lifecycle: any) {
     this.gristConfig = {
       list: {
-        fields: ['name', 'description'],
-        details: ['active', 'updatedAt']
+        fields: [
+          'name',
+          'description',
+          'category',
+          'formula',
+          'active',
+          'state',
+          'vizType',
+          'schedule',
+          'scheduleId',
+          'timezone',
+          'version',
+          'createdAt',
+          'updatedAt',
+          'creator',
+          'updater',
+          'thumbnail'
+        ],
+        details: [
+          'name',
+          'description',
+          'category',
+          'formula',
+          'active',
+          'state',
+          'vizType',
+          'schedule',
+          'scheduleId',
+          'timezone',
+          'version',
+          'createdAt',
+          'updatedAt',
+          'creator',
+          'updater',
+          'thumbnail'
+        ]
       },
       columns: [
         { type: 'gutter', gutterName: 'sequence' },
@@ -140,56 +168,83 @@ export class KpiListPage extends connect(store)(localize(i18next)(ScopedElements
         {
           type: 'string',
           name: 'name',
-          header: i18next.t('field.name'),
-          record: {
-            editable: true
-          },
+          header: '이름',
+          record: { editable: true },
           filter: 'search',
           sortable: true,
-          width: 150
+          width: 120
         },
         {
           type: 'string',
           name: 'description',
           header: i18next.t('field.description'),
+          record: { editable: true },
+          filter: 'search',
+          width: 200
+        },
+        // {
+        //   type: 'string',
+        //   name: 'category',
+        //   header: '카테고리',
+        //   record: { editable: false, renderer: (v, c, r) => r.category?.name },
+        //   width: 120
+        // },
+        {
+          type: 'resource-object',
+          name: 'category',
+          label: true,
+          header: '카테고리',
           record: {
-            editable: true
+            editable: true,
+            options: {
+              title: i18next.t('title.lookup category'),
+              queryName: 'kpiCategories'
+            }
           },
-          filter: 'search',
           width: 200
         },
+        { type: 'string', name: 'formula', header: '산식', record: { editable: true }, width: 200 },
         {
           type: 'checkbox',
           name: 'active',
           label: true,
           header: i18next.t('field.active'),
-          record: {
-            editable: true
-          },
+          record: { editable: true },
           filter: true,
           sortable: true,
           width: 60
         },
+        { type: 'string', name: 'state', header: '상태', record: { editable: false }, width: 100 },
+        { type: 'string', name: 'vizType', header: '시각화유형', record: { editable: true }, width: 120 },
+        { type: 'string', name: 'schedule', header: '스케줄', record: { editable: true }, width: 120 },
+        { type: 'string', name: 'scheduleId', header: '스케줄ID', record: { editable: false }, width: 120 },
+        { type: 'string', name: 'timezone', header: '타임존', record: { editable: true }, width: 100 },
+        { type: 'number', name: 'version', header: '버전', record: { editable: false }, width: 80 },
+        { type: 'datetime', name: 'createdAt', header: '생성일', record: { editable: false }, width: 180 },
+        {
+          type: 'datetime',
+          name: 'updatedAt',
+          header: i18next.t('field.updated_at'),
+          record: { editable: false },
+          sortable: true,
+          width: 180
+        },
+        {
+          type: 'resource-object',
+          name: 'creator',
+          header: '생성자',
+          record: { editable: false, renderer: (v, c, r) => r.creator?.name },
+          width: 120
+        },
         {
           type: 'resource-object',
           name: 'updater',
           header: i18next.t('field.updater'),
-          record: {
-            editable: false
-          },
+          record: { editable: false, renderer: (v, c, r) => r.updater?.name },
           sortable: true,
           width: 120
         },
-        {
-          type: 'datetime',
-          name: 'updatedAt',
-          header: i18next.t('field.updated_at'),
-          record: {
-            editable: false
-          },
-          sortable: true,
-          width: 180
-        }
+        { type: 'string', name: 'thumbnail', header: '썸네일', record: { editable: false }, width: 120 }
       ],
       rows: {
         appendable: false,
@@ -197,11 +252,7 @@ export class KpiListPage extends connect(store)(localize(i18next)(ScopedElements
           multiple: true
         }
       },
-      sorters: [
-        {
-          name: 'name'
-        }
-      ]
+      sorters: [{ name: 'name' }]
     }
   }
 
@@ -221,6 +272,11 @@ export class KpiListPage extends connect(store)(localize(i18next)(ScopedElements
               name
               description
               active
+              category {
+                id
+                name
+                description
+              }
               updater {
                 id
                 name
@@ -355,12 +411,7 @@ export class KpiListPage extends connect(store)(localize(i18next)(ScopedElements
 
   async exportHandler() {
     const exportTargets = this.grist.selected.length ? this.grist.selected : this.grist.dirtyData.records
-    const targetFieldSet = new Set([
-      'id',
-      'name',
-      'description',
-      'active'
-    ])
+    const targetFieldSet = new Set(['id', 'name', 'description', 'active'])
 
     return exportTargets.map(kpi => {
       let tempObj = {}
@@ -389,10 +440,9 @@ export class KpiListPage extends connect(store)(localize(i18next)(ScopedElements
         title: i18next.t('title.import kpi')
       }
     )
-    
+
     popup.onclosed = () => {
       this.grist.fetch()
     }
   }
 }
-

package/client/pages/kpi/kpi-overview-sample.ts

@@ -0,0 +1,260 @@
+import { html, css, LitElement } from 'lit'
+import { customElement, state } from 'lit/decorators.js'
+import { marked } from 'marked'
+
+import { PageView, store } from '@operato/shell'
+import { i18next, localize } from '@operato/i18n'
+
+@customElement('kpi-overview')
+export class KpiOverview extends PageView {
+  static styles = css`
+    .overview-container {
+      display: flex;
+      gap: 32px;
+      background: #f7f5fa;
+      border-radius: 20px;
+      padding: 32px;
+      margin-bottom: 24px;
+      align-items: stretch;
+    }
+    .overview-left {
+      flex: 1;
+      display: flex;
+      flex-direction: column;
+      justify-content: center;
+    }
+    .overview-title {
+      font-size: 2.8rem;
+      font-weight: bold;
+      margin-bottom: 24px;
+    }
+    .overview-desc {
+      font-size: 1.2rem;
+      color: #222;
+      line-height: 1.6;
+    }
+    .overview-right {
+      flex: 1;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+    }
+    .overview-img {
+      width: 100%;
+      max-width: 420px;
+      border-radius: 12px;
+      object-fit: cover;
+      box-shadow: 0 4px 16px rgba(0, 0, 0, 0.08);
+    }
+    .group-tabs {
+      display: flex;
+      gap: 8px;
+      margin: 0 0 16px 0;
+      justify-content: center;
+    }
+    .group-tab {
+      padding: 10px 28px;
+      border-radius: 16px 16px 0 0;
+      background: #eee;
+      cursor: pointer;
+      font-size: 1.1rem;
+      font-weight: 500;
+      border: none;
+      outline: none;
+      transition: background 0.2s;
+    }
+    .group-tab[selected] {
+      background: #d6d6f7;
+      color: #222;
+      font-weight: bold;
+    }
+    .kpi-list {
+      display: flex;
+      gap: 8px;
+      margin: 0 0 32px 0;
+      justify-content: center;
+    }
+    .kpi-item {
+      padding: 8px 20px;
+      border-radius: 12px;
+      background: #f5f5f5;
+      cursor: pointer;
+      font-size: 1rem;
+      border: none;
+      outline: none;
+      transition: background 0.2s;
+    }
+    .kpi-item[selected] {
+      background: #bdf;
+      color: #222;
+      font-weight: bold;
+    }
+    .main-content {
+      display: flex;
+      gap: 32px;
+      margin-top: 32px;
+      align-items: flex-start;
+      justify-content: center;
+    }
+    .markdown {
+      background: #fff;
+      border-radius: 12px;
+      padding: 40px 32px;
+      min-height: 240px;
+      flex: 2;
+      font-size: 2rem;
+      color: #222;
+      box-shadow: 0 2px 8px rgba(0, 0, 0, 0.04);
+    }
+    .toc {
+      flex: 1;
+      background: #faf9fd;
+      border-radius: 12px;
+      padding: 32px 24px;
+      font-size: 1.1rem;
+      color: #444;
+      min-width: 220px;
+      box-shadow: 0 2px 8px rgba(0, 0, 0, 0.03);
+    }
+    .toc-title {
+      font-weight: bold;
+      margin-bottom: 12px;
+      font-size: 1.2rem;
+    }
+    .toc-list {
+      margin: 0 0 16px 0;
+      padding: 0;
+      list-style: none;
+    }
+    .toc-list li {
+      margin-bottom: 6px;
+    }
+    .toc-btn {
+      display: block;
+      margin: 12px 0;
+      padding: 8px 16px;
+      border: 1px solid #aaa;
+      border-radius: 8px;
+      background: #fff;
+      color: #333;
+      cursor: pointer;
+      font-size: 1rem;
+      text-align: left;
+      transition: background 0.2s;
+    }
+    .toc-btn:hover {
+      background: #f0f0f0;
+    }
+  `
+
+  get context() {
+    return {
+      title: i18next.t('title.kpi overview')
+    }
+  }
+
+  @state() selectedGroup = 0
+  @state() selectedKpi = 0
+
+  kpiGroups = [
+    {
+      name: '일정성과 지표',
+      kpis: ['연면적 대비 공사기간', '설계변경에 따른 공기 증감률', '일정 이탈 수준', '일정성과 수준 평가']
+    },
+    {
+      name: '비용성과 지표',
+      kpis: ['연면적 대비 공사비', '설계변경에 따른 공사비 증감률', '비용성과 수준 평가']
+    },
+    {
+      name: '품질성과 지표',
+      kpis: ['품질시험 불합격률', '검수재 불합격률', '검측 불합격률', '품질 SL-PA 결과값', '품질성과 수준 평가']
+    },
+    {
+      name: '안전성과 지표',
+      kpis: ['재해율', '재해강도율', '안전 SL-PA 결과값', '안전성과 수준 평가']
+    },
+    {
+      name: '환경성과 지표',
+      kpis: ['건설폐기물 발생량', '환경성과 수준 평가']
+    },
+    {
+      name: '생산성과 지표',
+      kpis: ['투입인력 생산성', '생산성과 수준 평가']
+    }
+  ]
+
+  kpiDescriptions = {
+    '연면적 대비 공사기간': `# 연면적 대비 공사기간\n- 설명: 프로젝트의 전체 연면적 대비 실제 소요된 공사기간을 측정합니다.\n- 산식: 실제공사기간(개월) / (연면적/1000m2)\n- 데이터 표준형: 실제공사기간(개월) / (연면적/1000m2)\n- 활용: 대형 프로젝트의 일정 효율성 파악`,
+    '설계변경에 따른 공기 증감률': `# 설계변경에 따른 공기 증감률\n- 설명: 설계변경으로 인한 공기 단축 또는 증가 효과를 측정합니다.\n- 산식: (실제공사기간 - 계획공사기간) / 계획공사기간(개월)\n- 데이터 표준형: (실제공사기간 - 계획공사기간)(개월) / 계획공사기간(개월)`,
+    '일정 이탈 수준': `# 일정 이탈 수준\n- 설명: 계획 대비 실제 일정의 이탈 정도를 평가합니다.\n- 산식: Table(DART 등) 활용\n- 평가 방식: 1~5점 척도(감리자 평가)`,
+    '일정성과 수준 평가': `# 일정성과 수준 평가\n- 설명: 일정성과의 전반적인 수준을 감리자가 평가합니다.\n- 평가 방식: 감리자 1~5점 척도`,
+    '연면적 대비 공사비': `# 연면적 대비 공사비\n- 설명: 프로젝트의 전체 연면적 대비 실제 소요된 공사비를 측정합니다.\n- 산식: 실제공사비(억원) / (연면적/1000m2)\n- 데이터 표준형: 실제공사비(억원) / (연면적/1000m2)`,
+    '설계변경에 따른 공사비 증감률': `# 설계변경에 따른 공사비 증감률\n- 설명: 설계변경으로 인한 공사비 증감률을 측정합니다.\n- 산식: (실제공사비 - 계획공사비) / 계획공사비(억원)\n- 데이터 표준형: (실제공사비 - 계획공사비)(억원) / 계획공사비(억원)`,
+    '비용성과 수준 평가': `# 비용성과 수준 평가\n- 설명: 비용성과의 전반적인 수준을 감리자가 평가합니다.\n- 평가 방식: 감리자 1~5점 척도`,
+    '품질시험 불합격률': `# 품질시험 불합격률\n- 설명: 전체 품질시험 중 불합격 건수의 비율을 측정합니다.\n- 산식: 품질시험 불합격 건수(건) / (연면적/1000m2)`,
+    '검수재 불합격률': `# 검수재 불합격률\n- 설명: 검수재 중 불합격 건수의 비율을 측정합니다.\n- 산식: 검수재 불합격 건수(건) / (연면적/1000m2)`,
+    '검측 불합격률': `# 검측 불합격률\n- 설명: 전체 검측 중 불합격 건수의 비율을 측정합니다.\n- 산식: 품질검측 불합격 건수(건) / 품질검측 건수(건)`,
+    '품질 SL-PA 결과값': `# 품질 SL-PA 결과값\n- 설명: SL-PA(Safety Level - Performance Assessment)는 건설/안전 분야에서 안전관리 수준을 정량적으로 평가하는 대표 지표입니다.\n- 평가 방식: Python 활용 1~5점 척도`,
+    '품질성과 수준 평가': `# 품질성과 수준 평가\n- 설명: 품질성과의 전반적인 수준을 감리자가 평가합니다.\n- 평가 방식: 감리자 1~5점 척도`,
+    재해율: `# 재해율\n- 설명: 연간 근로자 수 대비 재해 발생 건수의 비율을 측정합니다.\n- 산식: (재해 건수(건) / 연간 근로자 수(명)) * 100`,
+    재해강도율: `# 재해강도율\n- 설명: 총 근로자 수와 연간 근로시간 대비 노동손실일수의 비율을 측정합니다.\n- 산식: (노동손실일수(일) / (총 근로자 수 * 1인당 연간 근로시간)) * 100`,
+    '안전 SL-PA 결과값': `# 안전 SL-PA 결과값\n- 설명: SL-PA(Safety Level - Performance Assessment)는 건설/안전 분야에서 **안전관리 수준**을 정량적으로 평가하는 대표 지표입니다.\n- 활용: 현장의 안전성과를 수치로 진단하고, 위험요소 개선 및 안전관리 정책 수립에 활용됩니다.\n- 평가 방식: Python 활용 1~5점 척도 (1점: 매우 미흡, 5점: 매우 우수)`,
+    '안전성과 수준 평가': `# 안전성과 수준 평가\n- 설명: 안전성과의 전반적인 수준을 감리자가 평가합니다.\n- 평가 방식: 감리자 1~5점 척도`,
+    '건설폐기물 발생량': `# 건설폐기물 발생량\n- 설명: 전체 건설폐기물 발생량을 측정합니다.\n- 산식: 총 건설 폐기물 발생량(ton) / (연면적/1000m2)`,
+    '환경성과 수준 평가': `# 환경성과 수준 평가\n- 설명: 환경성과의 전반적인 수준을 감리자가 평가합니다.\n- 평가 방식: 감리자 1~5점 척도`,
+    '투입인력 생산성': `# 투입인력 생산성\n- 설명: 투입 인력 대비 생산성을 측정합니다.\n- 산식: 투입인력(명) / (연면적/1000m2)`,
+    '생산성과 수준 평가': `# 생산성과 수준 평가\n- 설명: 생산성과의 전반적인 수준을 감리자가 평가합니다.\n- 평가 방식: 감리자 1~5점 척도`
+  }
+
+  render() {
+    const group = this.kpiGroups[this.selectedGroup]
+    const kpi = group.kpis[this.selectedKpi]
+    const md = this.kpiDescriptions[kpi] || '각 지표의 주요 소개 내용을 마크다운으로 입력하세요.'
+
+    return html`
+      <div class="overview-container">
+        <div class="overview-left">
+          <div class="overview-title">KPI개요</div>
+          <div class="overview-desc">
+            건설현장 KPI 관리 시스템은 프로젝트 성과를 측정하고 모니터링하여 효율적인 공정 관리를 지원합니다.<br />
+            주요 지표를 통해 현장 생산성, 품질, 안전 등을 실시간으로 파악할 수 있습니다.
+          </div>
+        </div>
+        <div class="overview-right">
+          <img
+            class="overview-img"
+            src="https://images.unsplash.com/photo-1464983953574-0892a716854b?auto=format&fit=crop&w=600&q=80"
+            alt="건설현장 안전"
+          />
+        </div>
+      </div>
+      <div class="group-tabs">
+        ${this.kpiGroups.map(
+          (g, i) => html`
+            <button
+              class="group-tab"
+              ?selected=${i === this.selectedGroup}
+              @click=${() => {
+                this.selectedGroup = i
+                this.selectedKpi = 0
+              }}
+            >
+              ${g.name}
+            </button>
+          `
+        )}
+      </div>
+      <div class="main-content">
+        <div class="markdown" .innerHTML=${marked(md)}></div>
+        <div class="toc">
+          <div class="toc-title">목차</div>
+          <ul class="toc-list">
+            ${group.kpis.map(
+              (k, i) => html` <li><button class="toc-btn" @click=${() => (this.selectedKpi = i)}>${k}</button></li> `
+            )}
+          </ul>
+        </div>
+      </div>
+    `
+  }
+}