ERP-node/docs/컬럼_매핑_사용_가이드.md

# 컬럼 매핑 기능 사용 가이드

## 📋 개요

**컬럼 매핑**은 여러 데이터 소스의 서로 다른 컬럼명을 통일된 이름으로 변환하여 데이터를 통합할 수 있게 해주는 기능입니다.

## 🎯 사용 시나리오

### 시나리오 1: 여러 데이터베이스 통합

```
데이터 소스 1 (PostgreSQL):
  SELECT name, amount, created_at FROM orders

데이터 소스 2 (MySQL):
  SELECT product_name, total, order_date FROM sales

데이터 소스 3 (Oracle):
  SELECT item, price, timestamp FROM transactions
```

**문제**: 각 데이터베이스의 컬럼명이 달라서 통합이 어렵습니다.

**해결**: 컬럼 매핑으로 통일!

```
데이터 소스 1 매핑:
  name → product
  amount → value
  created_at → date

데이터 소스 2 매핑:
  product_name → product
  total → value
  order_date → date

데이터 소스 3 매핑:
  item → product
  price → value
  timestamp → date
```

**결과**: 모든 데이터가 `product`, `value`, `date` 컬럼으로 통합됩니다!

---

## 🔧 사용 방법

### 1️⃣ 데이터 소스 추가

대시보드 편집 모드에서 위젯의 "데이터 소스 관리" 섹션으로 이동합니다.

### 2️⃣ 쿼리/API 테스트

- **Database**: SQL 쿼리 입력 후 "쿼리 테스트" 클릭
- **REST API**: API 설정 후 "API 테스트" 클릭

### 3️⃣ 컬럼 매핑 설정

테스트 성공 후 **"🔄 컬럼 매핑 (선택사항)"** 섹션이 나타납니다.

#### 매핑 추가:
1. 드롭다운에서 원본 컬럼 선택
2. 표시 이름 입력 (예: `name` → `product`)
3. 자동으로 매핑 추가됨

#### 매핑 수정:
- 오른쪽 입력 필드에서 표시 이름 변경

#### 매핑 삭제:
- 각 매핑 행의 ❌ 버튼 클릭
- 또는 "초기화" 버튼으로 전체 삭제

### 4️⃣ 적용 및 저장

1. "적용" 버튼 클릭
2. 대시보드 저장

---

## 📊 지원 위젯

컬럼 매핑은 다음 **모든 다중 데이터 소스 위젯**에서 사용 가능합니다:

- ✅ **지도 위젯** (`map-summary-v2`)
- ✅ **통계 카드** (`custom-metric-v2`)
- ✅ **리스트 위젯** (`list-v2`)
- ✅ **리스크/알림 위젯** (`risk-alert-v2`)
- ✅ **차트 위젯** (`chart`)

---

## 💡 실전 예시

### 예시 1: 주문 데이터 통합

**데이터 소스 1 (내부 DB)**
```sql
SELECT 
  customer_name,
  order_amount,
  order_date
FROM orders
```

**컬럼 매핑:**
- `customer_name` → `name`
- `order_amount` → `amount`
- `order_date` → `date`

---

**데이터 소스 2 (외부 API)**

API 응답:
```json
[
  { "clientName": "홍길동", "totalPrice": 50000, "timestamp": "2025-01-01" }
]
```

**컬럼 매핑:**
- `clientName` → `name`
- `totalPrice` → `amount`
- `timestamp` → `date`

---

**결과 (통합된 데이터):**
```json
[
  { "name": "홍길동", "amount": 50000, "date": "2025-01-01", "_source": "내부 DB" },
  { "name": "홍길동", "amount": 50000, "date": "2025-01-01", "_source": "외부 API" }
]
```

---

### 예시 2: 지도 위젯 - 위치 데이터 통합

**데이터 소스 1 (기상청 API)**
```json
[
  { "location": "서울", "lat": 37.5665, "lon": 126.9780, "temp": 15 }
]
```

**컬럼 매핑:**
- `lat` → `latitude`
- `lon` → `longitude`
- `location` → `name`

---

**데이터 소스 2 (교통정보 DB)**
```sql
SELECT 
  address,
  y_coord AS latitude,
  x_coord AS longitude,
  status
FROM traffic_info
```

**컬럼 매핑:**
- `address` → `name`
- (latitude, longitude는 이미 올바른 이름)

---

**결과**: 모든 데이터가 `name`, `latitude`, `longitude`로 통일되어 지도에 표시됩니다!

---

## 🔍 SQL Alias vs 컬럼 매핑

### SQL Alias (방법 1)

```sql
SELECT 
  name AS product,
  amount AS value,
  created_at AS date
FROM orders
```

**장점:**
- SQL 쿼리에서 직접 처리
- 백엔드에서 이미 변환됨

**단점:**
- SQL 지식 필요
- REST API에는 사용 불가

---

### 컬럼 매핑 (방법 2)

UI에서 클릭만으로 설정:
- `name` → `product`
- `amount` → `value`
- `created_at` → `date`

**장점:**
- SQL 지식 불필요
- REST API에도 사용 가능
- 언제든지 수정 가능
- 실시간 미리보기

**단점:**
- 프론트엔드에서 처리 (약간의 오버헤드)

---

## ✨ 권장 사항

### 언제 SQL Alias를 사용할까?
- SQL에 익숙한 경우
- 백엔드에서 처리하고 싶은 경우
- 복잡한 변환 로직이 필요한 경우

### 언제 컬럼 매핑을 사용할까?
- SQL을 모르는 경우
- REST API 데이터를 다룰 때
- 빠르게 테스트하고 싶을 때
- 여러 데이터 소스를 통합할 때

### 두 가지 모두 사용 가능!
- SQL Alias로 일차 변환
- 컬럼 매핑으로 추가 변환
- 예: `SELECT name AS product_name` → 컬럼 매핑: `product_name` → `product`

---

## 🚨 주의사항

### 1. 매핑하지 않은 컬럼은 원본 이름 유지
```
원본: { name: "A", amount: 100, status: "active" }
매핑: { name: "product" }
결과: { product: "A", amount: 100, status: "active" }
```

### 2. 중복 컬럼명 주의
```
원본: { name: "A", product: "B" }
매핑: { name: "product" }
결과: { product: "A" }  // 기존 product 컬럼이 덮어씌워짐!
```

### 3. 대소문자 구분
- PostgreSQL: 소문자 권장 (`user_name`)
- JavaScript: 카멜케이스 권장 (`userName`)
- 매핑으로 통일 가능!

---

## 🔄 데이터 흐름

```
1. 데이터 소스에서 원본 데이터 로드
   ↓
2. 컬럼 매핑 적용 (applyColumnMapping)
   ↓
3. 통일된 컬럼명으로 변환된 데이터
   ↓
4. 위젯에서 표시/처리
```

---

## 📝 기술 세부사항

### 유틸리티 함수

**파일**: `frontend/lib/utils/columnMapping.ts`

#### `applyColumnMapping(data, columnMapping)`
- 데이터 배열에 컬럼 매핑 적용
- 매핑이 없으면 원본 그대로 반환

#### `mergeDataSources(dataSets)`
- 여러 데이터 소스를 병합
- 각 데이터 소스의 매핑을 자동 적용
- `_source` 필드로 출처 표시

---

## 🎓 학습 자료

### 관련 파일
- 타입 정의: `frontend/components/admin/dashboard/types.ts`
- UI 컴포넌트: `frontend/components/admin/dashboard/data-sources/MultiApiConfig.tsx`
- UI 컴포넌트: `frontend/components/admin/dashboard/data-sources/MultiDatabaseConfig.tsx`
- 유틸리티: `frontend/lib/utils/columnMapping.ts`

### 위젯 구현 예시
- 지도: `frontend/components/dashboard/widgets/MapTestWidgetV2.tsx` (subtype: `map-summary-v2`)
- 통계 카드: `frontend/components/dashboard/widgets/CustomMetricTestWidget.tsx` (subtype: `custom-metric-v2`)
- 리스트: `frontend/components/dashboard/widgets/ListTestWidget.tsx` (subtype: `list-v2`)
- 알림: `frontend/components/dashboard/widgets/RiskAlertTestWidget.tsx` (subtype: `risk-alert-v2`)
- 차트: `frontend/components/dashboard/widgets/ChartTestWidget.tsx` (subtype: `chart`)

---

## ❓ FAQ

### Q1: 컬럼 매핑이 저장되나요?
**A**: 네! 대시보드 저장 시 함께 저장됩니다.

### Q2: 매핑 후 원본 컬럼명으로 되돌릴 수 있나요?
**A**: 네! 해당 매핑을 삭제하면 원본 이름으로 돌아갑니다.

### Q3: REST API와 Database를 동시에 매핑할 수 있나요?
**A**: 네! 각 데이터 소스마다 독립적으로 매핑할 수 있습니다.

### Q4: 성능에 영향이 있나요?
**A**: 매우 적습니다. 단순 객체 키 변환이므로 빠릅니다.

### Q5: 컬럼 타입이 변경되나요?
**A**: 아니요! 컬럼 이름만 변경되고, 값과 타입은 그대로 유지됩니다.

---

## 🎉 마무리

컬럼 매핑 기능을 사용하면:
- ✅ 여러 데이터 소스를 쉽게 통합
- ✅ SQL 지식 없이도 데이터 변환
- ✅ REST API와 Database 모두 지원
- ✅ 실시간으로 결과 확인
- ✅ 언제든지 수정 가능

**지금 바로 사용해보세요!** 🚀