kjs
/
ERP-node
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ERP-node/docs/컬럼_매핑_사용_가이드.md

7.7 KiB
Raw Permalink Blame History

컬럼 매핑 기능 사용 가이드

📋 개요

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

🎯 사용 시나리오

시나리오 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)

SELECT 
  customer_name,
  order_amount,
  order_date
FROM orders

컬럼 매핑:

  • customer_name → name
  • order_amount → amount
  • order_date → date

데이터 소스 2 (외부 API)

API 응답:

[
  { "clientName": "홍길동", "totalPrice": 50000, "timestamp": "2025-01-01" }
]

컬럼 매핑:

  • clientName → name
  • totalPrice → amount
  • timestamp → date

결과 (통합된 데이터):

[
  { "name": "홍길동", "amount": 50000, "date": "2025-01-01", "_source": "내부 DB" },
  { "name": "홍길동", "amount": 50000, "date": "2025-01-01", "_source": "외부 API" }
]

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

데이터 소스 1 (기상청 API)

[
  { "location": "서울", "lat": 37.5665, "lon": 126.9780, "temp": 15 }
]

컬럼 매핑:

  • lat → latitude
  • lon → longitude
  • location → name

데이터 소스 2 (교통정보 DB)

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)

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 모두 지원
  • ✅ 실시간으로 결과 확인
  • ✅ 언제든지 수정 가능

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