# 노드 플로우 데이터 소스 설정 가이드

## 개요

노드 플로우 편집기에서 **테이블 소스 노드**와 **외부 DB 소스 노드**에 데이터 소스 타입을 설정할 수 있습니다. 이제 버튼에서 전달된 데이터를 사용할지, 아니면 테이블의 전체 데이터를 직접 조회할지 선택할 수 있습니다.

## 지원 노드

### 1. 테이블 소스 노드 (내부 DB)
- **위치**: 노드 팔레트 > 데이터 소스 > 테이블 소스
- **용도**: 내부 데이터베이스의 테이블 데이터 조회

### 2. 외부 DB 소스 노드
- **위치**: 노드 팔레트 > 데이터 소스 > 외부 DB 소스
- **용도**: 외부 데이터베이스의 테이블 데이터 조회

## 데이터 소스 타입

### 1. 컨텍스트 데이터 (기본값)
```
💡 컨텍스트 데이터 모드
버튼 실행 시 전달된 데이터(폼 데이터, 테이블 선택 항목 등)를 사용합니다.

사용 예시:
• 폼 데이터: 1개 레코드
• 테이블 선택: N개 레코드
```

**특징:**
- ✅ 버튼에서 제어한 데이터만 처리
- ✅ 성능 우수 (필요한 데이터만 사용)
- ✅ 사용자가 선택한 데이터만 처리
- ⚠️ 버튼 설정에서 데이터 소스를 올바르게 설정해야 함

**사용 시나리오:**
- 폼 데이터로 새 레코드 생성
- 테이블에서 선택한 항목 일괄 업데이트
- 사용자가 선택한 데이터만 처리

### 2. 테이블 전체 데이터
```
📊 테이블 전체 데이터 모드
선택한 테이블의 **모든 행**을 직접 조회합니다.

⚠️ 대량 데이터 시 성능 주의
```

**특징:**
- ✅ 테이블의 모든 데이터 처리
- ✅ 버튼 설정과 무관하게 동작
- ✅ 자동으로 전체 데이터 조회
- ⚠️ 대량 데이터 시 메모리 및 성능 이슈 가능
- ⚠️ 네트워크 부하 증가

**사용 시나리오:**
- 전체 데이터 통계/집계
- 일괄 데이터 마이그레이션
- 전체 데이터 검증
- 백업/복원 작업

## 설정 방법

### 1단계: 노드 추가
1. 노드 플로우 편집기 열기
2. 좌측 팔레트에서 **테이블 소스** 또는 **외부 DB 소스** 드래그
3. 캔버스에 노드 배치

### 2단계: 테이블 선택
1. 노드 클릭하여 선택
2. 우측 **속성 패널** 열림
3. **테이블 선택** 드롭다운에서 테이블 선택

### 3단계: 데이터 소스 설정
1. **데이터 소스 설정** 섹션으로 스크롤
2. **데이터 소스 타입** 드롭다운 클릭
3. 원하는 모드 선택:
   - **컨텍스트 데이터**: 버튼에서 전달된 데이터 사용
   - **테이블 전체 데이터**: 테이블의 모든 행 조회

### 4단계: 저장
- 변경 사항은 **즉시 노드에 반영**됩니다.
- 별도 저장 버튼 불필요 (자동 저장)

## 사용 예시

### 예시 1: 선택된 항목만 처리 (컨텍스트 데이터)

**시나리오**: 사용자가 테이블에서 선택한 주문만 승인 처리

**플로우 구성:**
```
[테이블 소스: orders]
  └─ 데이터 소스: 컨텍스트 데이터
     └─ [조건: status = 'pending']
        └─ [업데이트: status = 'approved']
```

**버튼 설정:**
- 제어 데이터 소스: `table-selection` (테이블 선택 항목)

**실행 결과:**
- 사용자가 선택한 3개 주문만 승인 처리
- 나머지 주문은 변경되지 않음

### 예시 2: 전체 데이터 일괄 처리 (테이블 전체 데이터)

**시나리오**: 모든 고객의 등급을 재계산

**플로우 구성:**
```
[테이블 소스: customers]
  └─ 데이터 소스: 테이블 전체 데이터
     └─ [데이터 변환: 등급 계산]
        └─ [업데이트: grade = 계산된 등급]
```

**버튼 설정:**
- 제어 데이터 소스: 무관 (테이블 전체를 자동 조회)

**실행 결과:**
- 모든 고객 레코드의 등급 재계산
- 1,000개 고객 → 1,000개 모두 업데이트

### 예시 3: 외부 DB 전체 데이터 동기화

**시나리오**: 외부 ERP의 모든 제품 정보를 내부 DB로 동기화

**플로우 구성:**
```
[외부 DB 소스: products]
  └─ 데이터 소스: 테이블 전체 데이터
     └─ [Upsert: 내부 DB products 테이블]
```

**실행 결과:**
- 외부 DB의 모든 제품 데이터 조회
- 내부 DB에 동기화 (있으면 업데이트, 없으면 삽입)

## 노드 실행 로직

### 컨텍스트 데이터 모드 실행 흐름

```typescript
// 1. 버튼 클릭
// 2. 버튼에서 데이터 전달 (폼, 테이블 선택 등)
// 3. 노드 플로우 실행
// 4. 테이블 소스 노드가 전달받은 데이터 사용

{
  nodeType: "tableSource",
  config: {
    tableName: "orders",
    dataSourceType: "context-data"
  },
  // 실행 시 버튼에서 전달된 데이터 사용
  input: [
    { id: 1, status: "pending" },
    { id: 2, status: "pending" }
  ]
}
```

### 테이블 전체 데이터 모드 실행 흐름

```typescript
// 1. 버튼 클릭
// 2. 노드 플로우 실행
// 3. 테이블 소스 노드가 직접 DB 조회
// 4. 모든 행을 반환

{
  nodeType: "tableSource",
  config: {
    tableName: "orders",
    dataSourceType: "table-all"
  },
  // 실행 시 DB에서 전체 데이터 조회
  query: "SELECT * FROM orders",
  output: [
    { id: 1, status: "pending" },
    { id: 2, status: "approved" },
    { id: 3, status: "completed" },
    // ... 수천 개의 행
  ]
}
```

## 성능 고려사항

### 컨텍스트 데이터 모드
- ✅ **성능 우수**: 필요한 데이터만 처리
- ✅ **메모리 효율**: 선택된 데이터만 메모리에 로드
- ✅ **네트워크 효율**: 최소한의 데이터 전송

### 테이블 전체 데이터 모드
- ⚠️ **대량 데이터 주의**: 수천~수만 개 행 처리 시 느려질 수 있음
- ⚠️ **메모리 사용**: 모든 데이터를 메모리에 로드
- ⚠️ **네트워크 부하**: 전체 데이터 전송

**권장 사항:**
```
• 데이터가 1,000개 이하: 테이블 전체 데이터 사용 가능
• 데이터가 10,000개 이상: 컨텍스트 데이터 + 필터링 권장
• 데이터가 100,000개 이상: 배치 처리 또는 서버 사이드 처리 필요
```

## 디버깅

### 콘솔 로그 확인

**데이터 소스 타입 변경 시:**
```
✅ 데이터 소스 타입 변경: table-all
```

**노드 실행 시:**
```typescript
// 컨텍스트 데이터 모드
🔍 테이블 소스 노드 실행: orders
📊 입력 데이터: 3건 (컨텍스트에서 전달됨)

// 테이블 전체 데이터 모드
🔍 테이블 소스 노드 실행: orders
📊 테이블 전체 데이터 조회: 1,234건
```

### 일반적인 문제

#### Q1: 컨텍스트 데이터 모드인데 데이터가 없습니다
**A**: 버튼 설정을 확인하세요.
- 버튼 설정 > 제어 데이터 소스가 올바르게 설정되어 있는지 확인
- 폼 데이터: `form`
- 테이블 선택: `table-selection`
- 테이블 전체: `table-all`

#### Q2: 테이블 전체 데이터 모드가 느립니다
**A**: 
1. 데이터 양 확인 (몇 개 행인지?)
2. 필요하면 컨텍스트 데이터 + 필터링으로 변경
3. WHERE 조건으로 범위 제한

#### Q3: 외부 DB 소스가 오래 걸립니다
**A**:
1. 외부 DB 연결 상태 확인
2. 네트워크 지연 확인
3. 외부 DB의 인덱스 확인

## 버튼 설정과의 관계

### 버튼 데이터 소스 vs 노드 데이터 소스

| 버튼 설정 | 노드 설정 | 결과 |
|---------|---------|-----|
| `table-selection` | `context-data` | 선택된 항목만 처리 ✅ |
| `table-all` | `context-data` | 전체 데이터 전달됨 ⚠️ |
| 무관 | `table-all` | 노드가 직접 전체 조회 ✅ |
| `form` | `context-data` | 폼 데이터만 처리 ✅ |

**권장 조합:**
```
1. 선택된 항목 처리:
   버튼: table-selection → 노드: context-data

2. 테이블 전체 처리:
   버튼: 무관 → 노드: table-all

3. 폼 데이터 처리:
   버튼: form → 노드: context-data
```

## 마이그레이션 가이드

### 기존 노드 업데이트

기존에 생성된 노드는 **자동으로 `context-data` 모드**로 설정됩니다.

**업데이트 방법:**
1. 노드 선택
2. 속성 패널 열기
3. 데이터 소스 설정 섹션에서 `table-all`로 변경

## 베스트 프랙티스

### ✅ 좋은 예

```typescript
// 시나리오: 사용자가 선택한 주문 취소
[테이블 소스: orders]
  dataSourceType: "context-data"  // ✅ 선택된 주문만 처리
  ↓
[업데이트: status = 'cancelled']
```

```typescript
// 시나리오: 모든 만료된 쿠폰 삭제
[테이블 소스: coupons]
  dataSourceType: "table-all"  // ✅ 전체 조회 후 필터링
  ↓
[조건: expiry_date < today]
  ↓
[삭제]
```

### ❌ 나쁜 예

```typescript
// 시나리오: 단일 주문 업데이트인데 전체 조회
[테이블 소스: orders]
  dataSourceType: "table-all"  // ❌ 불필요한 전체 조회
  ↓
[조건: id = 123]  // 한 개만 필요한데 전체를 조회함
  ↓
[업데이트]
```

## 요약

### 언제 어떤 모드를 사용해야 하나요?

| 상황 | 권장 모드 |
|------|----------|
| 폼 데이터로 새 레코드 생성 | 컨텍스트 데이터 |
| 테이블에서 선택한 항목 수정 | 컨텍스트 데이터 |
| 전체 데이터 통계/집계 | 테이블 전체 데이터 |
| 일괄 데이터 마이그레이션 | 테이블 전체 데이터 |
| 특정 조건의 데이터 처리 | 테이블 전체 데이터 + 조건 |
| 외부 DB 동기화 | 테이블 전체 데이터 |

### 핵심 원칙

1. **기본은 컨텍스트 데이터**: 대부분의 경우 이것으로 충분합니다.
2. **전체 데이터는 신중히**: 성능 영향을 고려하세요.
3. **버튼과 노드를 함께 설계**: 데이터 흐름을 명확히 이해하세요.

## 관련 문서

- [제어관리_데이터소스_확장_가이드.md](./제어관리_데이터소스_확장_가이드.md) - 버튼 데이터 소스 설정
- 노드 플로우 기본 가이드 (준비 중)

## 업데이트 이력

- **2025-01-24**: 초기 문서 작성
  - 테이블 소스 노드에 데이터 소스 타입 추가
  - 외부 DB 소스 노드에 데이터 소스 타입 추가
  - `context-data`, `table-all` 모드 지원