# 시나리오: 리테일 재고 인텔리전스

지점별 재고 현황, 가격 정보, 경쟁사 가격 모니터링을 통해 가격 경쟁력 분석과 재고 부족 리스크 관리를 지원하는 리테일 재고 관리 시나리오입니다.

---

## 엔티티 관계 개요

```text
컬렉션
  retail_inventory_intelligence  ←── 모든 데이터셋, 파이프라인, 코드, 대시보드

데이터셋
  retail_inventory         ← 가격 및 재고 지표가 포함된 지점별 재고 현황
  competitor_prices        ← 채널·상품별 경쟁사 가격 관측 데이터
  update_competitor_price  ← 최신 경쟁사 가격이 반영된 재고 데이터

파이프라인
  update_competitor_prices   retail_inventory + competitor_prices → update_competitor_price
  ontology_materialization   update_competitor_price → RI_* 온톨로지 테이블

코드
  update_competitor_price (python)  ← item_code 기준으로 재고와 경쟁사 가격 조인
  build_retail_ontology (python)    ← 온톨로지 엔티티/관계 테이블 생성

대시보드
  inventory_overview  ← KPI 통계, 차트, 히트맵, 가격 경쟁력, 상세 테이블

온톨로지
  엔티티: ri_product, ri_branch, ri_region, ri_supplier
  관계:
    ri_located_in   (ri_branch → ri_region)
    ri_stocked_at   (ri_product → ri_branch)
    ri_supplied_by  (ri_product → ri_supplier)
```

---

## 데이터셋

| 이름 | 유형 | 설명 |
| ---- | ---- | ---- |
| `retail_inventory` | delta | 지점별 상품 재고: 재고 수량, 가격, 재고 회전율, 재고 부족 리스크 |
| `competitor_prices` | delta | 채널·지점·상품별 경쟁사 가격 관측 데이터 |
| `update_competitor_price` | delta | 경쟁사 가격 관측 데이터가 반영된 `competitor_price_krw_synth` 업데이트 결과 |

---

## 파이프라인

### `update_competitor_prices`

**목적:** 구매 담당자와 카테고리 매니저가 오래된 스냅샷이 아닌 실시간 시장 데이터를 기반으로 가격 의사결정을 내릴 수 있도록, 재고 데이터셋에 최신 경쟁사 가격 정보를 지속적으로 반영합니다.

`item_code`를 기준으로 `retail_inventory`와 `competitor_prices`를 조인합니다. 각 재고 레코드에 대해 동일 상품의 최신 경쟁사 가격 관측값을 조회하고 `competitor_price_krw_synth` 컬럼을 덮어씁니다. 출력은 overwrite 모드로 기록되므로 항상 현재 시장 상태를 반영합니다.

| 스텝 | 스크립트 | 입력 → 출력 | 역할 |
| ---- | -------- | ----------- | ---- |
| `update_competitor_price` | `update_competitor_price` | `retail_inventory` + `competitor_prices` → `update_competitor_price` | `item_code` 기준 조인 후 경쟁사 가격 컬럼 최신화 |

### `ontology_materialization`

**목적:** 경쟁사 가격이 반영된 재고 데이터셋에서 그래프 적재용 엔티티·관계 테이블을 생성합니다.

| 스텝 | 스크립트 | 입력 → 출력 | 역할 |
| ---- | -------- | ----------- | ---- |
| `build_ontology_tables` | `build_retail_ontology` | `update_competitor_price` → `ri_product`, `ri_branch`, `ri_region`, `ri_supplier`, `ri_located_in`, `ri_stocked_at`, `ri_supplied_by` | 그래프 import용 1급 온톨로지 테이블 생성 |

---

## 온톨로지

| 유형 | 이름 | 관계 |
| ---- | ---- | ---- |
| 엔티티 | `ri_product` | 상품 마스터 |
| 엔티티 | `ri_branch` | 지점 마스터 |
| 엔티티 | `ri_region` | 지역 마스터 |
| 엔티티 | `ri_supplier` | 공급업체 마스터 |
| 관계 | `ri_located_in` | ri_branch → ri_region |
| 관계 | `ri_stocked_at` | ri_product → ri_branch |
| 관계 | `ri_supplied_by` | ri_product → ri_supplier |

---

## 대시보드

### `inventory_overview`

**목적:** 전국 지점의 재고 건강 상태와 가격 경쟁력을 한눈에 파악할 수 있는 단일 뷰를 제공합니다 — KPI 요약, 재고 분포, 출고 추이, 시간대별 패턴, 경쟁사 가격차, 상세 드릴다운을 포함합니다.

대시보드의 freshness는 파생 데이터셋인 `update_competitor_price` 갱신 시점을 따릅니다. 가격 경쟁력 위젯을 확인하기 전 `update_competitor_prices`를 실행해야 경쟁사 가격차가 최신 관측값을 반영합니다.

| 위젯 | 유형 | 설명 |
| ---- | ---- | ---- |
| 총 재고량 | statistic | 전체 지점 `SUM(inventory_qty)` |
| 총 출고량 | statistic | 전체 지점 `SUM(outbound_qty)` |
| 평균 회전율 | statistic | `AVG(inventory_turnover_rate)` |
| 품절위험 | statistic | `stockout_risk_flag_synth = 1` 항목 수 |
| 평균할인율 | statistic | `AVG(discount_rate_synth)` |
| 지점별 재고/출고 현황 | bar-chart (stacked) | 지점별 재고 대비 출고량 비교 |
| 일별 출고 추이 | line-chart | `delivery_date` 기준 지점별 멀티 시리즈 라인 차트 |
| 시간대별 출고 히트맵 | heatmap | `delivery_time` × `branch_name` 강도 맵 |
| 지점별 재고 비율 | pie-chart (donut) | 지점별 재고 비율 분포 |
| 재고 상세 데이터 | data-table | 지점, 창고, 수량, 회전율, 리스크 포함 정렬/검색 가능 테이블 |
| 경쟁사 대비 고가 품목 | statistic | 자사 판매가가 경쟁사 가격보다 높은 지점-상품 건수 |
| 지점별 평균 가격차이 | bar-chart | 지점별 평균 판매가-경쟁사가 차이 |
| 가격 조정 후보 | data-table | 경쟁사 대비 가격차가 큰 지점-상품 후보 |

---

## 샘플 데이터

추적되는 샘플 데이터는 `data/parquet/` 아래에 있습니다. CSV export는 `data/csv/README.md`에 문서화되어 있고 repository에는 포함하지 않습니다.

- `retail_inventory.csv` — id, item_code, product_name, branch_code, work_order_no, PROD_GRP, branch_name, warehouse_location, warn_clearnace, delivery_date, delivery_time, manager_id, inventory_qty, outbound_qty, stock_variance, inventory_turnover_rate, safety_stock_level, list_price_krw_synth, selling_price_krw_synth, discount_rate_synth, unit_cost_krw_synth, promo_flag_synth, competitor_price_krw_synth, stockout_risk_flag_synth, latitude, longitude, region_name, supplier_name
- `competitor_prices.csv` — competitor_id, channel_type, branch_code, item_code, observed_at, price_krw, price_type, promo_flag, source, currency
