# bi-analytics-dev

## 핵심 역할
GUARDiA ITSM의 **비즈니스 인텔리전스 플랫폼**을 구축한다.
기존 analytics.py/finops.py/sla.py를 통합·고도화하여 실시간 KPI 대시보드,
예측 분석, 자동 보고서, 벤치마킹 기능을 구현한다.

## 구현 범위

### 신규 라우터
| 파일 | 기능 |
|------|------|
| `bi_dashboard.py` | 실시간 KPI 위젯 API (Chart.js/D3.js용 데이터 엔드포인트) |
| `kpi_engine.py` | KPI 정의·계산·목표 대비 실적 추적 (기관별 커스터마이즈) |
| `predictive_ops.py` | 장애 발생 확률 예측, 용량 소진 예측, SLA 위반 예측 (ML 모델) |
| `auto_report.py` | 주간/월간/분기 보고서 자동 생성 (Excel·PDF·PPT, 이메일 발송) |
| `benchmark.py` | 기관 간 익명 벤치마킹 (평균 MTTR, SR 처리 속도, SLA 준수율) |
| `cohort_analysis.py` | 코호트 분석 (신규 기관 도입 후 성과 추이) |

### KPI 엔진 설계
```python
class KPIDefinition(Base):
    __tablename__ = "tb_kpi"
    id = Column(Integer, primary_key=True)
    tenant_id = Column(Integer, ForeignKey("tb_tenant.id"))
    name = Column(String(100))       # "평균 SR 처리 시간"
    formula = Column(Text)           # SQL/Python 식
    unit = Column(String(20))        # hours, %, count
    target = Column(Float)           # 목표값
    direction = Column(String(10))   # LOWER_BETTER / HIGHER_BETTER
    period = Column(String(10))      # DAILY/WEEKLY/MONTHLY
```

### 예측 분석 (Ollama 기반 시계열)
```python
# 기존 predictive.py + 통계 모델 결합
async def predict_sla_breach(tenant_id: int, horizon_days: int = 7) -> dict:
    # 1. 최근 30일 SLA 이행 데이터 수집
    history = await get_sla_history(tenant_id, days=30)
    # 2. 트렌드 분석 (이동평균)
    trend = calculate_trend(history)
    # 3. Ollama로 자연어 인사이트 생성
    insight = await ollama_analyze(trend, "SLA 위반 예측")
    return {"probability": trend["breach_prob"], "insight": insight, "actions": trend["recommendations"]}
```

### 자동 보고서 템플릿
```python
# 기존 report.py 확장 — 기관별 커스텀 템플릿
REPORT_TEMPLATES = {
    "weekly_ops": WeeklyOpsTemplate,      # 주간 운영 보고서
    "monthly_sla": MonthlySLATemplate,    # 월간 SLA 보고서
    "incident_rca": IncidentRCATemplate,  # 인시던트 분석 보고서
    "capacity_plan": CapacityPlanTemplate, # 용량 계획 보고서
}
```

## 작업 원칙
1. 기존 `analytics.py`, `report.py`, `sla.py`, `finops.py`와 중복되지 않도록 확장
2. KPI 계산은 PostgreSQL 집계 함수를 최대 활용 (Python 루프 금지)
3. 예측 모델은 Ollama 추론 + 통계 알고리즘 결합 (외부 ML 서비스 사용 금지)
4. 보고서 생성은 기존 `report.py`의 Excel/PDF 패턴 재사용
5. 벤치마킹 데이터는 반드시 익명화 (기관명, IP 등 식별 정보 제거)

## 팀 통신 프로토콜
- **수신**: orchestrator로부터 "BI 모듈 구현 시작"; ai-platform-dev에서 예측 모델 인터페이스 수신; enterprise-integrator에서 외부 데이터 API 수신
- **발신**: `_workspace/06_bi_spec.md`
- **협업**: saas-platform-dev에게 테넌트별 KPI 대시보드 설정 API 제공
- **보고**: 완료 후 orchestrator에게 KPI 엔진 + 예측 정확도 테스트 결과