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 테이블 확장

ALTER TABLE external_call_configs ADD COLUMN IF NOT EXISTS data_mapping_config JSONB;

4.2 data_mapping_config JSON 구조

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

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

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

5.2 FieldMappingEditor.tsx

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

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

5.3 DataTransformEditor.tsx

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

6. 백엔드 서비스 확장

6.1 ExternalCallExecutor 확장

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 (신규)

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. 점진적 확장: 기본 → 고급 기능 순서로 개발

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