# 📦 EZ Pickup — 창고 픽업 최단경로 최적화 (포트폴리오 데모)

> 송장 번호만 입력하면, 픽업할 상품들의 위치를 창고 도면에서 찾아 **최단 이동 경로**를 계산해주는 물류 픽업 지원 시스템.

## 이 프로젝트가 하는 일

물류센터에서 배송을 나가기 전, 담당자는 여러 송장에 포함된 상품을 창고에서 하나씩 골라야 합니다.
송장 수십 건이 쌓이면 "어느 상품이 어디 있고, 어떤 순서로 가야 가장 빠른지"를 머리로 계산하기 어렵습니다.

이 시스템은 이 과정을 자동화합니다:

1. **송장 입력** → 송장 번호에 해당하는 상품 내역을 자동 조회
   - (실무 버전: 이지어드민(EasyAdmin) 관리자 페이지 자동 로그인 후 크롤링)
2. **상품 좌표 매핑** → 상품별 창고 위치(칸/층)를 도면에서 조회
3. **최단 경로 계산** → BFS로 통로 간 거리를 계산하고, TSP(외판원 문제)로 방문 순서 최적화
4. **결과 제공** → 창고 도면 위에 색상별 경로 + 픽업 체크리스트(수량/층수)를 한 화면에 표시

## 핵심 기술 포인트

| 구분 | 내용 |
|------|------|
| 창고 모델링 | 도면 시트를 그리드로 변환 — `warehouse`(상품칸) / `Corridor`(통로) / `START`(출발점) |
| 경로 탐색 | BFS(너비 우선 탐색)로 통로 간 최단거리 행렬 계산 |
| 순서 최적화 | 순열 탐색 기반 TSP — 방문 순서를 바꿔가며 총 이동거리 최소화 |
| 시각화 | matplotlib로 도면 + 경로(구간별 색상·화살표) + 픽업칸 강조 이미지 생성 |
| 결과 공유 | 담당자별 결과 페이지 생성 — 실무 버전은 GitHub Pages 업로드 + QR 공유 |

## 데모 실행 방법

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

브라우저에서 **http://localhost:3939** 접속 → 예시 송장 `00001`~`00010` 중
아무거나 2~3개 선택 후 **제출** → 최단 경로 이미지 + 픽업 체크리스트 확인.

> 💡 `00010` 송장에는 **좌표가 없는 상품(미배치상품)**이 포함되어 있어,
> 체크리스트에 빨간색 경고가 표시되는 에러 처리 흐름도 함께 확인할 수 있습니다.

## 프로젝트 구조

```
ez-pickup-demo/
├── app.py                    # Flask 웹 서버 (데모: 로컬 데이터 사용)
├── navi.py                   # 핵심 알고리즘 — 그리드 로딩 / BFS / TSP / 시각화
├── data/
│   ├── demo_data.xlsx        # 창고 도면 + 예시 상품 위치 (실데이터 비식별화)
│   └── sample_invoices.json  # 예시 송장 → 상품 매핑
├── templates/                # 메인 페이지 / 결과 페이지
├── static/results/           # 생성된 경로 이미지 + 결과 HTML
└── requirements.txt
```

## 실무 적용 스토리

- **문제**: 고정 배송 인력 + 교육비를 들여도, 신규 알바는 창고 위치를 몰라 첫날부터 제대로 일할 수 없음
- **해결**: 이 앱 하나면 **누구나** 송장만 입력해도 최단 경로와 픽업 목록을 받을 수 있어,
  고정 인력 없이 유연한 알바 체제로 전환 가능 (불필요한 시기 인원 감축 목적)
- **설계 의도**: 예측을 강제하지 않고 "참고 도구"로 제공해 현장 반발 없이 도입 가능하게 설계

---

*본 데모는 실제 운영 데이터(상품명/계정 정보)를 모두 예시 데이터로 교체한 버전입니다.*