# 비재무 KPI 기능 추가 전략

## 1. PDF 분석 요약

### Scale Cloud + freee 연동 프레젠테이션 (52페이지)
- **핵심 컨셉**: PLとKPIの一元管理 (PL과 KPI 통합 관리)
- **목표**: 予算の達成度とその再現性を高める (예산 달성도와 재현성 향상)

### KPI 구조 (KPIツリー)
```
KGI (売上) ─ 結果指標 (결과지표)
    │
    ├── 契約単価 (계약단가) × 契約数 (계약수)
    │       │
    │       ├── 成約率 (성약율) × 商談数 (상담수)
    │       │       │
    │       │       ├── 商談化率 (상담화율) × リード数 (리드수)
    │       │               │
    │       │               └── CVR × クリック数 / アポ率 × コール数
    │       │
    │       └── 継続率 × 既契約数
    │
    └── 先行指標 (선행지표) - KPI
```

### 핵심 인사이트
1. **PLとKPIの紐付け**: PL 항목과 KPI를 연결하여 구조화
2. **四則演算で繋げる**: 모든 KPI는 사칙연산으로 연결 (× + ÷ -)
3. **部門横断的管理**: 마케팅 → 인사이드세일즈 → 필드세일즈 → 코포레이트

---

## 2. 구현 전략

### Phase 1: 데이터 모델 확장

#### 새로운 데이터 구조
```python
@dataclass
class KPIItem:
    """비재무 KPI 항목"""
    id: str                      # kpi_001
    name: str                    # リード数
    category: str                # marketing / sales / hr / product
    unit: str                    # 件, %, 円, 人

    # 월별 데이터
    monthly_plan: List[float]    # 계획
    monthly_actual: List[float]  # 실적
    monthly_forecast: List[float] # 예측

    # 계산 관계
    formula: Optional[str]       # "contract_count * contract_price"
    parent_id: Optional[str]     # 상위 KPI ID
    children_ids: List[str]      # 하위 KPI IDs
    operator: str                # × + ÷ -

@dataclass
class KPITree:
    """KPI 트리 구조"""
    root_kgi: KPIItem            # 최상위 KGI (매출)
    kpis: Dict[str, KPIItem]     # 전체 KPI 맵

    def get_bottleneck(self) -> List[KPIItem]:
        """달성률 낮은 KPI 반환"""

    def forecast_kgi(self) -> float:
        """KPI 기반 KGI 예측"""
```

### Phase 2: Google Sheets 템플릿 확장

#### 새로운 시트 구조
| 시트명 | 용도 |
|--------|------|
| `PL` | 기존 손익계산서 (현재) |
| `KPI_Master` | KPI 정의 (ID, 이름, 카테고리, 단위, 수식) |
| `KPI_Plan` | KPI 계획 (월별) |
| `KPI_Actual` | KPI 실적 (월별) |
| `KPI_Tree` | 트리 구조 정의 (부모-자식 관계) |

#### KPI_Master 시트 예시
| ID | Name | Category | Unit | Formula | Parent |
|----|------|----------|------|---------|--------|
| kgi_sales | 売上高 | result | 円 | contract_count × contract_price | - |
| kpi_contract_count | 契約数 | sales | 件 | close_rate × meetings | kgi_sales |
| kpi_contract_price | 契約単価 | sales | 円 | - | kgi_sales |
| kpi_close_rate | 成約率 | sales | % | - | kpi_contract_count |
| kpi_meetings | 商談数 | sales | 件 | meeting_rate × leads | kpi_contract_count |
| kpi_meeting_rate | 商談化率 | marketing | % | - | kpi_meetings |
| kpi_leads | リード数 | marketing | 件 | cvr × clicks | kpi_meetings |
| kpi_cvr | CVR | marketing | % | - | kpi_leads |
| kpi_clicks | クリック数 | marketing | 件 | - | kpi_leads |

### Phase 3: HTML 리포트 확장

#### 새로운 페이지 추가
1. **KPIダッシュボード** - KPI 카드 그리드 + 트리 시각화
2. **KPI分析表** - 계획 vs 실적 비교 테이블
3. **ボトルネック分析** - AI 기반 병목 분석

#### UI 컴포넌트
```
┌─────────────────────────────────────────────────────┐
│  KPIダッシュボード                                    │
├─────────────────────────────────────────────────────┤
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐│
│  │ リード数  │ │ 商談数   │ │ 契約数   │ │  売上    ││
│  │   380    │ │   31     │ │   19     │ │  95万    ││
│  │  ▲+5%   │ │  ▼-23%  │ │  ▼-5%   │ │  ▼-5%   ││
│  │ Marketing│ │  Sales   │ │  Sales   │ │  KGI     ││
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘│
├─────────────────────────────────────────────────────┤
│  KPIツリー (インタラクティブ)                         │
│                                                      │
│                    ┌─────────┐                       │
│                    │  売上   │                       │
│                    │  100万  │                       │
│                    └────┬────┘                       │
│              ┌──────────┴──────────┐                 │
│         ┌────┴────┐          ┌────┴────┐            │
│         │ 契約単価 │    ×    │ 契約数  │            │
│         │   5万   │          │  20件   │            │
│         └─────────┘          └────┬────┘            │
│                            ┌──────┴──────┐          │
│                       ┌────┴────┐   ┌────┴────┐     │
│                       │ 成約率  │ × │ 商談数  │     │
│                       │  50%   │   │  40件   │     │
│                       └─────────┘   └────┬────┘     │
│                                    ┌──────┴──────┐   │
│                               ┌────┴────┐  ┌────┴───┐│
│                               │商談化率 │×│リード数 ││
│                               │  10%   │  │ 400件  ││
│                               └─────────┘  └────────┘│
└─────────────────────────────────────────────────────┘
```

### Phase 4: AI 분석 확장

#### Gemini 프롬프트 확장
```python
def generate_kpi_bottleneck_analysis(kpi_tree: KPITree) -> str:
    """KPI 병목 분석"""
    prompt = """
    以下のKPIツリーデータを分析し、ボトルネックを特定してください。

    ## KPIデータ
    {kpi_data}

    ## 分析要求
    1. 最も達成率が低いKPIを特定
    2. そのKPIが結果指標（売上）に与える影響を計算
    3. 改善のための具体的なアクションを提案
    4. 改善した場合の売上予測を算出
    """
```

---

## 3. 구현 우선순위

### MVP (2-3일)
1. [ ] KPI 데이터 모델 추가 (`data_models.py`)
2. [ ] Google Sheets KPI 시트 파싱 (`sheets_client.py`)
3. [ ] KPI 대시보드 페이지 추가 (`html/generator.py`)
4. [ ] 기본 KPI 카드 + 진행률 바

### Phase 2 (1주)
5. [ ] KPI 트리 시각화 (D3.js 또는 Chart.js)
6. [ ] 부서별 KPI 필터링
7. [ ] AI 병목 분석 추가
8. [ ] KPI 예측 기능

### Phase 3 (2주)
9. [ ] 인터랙티브 드릴다운
10. [ ] KPI 알림/경고 시스템
11. [ ] 다중 사업부 지원
12. [ ] 커스텀 KPI 템플릿

---

## 4. 기술 스택

### 현재 (유지)
- Python 3.10+
- Google Sheets API
- Gemini AI
- HTML + Chart.js

### 추가 검토
- **D3.js**: KPI 트리 시각화 (복잡한 트리 구조)
- **Mermaid.js**: 간단한 플로우차트 (대안)
- **Cytoscape.js**: 네트워크 그래프 (대안)

---

## 5. 샘플 Google Sheets 구조

### KPI_Master 시트
```
A: ID           B: Name           C: Category   D: Unit  E: Formula                    F: Parent
kgi_sales       売上高            result        円       contract_count*contract_price  -
kpi_cc          契約数            sales         件       close_rate*meetings            kgi_sales
kpi_cp          契約単価          sales         円       -                              kgi_sales
kpi_cr          成約率            sales         %        -                              kpi_cc
kpi_mtg         商談数            sales         件       meeting_rate*leads             kpi_cc
kpi_mr          商談化率          is            %        -                              kpi_mtg
kpi_leads       リード数          marketing     件       cvr*clicks                     kpi_mtg
kpi_cvr         CVR               marketing     %        -                              kpi_leads
kpi_clicks      クリック数        marketing     件       -                              kpi_leads
```

### KPI_Data 시트
```
A: ID        B: Type   C: 2025-04  D: 2025-05  E: 2025-06 ...
kgi_sales    plan      2000000     2100000     2200000
kgi_sales    actual    1800000     1950000     0
kpi_cc       plan      40          42          44
kpi_cc       actual    36          38          0
...
```

---

## 6. 예상 효과

### 비즈니스 가치
1. **선행지표 관리**: 결과가 아닌 프로세스 관리 가능
2. **병목 조기 발견**: AI가 문제 KPI 자동 감지
3. **부서 간 연계**: 마케팅-세일즈-경영 데이터 통합
4. **예측 정확도**: KPI 기반 매출 예측

### 차별화 포인트
- Scale Cloud 수준의 기능을 오픈소스/저비용으로 제공
- Gemini AI 기반 자동 분석
- Google Sheets 연동 (기존 데이터 활용)

---

## 7. 다음 단계

1. **사용자 확인**: 어떤 KPI를 관리하고 싶은지 구체화
2. **샘플 데이터**: GemEgg용 KPI 샘플 시트 생성
3. **MVP 개발**: 기본 KPI 대시보드 구현
4. **피드백 반영**: 실제 사용 후 개선