From 1b800d44983da47119e775ce834a90d9e3c0b907 Mon Sep 17 00:00:00 2001
From: hyeonsu <hyeonsu@wace.me>
Date: Wed, 17 Sep 2025 10:07:57 +0900
Subject: [PATCH] =?UTF-8?q?=EC=99=B8=EB=B6=80=20=ED=98=B8=EC=B6=9C=20?=
 =?UTF-8?q?=EA=B8=B0=EB=8A=A5=20=EA=B5=AC=ED=98=84=20=EA=B3=84=ED=9A=8D?=
 =?UTF-8?q?=EC=84=9C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/external-call-implementation-plan.md | 604 ++++++++++++++++++++++
 1 file changed, 604 insertions(+)
 create mode 100644 docs/external-call-implementation-plan.md

diff --git a/docs/external-call-implementation-plan.md b/docs/external-call-implementation-plan.md
new file mode 100644
index 00000000..276e4f19
--- /dev/null
+++ b/docs/external-call-implementation-plan.md
@@ -0,0 +1,604 @@
+# 외부 호출 기능 구현 계획서
+
+## 📋 개요
+
+데이터플로우 다이어그램에서 외부 시스템 호출 기능을 구현하여, 데이터 처리 완료 시 다양한 외부 서비스로 알림이나 데이터를 전송할 수 있도록 합니다.
+
+## 🎯 목표
+
+1. **무료/저렴한 알림 방법** 우선 구현
+2. **확장 가능한 구조** 설계
+3. **사용자 친화적 UI** 제공
+4. **안정적인 오류 처리** 구현
+
+---
+
+## 🚀 Phase 1: 기본 외부 호출 기능 (무료)
+
+### 1.1 REST API 호출 🚧
+
+**현재 상태**: UI만 구현됨 (실제 호출 기능 없음)
+
+- ✅ 설정 UI: HTTP 메서드, 헤더, 페이로드 입력 가능
+- ❌ 실제 HTTP 요청 전송 기능 없음
+- ❌ 백엔드 서비스 구현 필요
+
+### 1.2 웹훅 호출 🚧
+
+**현재 상태**: UI만 구현됨 (실제 호출 기능 없음)
+
+- ✅ 설정 UI: 웹훅 URL 입력 가능
+- ❌ 실제 웹훅 전송 기능 없음
+- ❌ 백엔드 서비스 구현 필요
+
+### 1.3 이메일 알림 🔄
+
+**현재 상태**: Java 기반 구현됨 (Node.js 연동 필요)
+
+- ✅ Java MailUtil 클래스 구현됨
+- ✅ SMTP 설정 및 발송 기능 있음
+- ❌ 데이터플로우와 연동 안됨
+
+### 1.4 통합된 REST API 호출 시스템 🆕
+
+**새로운 중첩 드롭다운 구조로 개선**
+
+- **1단계**: 호출 유형 (`REST API 호출`, `이메일 전송`, `FTP 업로드`)
+- **2단계**: REST API 세부 종류 (`슬랙`, `카카오톡`, `디스코드`, `기타`)
+- **3단계**: 각 종류별 맞춤 설정 UI
+
+```typescript
+// ExternalCallService.ts - 통합 구조
+class ExternalCallService {
+  // 공통 REST API 호출 메서드
+  private async callRestApi(config: RestApiConfig) {
+    return await fetch(config.url, {
+      method: config.method,
+      headers: config.headers,
+      body: config.body,
+    });
+  }
+
+  // 슬랙 (REST API의 특수 케이스)
+  async sendSlackMessage(settings: SlackSettings) {
+    return await this.callRestApi({
+      url: settings.slackWebhookUrl,
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        text: settings.slackMessage,
+        channel: settings.slackChannel,
+      }),
+    });
+  }
+
+  // 카카오톡 (REST API의 특수 케이스)
+  async sendKakaoTalk(settings: KakaoSettings) {
+    return await this.callRestApi({
+      url: "https://kapi.kakao.com/v2/api/talk/memo/default/send",
+      method: "POST",
+      headers: { Authorization: `Bearer ${settings.kakaoAccessToken}` },
+      body: this.buildKakaoBody(settings.kakaoMessage),
+    });
+  }
+
+  // 일반 API (사용자 정의)
+  async callGenericApi(settings: GenericApiSettings) {
+    return await this.callRestApi({
+      url: settings.apiUrl,
+      method: settings.httpMethod,
+      headers: JSON.parse(settings.headers || "{}"),
+      body: settings.bodyTemplate,
+    });
+  }
+}
+```
+
+---
+
+## 🔧 Phase 2: UI/UX 개선
+
+### 2.1 중첩 드롭다운 구조로 외부 호출 타입 개선
+
+**파일**: `frontend/types/connectionTypes.ts`
+
+```typescript
+export interface ExternalCallSettings {
+  callType: "rest-api" | "email" | "ftp" | "queue";
+
+  // REST API 세부 종류 (중첩 드롭다운)
+  apiType?: "slack" | "kakao-talk" | "discord" | "generic";
+
+  // 일반 REST API 설정 (기타 선택 시)
+  apiUrl?: string;
+  httpMethod?: "GET" | "POST" | "PUT" | "DELETE";
+  headers?: string;
+  bodyTemplate?: string;
+
+  // 슬랙 전용 설정
+  slackWebhookUrl?: string;
+  slackChannel?: string;
+  slackMessage?: string;
+
+  // 카카오톡 전용 설정
+  kakaoAccessToken?: string;
+  kakaoMessage?: string;
+
+  // 디스코드 전용 설정
+  discordWebhookUrl?: string;
+  discordMessage?: string;
+
+  // 이메일 설정
+  smtpHost?: string;
+  smtpPort?: number;
+  smtpUser?: string;
+  smtpPass?: string;
+  fromEmail?: string;
+  toEmail?: string;
+  subject?: string;
+  emailBody?: string;
+}
+```
+
+#### **중첩 드롭다운 구조**:
+
+1. **1단계**: 호출 유형 선택 (`REST API 호출`, `이메일 전송`, `FTP 업로드`, `메시지 큐`)
+2. **2단계**: REST API 세부 종류 선택 (`슬랙`, `카카오톡`, `디스코드`, `기타`)
+3. **3단계**: 각 종류별 맞춤 설정 UI 표시
+
+### 2.2 중첩 드롭다운 UI 구현
+
+**파일**: `frontend/components/dataflow/connection/ExternalCallSettings.tsx`
+
+#### 1단계: 호출 유형 선택
+
+```tsx
+<Select
+  value={settings.callType}
+  onValueChange={(value) => onSettingsChange({ ...settings, callType: value })}
+>
+  <SelectContent>
+    <SelectItem value="rest-api">REST API 호출</SelectItem>
+    <SelectItem value="email">이메일 전송</SelectItem>
+    <SelectItem value="ftp">FTP 업로드</SelectItem>
+    <SelectItem value="queue">메시지 큐</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+#### 2단계: REST API 세부 종류 선택
+
+```tsx
+{
+  settings.callType === "rest-api" && (
+    <Select
+      value={settings.apiType || "generic"}
+      onValueChange={(value) =>
+        onSettingsChange({ ...settings, apiType: value })
+      }
+    >
+      <SelectContent>
+        <SelectItem value="slack">슬랙</SelectItem>
+        <SelectItem value="kakao-talk">카카오톡</SelectItem>
+        <SelectItem value="discord">디스코드</SelectItem>
+        <SelectItem value="generic">기타 (일반 API)</SelectItem>
+      </SelectContent>
+    </Select>
+  );
+}
+```
+
+#### 3단계: 각 종류별 맞춤 설정
+
+```tsx
+{
+  /* 슬랙 설정 */
+}
+{
+  settings.apiType === "slack" && (
+    <>
+      <Input placeholder="https://hooks.slack.com/services/..." />
+      <Input placeholder="#general" />
+      <Textarea placeholder="데이터 처리 완료! {{recordCount}}건" />
+    </>
+  );
+}
+
+{
+  /* 카카오톡 설정 */
+}
+{
+  settings.apiType === "kakao-talk" && (
+    <>
+      <Input type="password" placeholder="카카오 액세스 토큰" />
+      <Textarea placeholder="처리 완료! 총 {{recordCount}}건 처리되었습니다." />
+    </>
+  );
+}
+
+{
+  /* 기타 API 설정 */
+}
+{
+  settings.apiType === "generic" && (
+    <>
+      <Input placeholder="https://api.example.com/webhook" />
+      <Select placeholder="HTTP Method" />
+      <Textarea placeholder="Headers (JSON)" />
+      <Textarea placeholder="Body Template" />
+    </>
+  );
+}
+```
+
+---
+
+## 📱 Phase 3: 메신저 통합 (유료)
+
+### 3.1 SMS 발송
+
+**예상 비용**: 15~20원/건
+**추천 서비스**:
+
+- NHN Toast SMS
+- 네이버 클라우드 SMS
+- 알리고 SMS
+
+```typescript
+// SMS 설정 타입
+interface SMSSettings {
+  provider: "toast" | "naver" | "aligo";
+  apiKey: string;
+  secretKey: string;
+  fromNumber: string;
+  toNumber: string;
+  message: string;
+}
+```
+
+### 3.2 카카오톡 알림톡
+
+**예상 비용**: 15~25원/건
+**필요 사항**:
+
+- 카카오톡 비즈니스 계정
+- 알림톡 템플릿 등록
+- 카카오톡 비즈니스 API 연동
+
+```typescript
+// 카카오톡 설정 타입
+interface KakaoTalkSettings {
+  apiKey: string;
+  templateCode: string;
+  phoneNumber: string;
+  templateParams: Record<string, string>;
+}
+```
+
+---
+
+## 🛠️ Phase 4: 고급 기능
+
+### 4.1 재시도 메커니즘
+
+```typescript
+interface RetryConfig {
+  maxRetries: number;
+  retryDelay: number; // ms
+  backoffMultiplier: number;
+}
+
+// ExternalCallService에서 구현
+async executeWithRetry(callFunction: () => Promise<any>, config: RetryConfig) {
+  let lastError: Error;
+
+  for (let attempt = 1; attempt <= config.maxRetries; attempt++) {
+    try {
+      return await callFunction();
+    } catch (error) {
+      lastError = error as Error;
+      if (attempt < config.maxRetries) {
+        await new Promise(resolve =>
+          setTimeout(resolve, config.retryDelay * Math.pow(config.backoffMultiplier, attempt - 1))
+        );
+      }
+    }
+  }
+
+  throw lastError!;
+}
+```
+
+### 4.2 호출 로그 및 모니터링
+
+```sql
+-- 외부 호출 로그 테이블
+CREATE TABLE external_call_logs (
+  id SERIAL PRIMARY KEY,
+  diagram_id INTEGER REFERENCES dataflow_diagrams(diagram_id),
+  relationship_id VARCHAR(255),
+  call_type VARCHAR(50),
+  target_url VARCHAR(500),
+  request_payload TEXT,
+  response_status INTEGER,
+  response_body TEXT,
+  error_message TEXT,
+  execution_time_ms INTEGER,
+  created_at TIMESTAMP DEFAULT NOW()
+);
+```
+
+### 4.3 조건부 호출
+
+```typescript
+// 특정 조건에서만 외부 호출 실행
+interface ConditionalCall {
+  condition: string; // "recordCount > 100"
+  callSettings: ExternalCallSettings;
+}
+```
+
+---
+
+## 📊 구현 우선순위
+
+### 🥇 **High Priority (즉시 구현)**
+
+1. 🚧 **ExternalCallService 생성** - 백엔드 서비스 기반 구축
+2. 🆕 **슬랙 웹훅 구현** - 가장 간단하고 테스트하기 쉬움
+3. 🔄 **REST API 호출 완성** - UI는 있으나 실제 기능 없음
+4. 🔄 **웹훅 호출 완성** - UI는 있으나 실제 기능 없음
+5. 🔄 **이메일 연동** - Java MailUtil을 Node.js에서 호출
+6. 🔄 **디스코드 웹훅 추가** - 슬랙과 유사한 구조
+
+### 🥈 **Medium Priority (1-2주 후)**
+
+7. 🔄 재시도 메커니즘
+8. 🔄 호출 로그 시스템
+9. 🔄 오류 처리 개선
+10. 🔄 템플릿 변수 확장
+
+### 🥉 **Low Priority (필요시)**
+
+11. 🔄 SMS 발송
+12. 🔄 카카오톡 알림톡
+13. 🔄 조건부 호출
+14. 🔄 배치 호출
+
+---
+
+## 🔧 기술적 구현 세부사항
+
+### 백엔드 수정사항
+
+#### 1. ExternalCallService 확장
+
+**파일**: `backend-node/src/services/externalCallService.ts`
+
+```typescript
+// 슬랙 웹훅 메서드 추가
+async sendSlackMessage(settings: SlackSettings): Promise<boolean> {
+  const payload = {
+    text: this.processTemplate(settings.message, settings.templateData),
+    channel: settings.channel,
+    username: settings.username || "DataFlow Bot",
+    icon_emoji: settings.iconEmoji || ":robot_face:"
+  };
+
+  const response = await fetch(settings.webhookUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload)
+  });
+
+  return response.ok;
+}
+```
+
+#### 2. 데이터베이스 스키마 확장 (선택사항)
+
+```sql
+-- 외부 호출 설정을 별도 테이블로 관리 (대용량 처리 시)
+CREATE TABLE external_call_configs (
+  id SERIAL PRIMARY KEY,
+  diagram_id INTEGER REFERENCES dataflow_diagrams(diagram_id),
+  relationship_id VARCHAR(255),
+  call_type VARCHAR(50),
+  config_data JSONB,
+  is_active BOOLEAN DEFAULT true,
+  created_at TIMESTAMP DEFAULT NOW()
+);
+
+-- 인덱스
+CREATE INDEX idx_external_calls_diagram ON external_call_configs(diagram_id);
+CREATE INDEX idx_external_calls_relationship ON external_call_configs(relationship_id);
+```
+
+### 프론트엔드 수정사항
+
+#### 1. 타입 정의 확장
+
+**파일**: `frontend/types/connectionTypes.ts`
+
+- SlackSettings, DiscordSettings 인터페이스 추가
+- ExternalCallSettings 확장
+
+#### 2. UI 컴포넌트 확장
+
+**파일**: `frontend/components/dataflow/connection/ExternalCallSettings.tsx`
+
+- 슬랙, 디스코드 설정 UI 추가
+- 템플릿 변수 도움말 추가
+- 실시간 미리보기 기능
+
+#### 3. 유효성 검사 강화
+
+**파일**: `frontend/components/dataflow/ConnectionSetupModal.tsx`
+
+```typescript
+const validateExternalCallSettings = (
+  settings: ExternalCallSettings
+): boolean => {
+  if (settings.callType === "rest-api") {
+    switch (settings.apiType) {
+      case "slack":
+        return !!(settings.slackWebhookUrl && settings.slackMessage);
+      case "kakao-talk":
+        return !!(settings.kakaoAccessToken && settings.kakaoMessage);
+      case "discord":
+        return !!(settings.discordWebhookUrl && settings.discordMessage);
+      case "generic":
+        return !!(settings.apiUrl && settings.httpMethod);
+      default:
+        return false;
+    }
+  } else if (settings.callType === "email") {
+    return !!(settings.toEmail && settings.subject && settings.emailBody);
+  }
+  return true;
+};
+```
+
+---
+
+## 📈 성능 고려사항
+
+### 1. 비동기 처리
+
+- 외부 호출을 메인 데이터 처리와 분리
+- 큐 시스템 도입 (Redis/Bull Queue)
+
+### 2. 타임아웃 설정
+
+```typescript
+const EXTERNAL_CALL_TIMEOUT = {
+  "rest-api": 30000, // 30초
+  webhook: 10000, // 10초
+  email: 60000, // 60초
+  slack: 15000, // 15초
+};
+```
+
+### 3. 호출 제한
+
+```typescript
+// 레이트 리미팅
+const RATE_LIMITS = {
+  slack: { requests: 1, per: 1000 }, // 1초당 1회
+  email: { requests: 10, per: 60000 }, // 1분당 10회
+  "rest-api": { requests: 100, per: 60000 }, // 1분당 100회
+};
+```
+
+---
+
+## 🔒 보안 고려사항
+
+### 1. API 키 관리
+
+- 환경변수로 민감 정보 관리
+- 데이터베이스 암호화 저장
+- API 키 순환 정책
+
+### 2. 입력값 검증
+
+```typescript
+// 웹훅 URL 화이트리스트
+const ALLOWED_WEBHOOK_DOMAINS = [
+  "hooks.slack.com",
+  "discord.com",
+  "outlook.office365.com",
+];
+
+const validateWebhookUrl = (url: string): boolean => {
+  try {
+    const parsed = new URL(url);
+    return ALLOWED_WEBHOOK_DOMAINS.some((domain) =>
+      parsed.hostname.endsWith(domain)
+    );
+  } catch {
+    return false;
+  }
+};
+```
+
+### 3. 로깅 및 감사
+
+- 모든 외부 호출 로깅
+- 실패 원인 추적
+- 사용량 모니터링
+
+---
+
+## 📚 참고 자료
+
+### API 문서
+
+- [Slack Webhooks](https://api.slack.com/messaging/webhooks)
+- [Discord Webhooks](https://discord.com/developers/docs/resources/webhook)
+- [Microsoft Teams Webhooks](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook)
+
+### SMS/카카오톡 서비스
+
+- [NHN Toast SMS](https://docs.toast.com/ko/Notification/SMS/ko/api-guide/)
+- [네이버 클라우드 SMS](https://api.ncloud-docs.com/docs/ai-application-service-sens-smsv2)
+- [카카오톡 비즈니스 API](https://developers.kakao.com/docs/latest/ko/message/common)
+
+---
+
+## 📅 일정
+
+### Week 1
+
+- [ ] 슬랙 웹훅 구현
+- [ ] 디스코드 웹훅 구현
+- [ ] UI 컴포넌트 확장
+
+### Week 2
+
+- [ ] 재시도 메커니즘 구현
+- [ ] 호출 로그 시스템 구현
+- [ ] 테스트 코드 작성
+
+### Week 3
+
+- [ ] SMS 발송 구현 (선택)
+- [ ] 성능 최적화
+- [ ] 문서화 완성
+
+### Week 4
+
+- [ ] 카카오톡 알림톡 구현 (선택)
+- [ ] 최종 테스트 및 배포
+
+---
+
+## ✅ 체크리스트
+
+### 개발 완료 체크
+
+#### 🚧 **현재 상태 (실제)**
+
+- [x] **중첩 드롭다운 UI 구현** (호출 유형 → API 종류 → 맞춤 설정)
+- [x] **타입 정의 개선** (REST API 세부 분류 지원)
+- [ ] **ExternalCallService 백엔드 서비스 생성** ← 최우선!
+- [ ] 실제 HTTP 요청/웹훅 전송 기능
+- [ ] 데이터플로우 실행 시 외부 호출 트리거
+- [ ] 슬랙 웹훅 구현 (REST API 방식)
+- [ ] 카카오톡 API 호출 구현 (REST API 방식)
+- [ ] 디스코드 웹훅 구현 (REST API 방식)
+- [ ] 일반 REST API 호출 구현
+- [ ] 이메일 발송 연동 (Java → Node.js)
+- [ ] 오류 처리 및 재시도 메커니즘
+
+### 배포 준비 체크
+
+- [ ] 환경변수 설정
+- [ ] 데이터베이스 마이그레이션
+- [ ] 로그 시스템 설정
+- [ ] 모니터링 설정
+- [ ] 백업 계획 수립
+
+---
+
+이 계획서를 바탕으로 단계별로 구현해나가면 안정적이고 확장 가능한 외부 호출 시스템을 구축할 수 있을 것입니다! 🚀