ERP-node/제어관리_외부커넥션_통합_기능_가이드.md

# 🔧 제어관리 외부 커넥션 통합 기능 사용 가이드

## 📋 기능 개요

제어관리 시스템에 외부 데이터베이스 커넥션 연동 기능이 추가되었습니다. 이제 데이터 저장 액션에서 외부 DB나 자기 자신의 테이블에 INSERT, UPDATE, DELETE 작업을 수행할 수 있습니다.

## 🚀 주요 기능

### 1. **다중 커넥션 지원**

- 메인 데이터베이스 (현재 시스템)
- 외부 데이터베이스 (MySQL, PostgreSQL, Oracle, SQL Server 등)
- FROM/TO 커넥션을 독립적으로 선택 가능

### 2. **액션 타입별 지원**

- **INSERT**: 외부 DB에서 데이터 조회 → 다른 DB에 삽입
- **UPDATE**: 조건 확인 후 대상 테이블 업데이트
- **DELETE**: 조건 확인 후 대상 테이블 데이터 삭제

### 3. **자기 자신 테이블 작업**

- 같은 테이블 내에서 UPDATE/DELETE 작업 지원
- 강화된 안전장치로 데이터 손실 방지

## 📖 사용 방법

### 1단계: 커넥션 선택

제어관리에서 데이터 저장 액션을 생성할 때, 먼저 FROM/TO 커넥션을 선택합니다.

```
📍 커넥션 선택 화면
┌─────────────────────────────────────────────────────────┐
│ FROM 커넥션 (소스)           │ TO 커넥션 (대상)            │
│ ┌─────────────────────────┐ │ ┌─────────────────────────┐ │
│ │ [현재 DB] 메인 시스템   │ │ │ [MySQL] 외부 DB 1      │ │
│ │ [PostgreSQL] 외부 DB 2  │ │ │ [Oracle] 외부 DB 3     │ │
│ └─────────────────────────┘ │ └─────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```

### 2단계: 테이블 선택

선택한 커넥션에서 사용할 테이블을 선택합니다.

```
📍 테이블 선택 화면
┌─────────────────────────────────────────────────────────┐
│ FROM 테이블                  │ TO 테이블                   │
│ ┌─────────────────────────┐ │ ┌─────────────────────────┐ │
│ │ 🔍 [검색: user]        │ │ │ 🔍 [검색: order]       │ │
│ │ 📊 user_info (15 컬럼) │ │ │ 📊 order_log (8 컬럼)  │ │
│ │ 📊 user_auth (5 컬럼)  │ │ │ 📊 order_items (12 컬럼)│ │
│ └─────────────────────────┘ │ └─────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```

### 3단계: 액션별 설정

#### 🔄 INSERT 액션

FROM 테이블의 데이터를 TO 테이블에 삽입하는 필드 매핑을 설정합니다.

```
매핑 규칙:
✅ 1:1 매핑: FROM.user_id → TO.customer_id
✅ 1:N 매핑: FROM.name → TO.first_name, TO.display_name
❌ N:1 매핑: FROM.first_name, FROM.last_name → TO.name (금지)
```

#### 🔄 UPDATE 액션

3가지 설정 영역이 있습니다:

1. **업데이트 조건**: FROM 테이블에서 어떤 조건을 만족할 때 실행할지
2. **필드 매핑**: FROM 데이터를 TO 테이블의 어떤 필드에 업데이트할지
3. **WHERE 조건**: TO 테이블에서 어떤 레코드를 업데이트할지

```
예시 설정:
🔍 업데이트 조건: FROM.status = 'completed' AND FROM.updated_at > '2024-01-01'
📝 필드 매핑: FROM.result_value → TO.final_score
🎯 WHERE 조건: TO.user_id = FROM.user_id AND TO.status = 'pending'
```

#### 🔄 DELETE 액션

2가지 설정 영역과 안전장치가 있습니다:

1. **삭제 트리거 조건**: FROM 테이블에서 어떤 조건을 만족할 때 삭제할지
2. **WHERE 조건**: TO 테이블에서 어떤 레코드를 삭제할지
3. **안전장치**: 최대 삭제 개수, 확인 요구, Dry Run 등

```
예시 설정:
🔥 삭제 조건: FROM.is_expired = 'Y' AND FROM.cleanup_date < NOW()
🎯 WHERE 조건: TO.ref_id = FROM.id AND TO.status = 'inactive'
🛡️ 안전장치: 최대 100개, 확인 요구, Dry Run 실행
```

## ⚠️ 자기 자신 테이블 작업 주의사항

### UPDATE 작업 시

```
⚠️ 주의사항:
- WHERE 조건 필수 설정
- 업데이트 조건과 WHERE 조건 겹침 방지
- 무한 루프 위험 체크

✅ 안전한 예시:
UPDATE user_info
SET last_login = NOW(), login_count = login_count + 1
WHERE user_id = 'specific_user' AND status = 'active'
```

### DELETE 작업 시

```
🚨 강화된 안전장치:
- 최대 삭제 개수 10개로 제한
- 부정 조건(!=, NOT IN, NOT EXISTS) 금지
- WHERE 조건 2개 이상 권장

✅ 안전한 예시:
DELETE FROM temp_data
WHERE created_at < NOW() - INTERVAL '7 days'
AND status = 'processed'
AND batch_id = 'specific_batch'
LIMIT 10
```

## 🛠️ 실제 사용 시나리오

### 시나리오 1: 사용자 로그인 정보 업데이트

```
목적: 사용자 로그인 시 마지막 로그인 시간과 로그인 횟수 업데이트

설정:
- FROM: login_logs 테이블 (메인 DB)
- TO: user_info 테이블 (메인 DB)
- 액션: UPDATE

조건:
🔍 업데이트 조건: login_logs.status = 'success' AND login_logs.created_at > NOW() - INTERVAL '1 minute'
📝 필드 매핑:
  - login_logs.created_at → user_info.last_login
  - login_logs.user_agent → user_info.last_user_agent
🎯 WHERE 조건: user_info.user_id = login_logs.user_id
```

### 시나리오 2: 외부 시스템에서 주문 데이터 동기화

```
목적: 외부 쇼핑몰 시스템의 주문 데이터를 내부 ERP에 저장

설정:
- FROM: orders 테이블 (외부 MySQL DB)
- TO: erp_orders 테이블 (메인 PostgreSQL DB)
- 액션: INSERT

매핑:
✅ 필드 매핑:
  - orders.order_id → erp_orders.external_order_id
  - orders.customer_name → erp_orders.customer_name
  - orders.total_amount → erp_orders.order_amount
  - orders.order_date → erp_orders.received_date
```

### 시나리오 3: 만료된 임시 데이터 정리

```
목적: 배치 작업 완료 후 임시 처리 데이터 자동 삭제

설정:
- FROM: batch_jobs 테이블 (메인 DB)
- TO: temp_processing_data 테이블 (메인 DB)
- 액션: DELETE

조건:
🔥 삭제 조건: batch_jobs.status = 'completed' AND batch_jobs.completed_at < NOW() - INTERVAL '1 hour'
🎯 WHERE 조건:
  - temp_processing_data.batch_id = batch_jobs.batch_id
  - temp_processing_data.status = 'processed'
🛡️ 안전장치: 최대 100개, Dry Run 먼저 실행
```

## 🔧 API 사용법

### 활성 커넥션 조회

```typescript
import { getActiveConnections } from "@/lib/api/multiConnection";

const connections = await getActiveConnections();
// 결과: [{ id: 0, connection_name: '메인 데이터베이스' }, ...]
```

### 테이블 목록 조회

```typescript
import { getTablesFromConnection } from "@/lib/api/multiConnection";

const tables = await getTablesFromConnection(connectionId);
// 결과: [{ tableName: 'users', columnCount: 15 }, ...]
```

### 컬럼 정보 조회

```typescript
import { getColumnsFromConnection } from "@/lib/api/multiConnection";

const columns = await getColumnsFromConnection(connectionId, "users");
// 결과: [{ columnName: 'id', dataType: 'int', isPrimaryKey: true }, ...]
```

## 🚨 문제 해결

### 일반적인 오류

#### 1. 커넥션 연결 실패

```
오류: "커넥션을 찾을 수 없습니다"
해결: 외부 커넥션 관리에서 해당 커넥션이 활성 상태인지 확인
```

#### 2. 테이블 접근 권한 부족

```
오류: "테이블에 접근할 수 없습니다"
해결: 데이터베이스 사용자의 테이블 권한 확인
```

#### 3. 매핑 제약사항 위반

```
오류: "대상 컬럼이 이미 매핑되어 있습니다"
해결: N:1 매핑이 아닌 1:N 매핑으로 변경
```

#### 4. 자기 자신 테이블 작업 실패

```
오류: "WHERE 조건이 필수입니다"
해결: UPDATE/DELETE 작업 시 WHERE 조건 추가
```

### 성능 최적화

1. **인덱스 활용**: WHERE 조건에 사용되는 컬럼에 인덱스 생성
2. **배치 크기 조정**: 대량 데이터 처리 시 적절한 배치 크기 설정
3. **커넥션 풀링**: 외부 DB 연결 시 커넥션 풀 최적화

## 📞 지원

문제가 발생하거나 추가 기능이 필요한 경우:

1. **로그 확인**: 브라우저 개발자 도구의 콘솔 탭 확인
2. **에러 메시지**: 상세한 에러 메시지와 함께 문의
3. **설정 정보**: 사용한 커넥션, 테이블, 액션 타입 정보 제공

---

**📝 마지막 업데이트**: 2024년 12월
**🔧 버전**: v1.0.0
**📧 문의**: 시스템 관리자