# 📈 상품 수요예측 — Prophet 시계열 ML (포트폴리오 데모)

> 상품별 과거 판매 데이터를 기반으로 **미래 수요를 예측**하는 시계열 머신러닝 시스템.
> 예측 결과를 **인터랙티브 그래프(HTML)**로 생성해 발주/생산 의사결정을 지원합니다.

## 이 프로젝트가 하는 일

의류 브랜드의 생산 리드타임은 보통 한 달 이상입니다. "지금 주문해야 두 달 뒤에 받는다"는 구조에서,
감으로 발주하면 재고 과잉/부족이 반복됩니다. 이 시스템은 과거 판매 데이터로 미래 수요를 예측해
발주 시점의 의사결정 근거를 제공합니다.

1. **월 판매량 집계** — 일 단위 주문 데이터를 상품(코드)별 월 판매량/평균 판매가로 집계
2. **시계열 모델 학습** — Prophet(로지스틱 성장) + 한국 공휴일·특수 이벤트(블랙프라이데이/설날) 반영
3. **도메인 규칙 적용** — 비수기(4~8월)는 상한선(cap)을 낮춰 발주 제한 규칙을 모델에 반영
4. **예측 후처리** — 이상치 스무딩, 상/하한 클리핑
5. **인터랙티브 시각화** — 실판매량(빨강) + 예측 평균 + 예측 범위를 HTML 그래프로 제공

## 핵심 기술 포인트

| 구분 | 내용 |
|------|------|
| 시계열 모델 | Prophet (logistic growth, 연간 계절성 약하게, 주간/일간 비활성화) |
| 외부 변수 | 한국 공휴일 + 블랙프라이데이/크리스마스/설날 특수 이벤트 |
| 도메인 규칙 | 비수기(4~8월) 발주 제한 → 상한선(cap)으로 구현 |
| 전처리 | 최근 6개월 필터, 월 집계, 결측월 0 처리, 평균 판매가 병합 |
| 시각화 | Plotly 인터랙티브 HTML (호버 시 판매량/평균가 표시) |

## 데모 실행 방법

```bash
pip install -r requirements.txt
python demand_forecast.py
```

실행하면 `output/` 폴더에 상품(PRD-101 ~ PRD-108)별 인터랙티브 예측 그래프와
`index.html`이 생성됩니다.

> 💡 그래프에서 **빨간 선 = 실판매량**, **파란 선 = 예측 평균**, **연한 영역 = 예측 범위**입니다.
> 비수기(4~8월)에 예측이 급감하는 모습에서 도메인 규칙(cap)이 반영된 걸 확인할 수 있습니다.

## 프로젝트 구조

```
ml-demand-forecast/
├── demand_forecast.py      # 전처리 → Prophet 학습 → 예측 → 시각화 파이프라인
├── data/
│   └── demo_sales.xlsx     # 합성 예시 판매 데이터 (실데이터 비식별화)
├── output/                 # 생성된 인터랙티브 그래프 (HTML)
└── requirements.txt
```

## 실무 적용 스토리

- **문제**: 중국 생산 리드타임(약 1개월) 환경에서 감에 의존한 발주 → 재고 과잉/부족 반복
- **해결**: SKU별 수요예측을 제공해 발주·출하 의사결정의 참고 지표로 활용
- **설계 의도**: 예측을 "강제"가 아닌 "참고 도구"로 제공 — 현장의 판단권을 침해하지 않아
  도입 저항을 줄이는 것이 핵심 설계 원칙

---

*본 데모는 실제 판매 데이터를 모두 합성 예시 데이터로 교체한 버전입니다.*