# 🌐 제어관리 외부호출 REST API 기능 구현 계획서

## 📋 프로젝트 개요

### 목적

제어관리 시스템에서 관계 생성 시 연결타입으로 "외부호출"을 선택하면 REST API 호출 기능을 설정할 수 있도록 구현합니다.

### 현재 상황 분석

#### 기존 연결타입 구조

- **데이터 저장**: INSERT/UPDATE/DELETE 작업 지원
- **외부 호출**: 기본 구조는 있으나 REST API 전용 설정 UI 필요

#### 기존 외부호출 기능

- `ExternalCallSettings.tsx`: 복합적인 외부호출 설정 (REST API, 이메일, FTP, 큐)
- `SimpleExternalCallSettings.tsx`: 기존 설정을 재사용하는 단순화된 버전
- `ExternalCallAPI`: REST API 테스트/실행 기능 완료
- `ExternalCallService`: 백엔드 로직 완료

## 🎯 구현 목표

### 1단계: REST API 전용 설정 컴포넌트 개발

기존 복합 설정에서 REST API 부분만 추출하여 전용 컴포넌트 생성

### 2단계: 연결타입 선택 시 REST API 설정 연동

ConnectionTypeSelector에서 "외부호출" 선택 시 REST API 설정 패널 표시

### 3단계: 설정 저장 및 실행 로직 연동

관계 데이터에 REST API 설정 저장 및 실행 시점 연동

## 🏗️ 시스템 아키텍처 설계

### 1. 분리된 외부호출 컴포넌트 구조

#### 🔄 설계 철학: 완전 분리형 아키텍처

기존 데이터 저장 기능과 완전히 독립된 외부호출 전용 컴포넌트들을 구성하여 각각의 책임을 명확히 분리합니다.

#### ExternalCallPanel.tsx (신규 생성 - 메인 패널)

```typescript
interface ExternalCallPanelProps {
  relationshipId: string;
  onSettingsChange: (settings: ExternalCallConfig) => void;
  initialSettings?: ExternalCallConfig;
}

// 외부호출 전용 설정 구조
interface ExternalCallConfig {
  callType: "rest-api"; // 향후 확장 가능
  restApiSettings: RestApiSettings;
}
```

#### RestApiSettings.tsx (신규 생성 - REST API 전용)

```typescript
interface RestApiSettingsProps {
  settings: RestApiSettings;
  onSettingsChange: (settings: RestApiSettings) => void;
}

interface RestApiSettings {
  apiUrl: string;
  httpMethod: "GET" | "POST" | "PUT" | "DELETE";
  headers: Record<string, string>;
  bodyTemplate: string;
  authentication?: {
    type: "none" | "bearer" | "basic" | "api-key";
    token?: string;
    username?: string;
    password?: string;
    apiKey?: string;
    apiKeyHeader?: string;
  };
  timeout?: number;
  retryCount?: number;
}
```

#### ExternalCallTestPanel.tsx (신규 생성 - 테스트 전용)

```typescript
interface ExternalCallTestPanelProps {
  settings: RestApiSettings;
  onTestResult: (result: TestResult) => void;
}
```

#### 주요 기능

- **URL 설정**: API 엔드포인트 URL 입력
- **HTTP 메서드**: GET, POST, PUT, DELETE 선택
- **헤더 설정**: Content-Type, Authorization 등 커스텀 헤더
- **바디 템플릿**: POST/PUT 요청 시 JSON 바디 템플릿
- **인증 설정**: Bearer Token, Basic Auth, API Key 지원
- **고급 설정**: 타임아웃, 재시도 횟수
- **테스트 기능**: 설정한 API 실제 호출 테스트

### 2. 연결타입 선택 플로우 개선

#### ConnectionTypeSelector 수정

```typescript
// 기존 코드 유지, 외부호출 선택 시 이벤트 처리만 추가
const connectionTypes: ConnectionType[] = [
  {
    id: "data_save",
    label: "데이터 저장",
    description: "INSERT/UPDATE/DELETE 작업",
    icon: <Database className="h-4 w-4" />,
  },
  {
    id: "external_call",
    label: "외부 호출",
    description: "REST API 호출", // 설명 업데이트
    icon: <Globe className="h-4 w-4" />,
  },
];
```

#### ConnectionSetupModal 수정

```typescript
// 외부호출 선택 시 완전 분리된 ExternalCallPanel 표시
{
  selectedConnectionType === "external_call" && (
    <ExternalCallPanel
      relationshipId={relationshipId}
      initialSettings={externalCallConfig}
      onSettingsChange={setExternalCallConfig}
    />
  );
}

// 데이터 저장 선택 시 기존 DataSavePanel 표시
{
  selectedConnectionType === "data_save" && (
    <DataSavePanel
      relationshipId={relationshipId}
      initialSettings={dataSaveConfig}
      onSettingsChange={setDataSaveConfig}
    />
  );
}
```

### 3. 데이터 구조 확장

#### 관계 데이터 스키마 확장

```sql
-- relationships 테이블에 rest_api_settings 컬럼 추가 (JSON 타입)
ALTER TABLE relationships
ADD COLUMN rest_api_settings JSONB;

-- 인덱스 추가 (성능 최적화)
CREATE INDEX idx_relationships_rest_api_settings
ON relationships USING GIN (rest_api_settings);
```

#### TypeScript 타입 정의

```typescript
// types/connectionTypes.ts 확장
export interface RelationshipData {
  id: string;
  sourceNodeId: string;
  targetNodeId: string;
  connectionType: "data_save" | "external_call";

  // 기존 필드들...
  dataSaveSettings?: DataSaveSettings;

  // 새로 추가
  restApiSettings?: RestApiSettings;
}
```

## 📱 UI/UX 설계

### 1. REST API 설정 패널 레이아웃

```
┌─────────────────────────────────────────────────────────┐
│ 🌐 REST API 설정                           [테스트] 버튼 │
├─────────────────────────────────────────────────────────┤
│ API URL                                                 │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ https://api.example.com/webhook                     │ │
│ └─────────────────────────────────────────────────────┘ │
│                                                         │
│ HTTP 메서드        │ 인증 방식                          │
│ ┌─────────────┐   │ ┌─────────────────────────────────┐ │
│ │ POST ▼      │   │ │ Bearer Token ▼                  │ │
│ └─────────────┘   │ └─────────────────────────────────┘ │
│                                                         │
│ 헤더 설정                                               │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Content-Type: application/json                      │ │
│ │ Authorization: Bearer {token}                       │ │
│ └─────────────────────────────────────────────────────┘ │
│                                                         │
│ 요청 바디 템플릿                                        │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ {                                                   │ │
│ │   "message": "{{message}}",                         │ │
│ │   "data": {{sourceData}},                           │ │
│ │   "timestamp": "{{timestamp}}"                      │ │
│ │ }                                                   │ │
│ └─────────────────────────────────────────────────────┘ │
│                                                         │
│ 고급 설정                                               │
│ 타임아웃: [30] 초    재시도: [3] 회                     │
└─────────────────────────────────────────────────────────┘
```

### 2. 템플릿 변수 지원

#### 사용 가능한 템플릿 변수

- `{{sourceData}}`: 소스 노드의 전체 데이터
- `{{targetData}}`: 타겟 노드의 데이터 (있는 경우)
- `{{timestamp}}`: 현재 타임스탬프
- `{{relationshipId}}`: 관계 ID
- `{{diagramId}}`: 다이어그램 ID
- `{{userId}}`: 현재 사용자 ID

#### 템플릿 도우미 UI

```typescript
const TemplateHelper = () => (
  <div className="text-xs text-gray-600 mt-2">
    <details>
      <summary className="cursor-pointer">사용 가능한 템플릿 변수</summary>
      <div className="mt-2 space-y-1">
        <div>
          <code>{"{{sourceData}}"}</code> - 소스 노드 데이터
        </div>
        <div>
          <code>{"{{timestamp}}"}</code> - 현재 시간
        </div>
        <div>
          <code>{"{{relationshipId}}"}</code> - 관계 ID
        </div>
      </div>
    </details>
  </div>
);
```

## 🔧 구현 단계별 계획

### Phase 1: 기본 REST API 설정 컴포넌트 (1-2일)

#### 1.1 분리된 컴포넌트 구조 생성

- [ ] **ExternalCallPanel.tsx**: 외부호출 메인 패널 컴포넌트
- [ ] **RestApiSettings.tsx**: REST API 전용 설정 컴포넌트
- [ ] **ExternalCallTestPanel.tsx**: API 테스트 전용 컴포넌트
- [ ] **외부호출 전용 디렉토리**: `components/dataflow/external-call/` 생성

#### 1.2 타입 정의 분리

- [ ] **ExternalCallTypes.ts**: 외부호출 전용 타입 정의 파일 생성
- [ ] **RestApiTypes.ts**: REST API 전용 타입 정의
- [ ] 기존 `connectionTypes.ts`와 완전 분리하여 독립성 확보

### Phase 2: 연결타입 선택 연동 (1일)

#### 2.1 ConnectionSetupModal 수정

- [ ] 외부호출 선택 시 RestApiSettings 컴포넌트 표시
- [ ] 상태 관리 로직 추가
- [ ] 설정 저장/불러오기 연동

#### 2.2 ConnectionTypeSelector 설명 업데이트

- [ ] 외부호출 설명을 "REST API 호출"로 명확화

### Phase 3: 인증 및 고급 기능 (2-3일)

#### 3.1 인증 방식 지원

- [ ] Bearer Token 인증
- [ ] Basic Authentication
- [ ] API Key 인증 (헤더/쿼리 파라미터)
- [ ] 인증 정보 암호화 저장

#### 3.2 고급 설정

- [ ] 타임아웃 설정
- [ ] 재시도 로직
- [ ] 응답 검증 규칙

### Phase 4: 테스트 및 실행 기능 (1-2일)

#### 4.1 테스트 기능 구현

- [ ] 설정한 API 실제 호출 테스트
- [ ] 응답 결과 표시
- [ ] 오류 메시지 상세 표시

#### 4.2 실행 로직 연동

- [ ] 관계 실행 시 REST API 호출
- [ ] 템플릿 변수 치환
- [ ] 실행 결과 로깅

### Phase 5: 템플릿 시스템 고도화 (2-3일)

#### 5.1 템플릿 변수 확장

- [ ] 소스/타겟 데이터 접근
- [ ] 조건부 템플릿 (if/else)
- [ ] 반복 템플릿 (for loop)

#### 5.2 템플릿 에디터 개선

- [ ] 문법 하이라이팅
- [ ] 자동완성
- [ ] 실시간 미리보기

### Phase 6: 데이터베이스 및 백엔드 연동 (1일)

#### 6.1 데이터베이스 스키마 업데이트

- [ ] relationships 테이블에 rest_api_settings 컬럼 추가
- [ ] 마이그레이션 스크립트 작성

#### 6.2 백엔드 API 수정

- [ ] 관계 저장 시 REST API 설정 저장
- [ ] 관계 실행 시 REST API 호출 로직

## 🧪 테스트 계획

### 1. 단위 테스트

- [ ] RestApiSettings 컴포넌트 렌더링 테스트
- [ ] 입력값 검증 로직 테스트
- [ ] 템플릿 변수 치환 테스트

### 2. 통합 테스트

- [ ] 연결타입 선택 → REST API 설정 플로우
- [ ] 설정 저장 → 불러오기 테스트
- [ ] API 호출 → 응답 처리 테스트

### 3. E2E 테스트

- [ ] 전체 관계 생성 → 실행 플로우
- [ ] 다양한 API 서비스와의 연동 테스트
- [ ] 오류 상황 처리 테스트

## 🔒 보안 고려사항

### 1. 인증 정보 보호

- [ ] API 키, 토큰 등 민감 정보 암호화 저장
- [ ] 프론트엔드에서 민감 정보 마스킹 표시
- [ ] 로그에 민감 정보 노출 방지

### 2. API 호출 제한

- [ ] 호출 빈도 제한 (Rate Limiting)
- [ ] 허용된 도메인만 호출 가능하도록 제한
- [ ] 타임아웃 설정으로 무한 대기 방지

### 3. 입력값 검증

- [ ] URL 형식 검증
- [ ] JSON 템플릿 문법 검증
- [ ] XSS, 인젝션 공격 방지

## 📊 성능 최적화

### 1. 프론트엔드 최적화

- [ ] 컴포넌트 지연 로딩 (Lazy Loading)
- [ ] 설정 변경 시 디바운싱 적용
- [ ] 메모이제이션으로 불필요한 리렌더링 방지

### 2. 백엔드 최적화

- [ ] API 호출 결과 캐싱
- [ ] 비동기 처리로 응답 시간 단축
- [ ] 연결 풀링으로 리소스 효율화

## 🚀 배포 및 모니터링

### 1. 배포 전략

- [ ] 기능 플래그로 점진적 배포
- [ ] A/B 테스트로 사용성 검증
- [ ] 롤백 계획 수립

### 2. 모니터링

- [ ] API 호출 성공/실패율 모니터링
- [ ] 응답 시간 추적
- [ ] 오류 로그 수집 및 알림

## 📝 문서화

### 1. 사용자 가이드

- [ ] REST API 설정 방법 가이드
- [ ] 템플릿 변수 사용법
- [ ] 일반적인 API 연동 예제

### 2. 개발자 문서

- [ ] 컴포넌트 API 문서
- [ ] 백엔드 API 명세
- [ ] 확장 가이드

## 🎯 성공 지표

### 1. 기능적 지표

- [ ] REST API 설정 완료율 > 95%
- [ ] API 호출 성공률 > 98%
- [ ] 설정 저장/불러오기 성공률 > 99%

### 2. 사용성 지표

- [ ] 설정 완료 시간 < 5분
- [ ] 사용자 만족도 > 4.0/5.0
- [ ] 지원 요청 감소율 > 30%

## 📅 일정 계획

| 단계        | 기간       | 주요 작업                          |
| ----------- | ---------- | ---------------------------------- |
| Phase 1     | 1-2일      | RestApiSettings 컴포넌트 기본 구현 |
| Phase 2     | 1일        | 연결타입 선택 연동                 |
| Phase 3     | 2-3일      | 인증 및 고급 기능                  |
| Phase 4     | 1-2일      | 테스트 및 실행 기능                |
| Phase 5     | 2-3일      | 템플릿 시스템 고도화               |
| Phase 6     | 1일        | 데이터베이스 및 백엔드 연동        |
| **총 기간** | **8-12일** | **전체 기능 완성**                 |

## 🔄 향후 확장 계획

### 1. 추가 프로토콜 지원

- [ ] GraphQL API 지원
- [ ] WebSocket 연결
- [ ] gRPC 호출

### 2. 고급 기능

- [ ] API 응답 기반 조건부 실행
- [ ] 여러 API 순차/병렬 호출
- [ ] API 응답 데이터 파싱 및 저장

### 3. 통합 기능

- [ ] 외부 API 문서 자동 가져오기
- [ ] Postman 컬렉션 임포트
- [ ] OpenAPI 스펙 지원

---

이 계획서를 바탕으로 단계별로 구현을 진행하면 안정적이고 사용자 친화적인 REST API 외부호출 기능을 완성할 수 있습니다.