# PlanitAI KPI 프로젝트 진행 상황

## 프로젝트 개요
AI 기반 KPI 분석 및 리포트 생성 도구 개발

### 목표
- Google Sheets에서 KPI 데이터를 읽어와 분석
- Gemini AI를 활용한 트렌드/병목 분석
- HTML 보고서 자동 생성

---

## 완료된 작업

### Phase 1: 블로그 기획 (v1 ~ v16)
16개의 기획 블로그 포스트 작성 완료
- Scale Cloud의 KPI Tree 개념 분석
- MVP 아키텍처 설계
- 구현 계획 수립

### Phase 2: MVP 코드 구현

#### 2.1 프로젝트 구조 생성
```
planitai-kpi/
├── src/
│   ├── config.py          # 설정 관리 (Pydantic/dataclass)
│   ├── sheets/
│   │   └── client.py      # Google Sheets 클라이언트
│   ├── kpi/
│   │   ├── tree.py        # KPI 트리 구조
│   │   ├── calculator.py  # 수식 계산 엔진 (AST 기반)
│   │   └── analyzer.py    # KPI 분석기
│   ├── ai/
│   │   ├── prompts.py     # 프롬프트 라이브러리
│   │   ├── client.py      # Gemini API 클라이언트
│   │   └── analyzer.py    # AI 분석기
│   ├── output/
│   │   └── html.py        # HTML 보고서 생성기
│   └── main.py            # CLI 엔트리포인트
├── templates/
│   └── report.html        # Jinja2 템플릿
├── tests/
│   ├── test_calculator.py # 수식 계산 테스트
│   └── test_tree.py       # 트리 구조 테스트
├── config/
│   ├── example.yaml       # 예제 설정
│   └── mock_data.json     # 테스트용 mock 데이터
├── pyproject.toml
└── README.md
```

#### 2.2 핵심 기능 구현
- **KPI Tree 엔진**: KGI → KPI → INPUT 계층 구조
- **수식 계산기**: Python AST를 사용한 안전한 수식 평가 (eval() 대신)
- **Google Sheets 클라이언트**: Service Account 인증 기반
- **Gemini AI 통합**: 트렌드 분석, 병목 분석, 경영진 요약
- **HTML 리포트 생성기**: Jinja2 템플릿 기반 반응형 디자인
- **CLI 인터페이스**: Click 프레임워크 사용

#### 2.3 테스트
- 35개 유닛 테스트 모두 통과
- Mock 데이터로 E2E 테스트 완료

### Phase 3: 실제 시트 연동 (2024-12-07)

#### 문제 발견
- 실제 Google Sheets 데이터가 **가로형 피봇 구조**로 되어 있음
- 기존 코드는 **세로형 구조**만 지원

#### 해결
1. **Pivot Parser 추가** (`src/sheets/client.py`)
   - `get_kpi_data_pivot()` 메서드 구현
   - 가로형 데이터에서 기간별 예산/실적 추출

2. **Config 확장** (`src/config.py`)
   - `PivotConfig` dataclass 추가
   - period_row, data_start_col, cols_per_period 등 설정

3. **config.yaml 업데이트**
   - pivot.enabled: true
   - item_mapping으로 시트 항목명 → KPI ID 매핑

#### 테스트 결과
```bash
$ planitai-kpi analyze -c config.yaml -p "2025-04" --skip-ai

📊 Fetched data for 6 periods
📈 売上高: 1,267,940 円 (110.1%)
✅ Report generated: output
```

---

## 현재 상태

### 작동하는 기능
- [x] Google Sheets에서 피봇 형태 데이터 로드
- [x] KPI 트리 구조 생성 및 계산
- [x] 목표 대비 달성률 계산
- [x] HTML 보고서 생성
- [x] Mock 데이터로 테스트
- [x] CLI 명령어 (analyze, validate, tree, init)

### 사용 가능한 기간
- 2025-04, 2025-05, 2025-06, 2025-07, 2025-08, 2025-09 (6개월)

### 테스트된 기간
| 기간 | 売上高 | 달성률 |
|------|--------|--------|
| 2025-04 | ¥1,267,940 | 110.1% |
| 2025-05 | ¥1,123,488 | 95.7% |

---

## 다음 단계 (선택사항)

1. **AI 분석 테스트**: --skip-ai 없이 실행하여 Gemini 분석 확인
2. **PDF 변환**: wkhtmltopdf 또는 weasyprint로 PDF 출력 추가
3. **더 많은 KPI**: 판관비 상세 항목, 손익 구조 트리 확장
4. **다기간 비교**: 전월/전년 대비 분석 기능

---

## 파일 위치
- 프로젝트: `/var/www/tkim.planitai.co.jp/gemegg/20251207-make-pdf-report/project/planitai-kpi/`
- 설정: `config.yaml`
- 인증: `credentials.json`
- 출력: `output/` (HTML 보고서)