vexplor/외부호출_데이터_매핑_시스템_설계서.md

# 외부호출 데이터 매핑 시스템 설계서

## 1. 개요

외부 API 호출 시 데이터를 송수신하고, 이를 내부 테이블과 매핑하는 시스템을 구현합니다.

## 2. 현재 상황 분석

### 2.1 기존 기능

- ✅ REST API 호출 기본 기능
- ✅ 인증 처리 (API Key, Basic, Bearer 등)
- ✅ 요청/응답 테스트 기능
- ✅ 외부호출 설정 저장

### 2.2 필요한 확장 기능

- 🔄 GET 요청 시 응답 데이터를 내부 테이블에 저장
- 🔄 POST 요청 시 내부 테이블 데이터를 외부로 전송
- 🔄 필드 매핑 설정 (외부 필드 ↔ 내부 필드)
- 🔄 데이터 변환 및 검증

## 3. 시스템 아키텍처

### 3.1 데이터 플로우

```
GET 요청 플로우:
내부 이벤트 → 외부 API 호출 → 응답 데이터 → 필드 매핑 → 내부 테이블 저장

POST 요청 플로우:
내부 이벤트 → 내부 테이블 조회 → 필드 매핑 → 외부 API 전송 → 응답 처리
```

### 3.2 컴포넌트 구조

```
ExternalCallPanel
├── RestApiSettings (기존)
├── DataMappingSettings (신규)
│   ├── SourceTableSelector
│   ├── TargetTableSelector
│   ├── FieldMappingEditor
│   └── DataTransformEditor
└── ExternalCallTestPanel (확장)
```

## 4. 데이터베이스 스키마 확장

### 4.1 external_call_configs 테이블 확장

```sql
ALTER TABLE external_call_configs ADD COLUMN IF NOT EXISTS data_mapping_config JSONB;
```

### 4.2 data_mapping_config JSON 구조

```typescript
interface DataMappingConfig {
  direction: "inbound" | "outbound" | "bidirectional";

  // GET 요청용 - 외부 → 내부
  inboundMapping?: {
    targetTable: string;
    targetSchema?: string;
    fieldMappings: FieldMapping[];
    insertMode: "insert" | "upsert" | "update";
    keyFields?: string[]; // upsert/update 시 키 필드
  };

  // POST 요청용 - 내부 → 외부
  outboundMapping?: {
    sourceTable: string;
    sourceSchema?: string;
    sourceFilter?: string; // WHERE 조건
    fieldMappings: FieldMapping[];
  };
}

interface FieldMapping {
  sourceField: string; // 외부 API 필드명 또는 내부 테이블 컬럼명
  targetField: string; // 내부 테이블 컬럼명 또는 외부 API 필드명
  dataType: "string" | "number" | "boolean" | "date" | "json";
  transform?: {
    type: "none" | "constant" | "format" | "function";
    value?: any;
    format?: string; // 날짜 포맷 등
    functionName?: string; // 커스텀 변환 함수
  };
  required?: boolean;
  defaultValue?: any;
}
```

## 5. 프론트엔드 컴포넌트 설계

### 5.1 DataMappingSettings.tsx

```typescript
interface DataMappingSettingsProps {
  config: DataMappingConfig;
  onConfigChange: (config: DataMappingConfig) => void;
  httpMethod: string;
  availableTables: TableInfo[];
}

// 주요 기능:
// - 방향 선택 (inbound/outbound/bidirectional)
// - 소스/타겟 테이블 선택
// - 필드 매핑 에디터
// - 데이터 변환 설정
```

### 5.2 FieldMappingEditor.tsx

```typescript
interface FieldMappingEditorProps {
  mappings: FieldMapping[];
  sourceFields: FieldInfo[];
  targetFields: FieldInfo[];
  onMappingsChange: (mappings: FieldMapping[]) => void;
}

// 주요 기능:
// - 드래그 앤 드롭으로 필드 매핑
// - 데이터 타입 자동 추론
// - 변환 함수 설정
// - 필수 필드 검증
```

### 5.3 DataTransformEditor.tsx

```typescript
// 데이터 변환 규칙 설정
// - 상수값 할당
// - 날짜 포맷 변환
// - 문자열 변환 (대소문자, 트림 등)
// - 커스텀 함수 적용
```

## 6. 백엔드 서비스 확장

### 6.1 ExternalCallExecutor 확장

```typescript
class ExternalCallExecutor {
  async executeWithDataMapping(
    config: ExternalCallConfig,
    triggerData?: any
  ): Promise<ExternalCallResult> {
    const result = await this.executeApiCall(config);

    if (result.success && config.dataMappingConfig) {
      if (config.restApiSettings.httpMethod === "GET") {
        await this.processInboundData(result, config.dataMappingConfig);
      }
    }

    return result;
  }

  private async processInboundData(
    result: ExternalCallResult,
    mappingConfig: DataMappingConfig
  ) {
    // 1. 응답 데이터 파싱
    // 2. 필드 매핑 적용
    // 3. 데이터 변환
    // 4. 데이터베이스 저장
  }

  private async prepareOutboundData(
    mappingConfig: DataMappingConfig,
    triggerData?: any
  ): Promise<any> {
    // 1. 소스 테이블 조회
    // 2. 필드 매핑 적용
    // 3. 데이터 변환
    // 4. API 요청 바디 생성
  }
}
```

### 6.2 DataMappingService.ts (신규)

```typescript
class DataMappingService {
  async mapInboundData(
    sourceData: any,
    mapping: InboundMapping
  ): Promise<any[]> {
    // 외부 데이터 → 내부 테이블 매핑
  }

  async mapOutboundData(
    sourceTable: string,
    mapping: OutboundMapping,
    filter?: any
  ): Promise<any> {
    // 내부 테이블 → 외부 API 매핑
  }

  private transformFieldValue(value: any, transform: FieldTransform): any {
    // 필드 변환 로직
  }
}
```

## 7. 구현 단계

### Phase 1: 기본 매핑 시스템 (1-2주)

1. 데이터베이스 스키마 확장
2. DataMappingSettings 컴포넌트 개발
3. 기본 필드 매핑 기능
4. GET 요청 응답 데이터 저장

### Phase 2: 고급 매핑 기능 (1-2주)

1. POST 요청 데이터 송신
2. 필드 변환 기능
3. upsert/update 모드
4. 배치 처리

### Phase 3: UI/UX 개선 (1주)

1. 드래그 앤 드롭 매핑 에디터
2. 실시간 미리보기
3. 매핑 템플릿
4. 에러 처리 및 로깅

## 8. 사용 시나리오

### 8.1 외부 API에서 데이터 가져오기 (GET)

```
고객사 API → 우리 customer 테이블
- 고객 정보 동기화
- 주문 정보 수집
- 재고 정보 업데이트
```

### 8.2 외부 API로 데이터 보내기 (POST)

```
우리 order 테이블 → 배송사 API
- 주문 정보 전달
- 재고 변동 알림
- 상태 업데이트 전송
```

## 9. 기술적 고려사항

### 9.1 데이터 일관성

- 트랜잭션 처리
- 롤백 메커니즘
- 중복 데이터 처리

### 9.2 성능 최적화

- 배치 처리
- 비동기 처리
- 캐싱 전략

### 9.3 보안

- 데이터 검증
- SQL 인젝션 방지
- 민감 데이터 마스킹

### 9.4 모니터링

- 매핑 실행 로그
- 에러 추적
- 성능 메트릭

## 10. 성공 지표

- ✅ 외부 API 응답 데이터를 내부 테이블에 정확히 저장
- ✅ 내부 테이블 데이터를 외부 API로 정확히 전송
- ✅ 필드 매핑 설정이 직관적이고 사용하기 쉬움
- ✅ 데이터 변환이 정확하고 안정적
- ✅ 에러 발생 시 적절한 처리 및 알림

## 11. 다음 단계

1. **우선순위 결정**: GET/POST 중 어느 것부터 구현할지
2. **테이블 선택**: 매핑할 주요 테이블들 식별
3. **프로토타입**: 간단한 매핑 시나리오로 POC 개발
4. **점진적 확장**: 기본 → 고급 기능 순서로 개발

이 설계서를 바탕으로 단계별로 구현해 나가면 됩니다. 어떤 부분부터 시작하고 싶으신가요?