ERP-node/PHASE_EXTERNAL_CONNECTION_REST_API_ENHANCEMENT.md

# 외부 커넥션 관리 REST API 지원 확장 계획서

## 📋 프로젝트 개요

### 목적

현재 외부 데이터베이스 연결만 관리하는 `/admin/external-connections` 페이지에 REST API 연결 관리 기능을 추가하여, DB와 REST API 커넥션을 통합 관리할 수 있도록 확장합니다.

### 현재 상황

- **기존 기능**: 외부 데이터베이스 연결 정보만 관리 (MySQL, PostgreSQL, Oracle, SQL Server, SQLite)
- **기존 테이블**: `external_db_connections` - DB 연결 정보 저장
- **기존 UI**: 단일 화면에서 DB 연결 목록 표시 및 CRUD 작업

### 요구사항

1. **탭 전환**: DB 연결 관리 ↔ REST API 연결 관리 간 탭 전환 UI
2. **REST API 관리**: 요청 주소별 헤더(키-값 쌍) 관리
3. **연결 테스트**: REST API 호출이 정상 작동하는지 테스트 기능

---

## 🗄️ 데이터베이스 설계

### 신규 테이블: `external_rest_api_connections`

```sql
CREATE TABLE external_rest_api_connections (
    id SERIAL PRIMARY KEY,

    -- 기본 정보
    connection_name VARCHAR(100) NOT NULL UNIQUE,
    description TEXT,

    -- REST API 연결 정보
    base_url VARCHAR(500) NOT NULL,              -- 기본 URL (예: https://api.example.com)
    default_headers JSONB DEFAULT '{}',          -- 기본 헤더 정보 (키-값 쌍)

    -- 인증 설정
    auth_type VARCHAR(20) DEFAULT 'none',        -- none, api-key, bearer, basic, oauth2
    auth_config JSONB,                           -- 인증 관련 설정

    -- 고급 설정
    timeout INTEGER DEFAULT 30000,               -- 요청 타임아웃 (ms)
    retry_count INTEGER DEFAULT 0,               -- 재시도 횟수
    retry_delay INTEGER DEFAULT 1000,            -- 재시도 간격 (ms)

    -- 관리 정보
    company_code VARCHAR(20) DEFAULT '*',
    is_active CHAR(1) DEFAULT 'Y',
    created_date TIMESTAMP DEFAULT NOW(),
    created_by VARCHAR(50),
    updated_date TIMESTAMP DEFAULT NOW(),
    updated_by VARCHAR(50),

    -- 테스트 정보
    last_test_date TIMESTAMP,
    last_test_result CHAR(1),                    -- Y: 성공, N: 실패
    last_test_message TEXT
);

-- 인덱스
CREATE INDEX idx_rest_api_connections_company ON external_rest_api_connections(company_code);
CREATE INDEX idx_rest_api_connections_active ON external_rest_api_connections(is_active);
CREATE INDEX idx_rest_api_connections_name ON external_rest_api_connections(connection_name);
```

### 샘플 데이터

```sql
INSERT INTO external_rest_api_connections (
    connection_name, description, base_url, default_headers, auth_type, auth_config
) VALUES
(
    '기상청 API',
    '기상청 공공데이터 API',
    'https://apis.data.go.kr/1360000/VilageFcstInfoService_2.0',
    '{"Content-Type": "application/json", "Accept": "application/json"}',
    'api-key',
    '{"keyLocation": "query", "keyName": "serviceKey", "keyValue": "your-api-key-here"}'
),
(
    '사내 인사 시스템 API',
    '인사정보 조회용 내부 API',
    'https://hr.company.com/api/v1',
    '{"Content-Type": "application/json"}',
    'bearer',
    '{"token": "your-bearer-token-here"}'
);
```

---

## 🔧 백엔드 구현

### 1. 타입 정의

```typescript
// backend-node/src/types/externalRestApiTypes.ts

export type AuthType = "none" | "api-key" | "bearer" | "basic" | "oauth2";

export interface ExternalRestApiConnection {
  id?: number;
  connection_name: string;
  description?: string;
  base_url: string;
  default_headers: Record<string, string>;
  auth_type: AuthType;
  auth_config?: {
    // API Key
    keyLocation?: "header" | "query";
    keyName?: string;
    keyValue?: string;

    // Bearer Token
    token?: string;

    // Basic Auth
    username?: string;
    password?: string;

    // OAuth2
    clientId?: string;
    clientSecret?: string;
    tokenUrl?: string;
    accessToken?: string;
  };
  timeout?: number;
  retry_count?: number;
  retry_delay?: number;
  company_code: string;
  is_active: string;
  created_date?: Date;
  created_by?: string;
  updated_date?: Date;
  updated_by?: string;
  last_test_date?: Date;
  last_test_result?: string;
  last_test_message?: string;
}

export interface ExternalRestApiConnectionFilter {
  auth_type?: string;
  is_active?: string;
  company_code?: string;
  search?: string;
}

export interface RestApiTestRequest {
  id?: number;
  base_url: string;
  endpoint?: string; // 테스트할 엔드포인트 (선택)
  method?: "GET" | "POST" | "PUT" | "DELETE";
  headers?: Record<string, string>;
  auth_type?: AuthType;
  auth_config?: any;
  timeout?: number;
}

export interface RestApiTestResult {
  success: boolean;
  message: string;
  response_time?: number;
  status_code?: number;
  response_data?: any;
  error_details?: string;
}
```

### 2. 서비스 계층

```typescript
// backend-node/src/services/externalRestApiConnectionService.ts

export class ExternalRestApiConnectionService {
  // CRUD 메서드
  static async getConnections(filter: ExternalRestApiConnectionFilter);
  static async getConnectionById(id: number);
  static async createConnection(data: ExternalRestApiConnection);
  static async updateConnection(
    id: number,
    data: Partial<ExternalRestApiConnection>
  );
  static async deleteConnection(id: number);

  // 테스트 메서드
  static async testConnection(
    testRequest: RestApiTestRequest
  ): Promise<RestApiTestResult>;
  static async testConnectionById(
    id: number,
    endpoint?: string
  ): Promise<RestApiTestResult>;

  // 헬퍼 메서드
  private static buildHeaders(
    connection: ExternalRestApiConnection
  ): Record<string, string>;
  private static validateConnectionData(data: ExternalRestApiConnection): void;
  private static encryptSensitiveData(authConfig: any): any;
  private static decryptSensitiveData(authConfig: any): any;
}
```

### 3. API 라우트

```typescript
// backend-node/src/routes/externalRestApiConnectionRoutes.ts

// GET    /api/external-rest-api-connections          - 목록 조회
// GET    /api/external-rest-api-connections/:id      - 상세 조회
// POST   /api/external-rest-api-connections          - 새 연결 생성
// PUT    /api/external-rest-api-connections/:id      - 연결 수정
// DELETE /api/external-rest-api-connections/:id      - 연결 삭제
// POST   /api/external-rest-api-connections/test     - 연결 테스트 (신규)
// POST   /api/external-rest-api-connections/:id/test - ID로 테스트 (기존 연결)
```

### 4. 연결 테스트 구현

```typescript
// REST API 연결 테스트 로직
static async testConnection(testRequest: RestApiTestRequest): Promise<RestApiTestResult> {
  const startTime = Date.now();

  try {
    // 헤더 구성
    const headers = { ...testRequest.headers };

    // 인증 헤더 추가
    if (testRequest.auth_type === 'bearer' && testRequest.auth_config?.token) {
      headers['Authorization'] = `Bearer ${testRequest.auth_config.token}`;
    } else if (testRequest.auth_type === 'basic') {
      const credentials = Buffer.from(
        `${testRequest.auth_config.username}:${testRequest.auth_config.password}`
      ).toString('base64');
      headers['Authorization'] = `Basic ${credentials}`;
    } else if (testRequest.auth_type === 'api-key') {
      if (testRequest.auth_config.keyLocation === 'header') {
        headers[testRequest.auth_config.keyName] = testRequest.auth_config.keyValue;
      }
    }

    // URL 구성
    let url = testRequest.base_url;
    if (testRequest.endpoint) {
      url = `${testRequest.base_url}${testRequest.endpoint}`;
    }

    // API Key가 쿼리에 있는 경우
    if (testRequest.auth_type === 'api-key' &&
        testRequest.auth_config.keyLocation === 'query') {
      const separator = url.includes('?') ? '&' : '?';
      url = `${url}${separator}${testRequest.auth_config.keyName}=${testRequest.auth_config.keyValue}`;
    }

    // HTTP 요청 실행
    const response = await fetch(url, {
      method: testRequest.method || 'GET',
      headers,
      signal: AbortSignal.timeout(testRequest.timeout || 30000),
    });

    const responseTime = Date.now() - startTime;
    const responseData = await response.json().catch(() => null);

    return {
      success: response.ok,
      message: response.ok ? '연결 성공' : `연결 실패 (${response.status})`,
      response_time: responseTime,
      status_code: response.status,
      response_data: responseData,
    };
  } catch (error) {
    return {
      success: false,
      message: '연결 실패',
      error_details: error instanceof Error ? error.message : '알 수 없는 오류',
    };
  }
}
```

---

## 🎨 프론트엔드 구현

### 1. 탭 구조 설계

```typescript
// frontend/app/(main)/admin/external-connections/page.tsx

type ConnectionTabType = "database" | "rest-api";

const [activeTab, setActiveTab] = useState<ConnectionTabType>("database");
```

### 2. 메인 페이지 구조 개선

```tsx
// 탭 헤더
<Tabs
  value={activeTab}
  onValueChange={(value) => setActiveTab(value as ConnectionTabType)}
>
  <TabsList className="grid w-[400px] grid-cols-2">
    <TabsTrigger value="database" className="flex items-center gap-2">
      <Database className="h-4 w-4" />
      데이터베이스 연결
    </TabsTrigger>
    <TabsTrigger value="rest-api" className="flex items-center gap-2">
      <Globe className="h-4 w-4" />
      REST API 연결
    </TabsTrigger>
  </TabsList>

  {/* 데이터베이스 연결 탭 */}
  <TabsContent value="database">
    <DatabaseConnectionList />
  </TabsContent>

  {/* REST API 연결 탭 */}
  <TabsContent value="rest-api">
    <RestApiConnectionList />
  </TabsContent>
</Tabs>
```

### 3. REST API 연결 목록 컴포넌트

```typescript
// frontend/components/admin/RestApiConnectionList.tsx

export function RestApiConnectionList() {
  const [connections, setConnections] = useState<ExternalRestApiConnection[]>(
    []
  );
  const [searchTerm, setSearchTerm] = useState("");
  const [authTypeFilter, setAuthTypeFilter] = useState("ALL");
  const [isModalOpen, setIsModalOpen] = useState(false);
  const [editingConnection, setEditingConnection] = useState<
    ExternalRestApiConnection | undefined
  >();

  // 테이블 컬럼:
  // - 연결명
  // - 기본 URL
  // - 인증 타입
  // - 헤더 수 (default_headers 개수)
  // - 상태 (활성/비활성)
  // - 마지막 테스트 (날짜 + 결과)
  // - 작업 (테스트/편집/삭제)
}
```

### 4. REST API 연결 설정 모달

```typescript
// frontend/components/admin/RestApiConnectionModal.tsx

export function RestApiConnectionModal({
  isOpen,
  onClose,
  onSave,
  connection,
}: RestApiConnectionModalProps) {
  // 섹션 구성:
  // 1. 기본 정보
  //    - 연결명 (필수)
  //    - 설명
  //    - 기본 URL (필수)
  // 2. 헤더 관리 (키-값 추가/삭제)
  //    - 동적 입력 필드
  //    - + 버튼으로 추가
  //    - 각 행에 삭제 버튼
  // 3. 인증 설정
  //    - 인증 타입 선택 (none/api-key/bearer/basic/oauth2)
  //    - 선택된 타입별 설정 필드 표시
  // 4. 고급 설정 (접기/펼치기)
  //    - 타임아웃
  //    - 재시도 설정
  // 5. 테스트 섹션
  //    - 테스트 엔드포인트 입력 (선택)
  //    - 테스트 실행 버튼
  //    - 테스트 결과 표시
}
```

### 5. 헤더 관리 컴포넌트

```typescript
// frontend/components/admin/HeadersManager.tsx

interface HeadersManagerProps {
  headers: Record<string, string>;
  onChange: (headers: Record<string, string>) => void;
}

export function HeadersManager({ headers, onChange }: HeadersManagerProps) {
  const [headersList, setHeadersList] = useState<
    Array<{ key: string; value: string }>
  >(Object.entries(headers).map(([key, value]) => ({ key, value })));

  const addHeader = () => {
    setHeadersList([...headersList, { key: "", value: "" }]);
  };

  const removeHeader = (index: number) => {
    const newList = headersList.filter((_, i) => i !== index);
    setHeadersList(newList);
    updateParent(newList);
  };

  const updateHeader = (
    index: number,
    field: "key" | "value",
    value: string
  ) => {
    const newList = [...headersList];
    newList[index][field] = value;
    setHeadersList(newList);
    updateParent(newList);
  };

  const updateParent = (list: Array<{ key: string; value: string }>) => {
    const headersObject = list.reduce((acc, { key, value }) => {
      if (key.trim()) acc[key] = value;
      return acc;
    }, {} as Record<string, string>);
    onChange(headersObject);
  };

  // UI: 테이블 형태로 키-값 입력 필드 표시
  // 각 행: [키 입력] [값 입력] [삭제 버튼]
  // 하단: [+ 헤더 추가] 버튼
}
```

### 6. 인증 설정 컴포넌트

```typescript
// frontend/components/admin/AuthenticationConfig.tsx

export function AuthenticationConfig({
  authType,
  authConfig,
  onChange,
}: AuthenticationConfigProps) {
  // authType에 따라 다른 입력 필드 표시
  // none: 추가 필드 없음
  // api-key:
  //   - 키 위치 (header/query)
  //   - 키 이름
  //   - 키 값
  // bearer:
  //   - 토큰 값
  // basic:
  //   - 사용자명
  //   - 비밀번호
  // oauth2:
  //   - Client ID
  //   - Client Secret
  //   - Token URL
  //   - Access Token (읽기전용, 자동 갱신)
}
```

### 7. API 클라이언트

```typescript
// frontend/lib/api/externalRestApiConnection.ts

export class ExternalRestApiConnectionAPI {
  private static readonly BASE_URL = "/api/external-rest-api-connections";

  static async getConnections(filter?: ExternalRestApiConnectionFilter) {
    const params = new URLSearchParams();
    if (filter?.search) params.append("search", filter.search);
    if (filter?.auth_type && filter.auth_type !== "ALL") {
      params.append("auth_type", filter.auth_type);
    }
    if (filter?.is_active && filter.is_active !== "ALL") {
      params.append("is_active", filter.is_active);
    }

    const response = await fetch(`${this.BASE_URL}?${params}`);
    return this.handleResponse(response);
  }

  static async getConnectionById(id: number) {
    const response = await fetch(`${this.BASE_URL}/${id}`);
    return this.handleResponse(response);
  }

  static async createConnection(data: ExternalRestApiConnection) {
    const response = await fetch(this.BASE_URL, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(data),
    });
    return this.handleResponse(response);
  }

  static async updateConnection(
    id: number,
    data: Partial<ExternalRestApiConnection>
  ) {
    const response = await fetch(`${this.BASE_URL}/${id}`, {
      method: "PUT",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(data),
    });
    return this.handleResponse(response);
  }

  static async deleteConnection(id: number) {
    const response = await fetch(`${this.BASE_URL}/${id}`, {
      method: "DELETE",
    });
    return this.handleResponse(response);
  }

  static async testConnection(
    testRequest: RestApiTestRequest
  ): Promise<RestApiTestResult> {
    const response = await fetch(`${this.BASE_URL}/test`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(testRequest),
    });
    return this.handleResponse(response);
  }

  static async testConnectionById(
    id: number,
    endpoint?: string
  ): Promise<RestApiTestResult> {
    const response = await fetch(`${this.BASE_URL}/${id}/test`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ endpoint }),
    });
    return this.handleResponse(response);
  }

  private static async handleResponse(response: Response) {
    if (!response.ok) {
      const error = await response.json().catch(() => ({}));
      throw new Error(error.message || "요청 실패");
    }
    return response.json();
  }
}
```

---

## 📋 구현 순서

### Phase 1: 데이터베이스 및 백엔드 기본 구조 (1일)

- [x] 데이터베이스 테이블 생성 (`external_rest_api_connections`)
- [ ] 타입 정의 작성 (`externalRestApiTypes.ts`)
- [ ] 서비스 계층 기본 CRUD 구현
- [ ] API 라우트 기본 구현

### Phase 2: 연결 테스트 기능 (1일)

- [ ] 연결 테스트 로직 구현
- [ ] 인증 타입별 헤더 구성 로직
- [ ] 에러 처리 및 타임아웃 관리
- [ ] 테스트 결과 저장 (last_test_date, last_test_result)

### Phase 3: 프론트엔드 기본 UI (1-2일)

- [ ] 탭 구조 추가 (Database / REST API)
- [ ] REST API 연결 목록 컴포넌트
- [ ] API 클라이언트 작성
- [ ] 기본 CRUD UI 구현

### Phase 4: 모달 및 상세 기능 (1-2일)

- [ ] REST API 연결 설정 모달
- [ ] 헤더 관리 컴포넌트 (키-값 동적 추가/삭제)
- [ ] 인증 설정 컴포넌트 (타입별 입력 필드)
- [ ] 고급 설정 섹션

### Phase 5: 테스트 및 통합 (1일)

- [ ] 연결 테스트 UI
- [ ] 테스트 결과 표시
- [ ] 에러 처리 및 사용자 피드백
- [ ] 전체 기능 통합 테스트

### Phase 6: 최적화 및 마무리 (0.5일)

- [ ] 민감 정보 암호화 (API 키, 토큰, 비밀번호)
- [ ] UI/UX 개선
- [ ] 문서화

---

## 🧪 테스트 시나리오

### 1. REST API 연결 등록 테스트

- [ ] 기본 정보 입력 (연결명, URL)
- [ ] 헤더 추가/삭제
- [ ] 각 인증 타입별 설정
- [ ] 유효성 검증 (필수 필드, URL 형식)

### 2. 연결 테스트

- [ ] 인증 없는 API 테스트
- [ ] API Key (header/query) 테스트
- [ ] Bearer Token 테스트
- [ ] Basic Auth 테스트
- [ ] 타임아웃 시나리오
- [ ] 네트워크 오류 시나리오

### 3. 데이터 관리

- [ ] 목록 조회 및 필터링
- [ ] 연결 수정
- [ ] 연결 삭제
- [ ] 활성/비활성 전환

### 4. 통합 시나리오

- [ ] DB 연결 탭 ↔ REST API 탭 전환
- [ ] 여러 연결 등록 및 관리
- [ ] 동시 테스트 실행

---

## 🔒 보안 고려사항

### 1. 민감 정보 암호화

```typescript
// API 키, 토큰, 비밀번호 암호화
private static encryptSensitiveData(authConfig: any): any {
  if (!authConfig) return null;

  const encrypted = { ...authConfig };

  // 암호화 대상 필드
  if (encrypted.keyValue) {
    encrypted.keyValue = encrypt(encrypted.keyValue);
  }
  if (encrypted.token) {
    encrypted.token = encrypt(encrypted.token);
  }
  if (encrypted.password) {
    encrypted.password = encrypt(encrypted.password);
  }
  if (encrypted.clientSecret) {
    encrypted.clientSecret = encrypt(encrypted.clientSecret);
  }

  return encrypted;
}
```

### 2. 접근 권한 제어

- 관리자 권한만 접근
- 회사별 데이터 분리
- API 호출 시 인증 토큰 검증

### 3. 테스트 요청 제한

- Rate Limiting (1분에 최대 10회)
- 타임아웃 설정 (최대 30초)
- 동시 테스트 제한

---

## 📊 성능 최적화

### 1. 헤더 데이터 구조

```typescript
// JSONB 필드 인덱싱 (PostgreSQL)
CREATE INDEX idx_rest_api_headers ON external_rest_api_connections
USING GIN (default_headers);

CREATE INDEX idx_rest_api_auth_config ON external_rest_api_connections
USING GIN (auth_config);
```

### 2. 캐싱 전략

- 자주 사용되는 연결 정보 캐싱
- 테스트 결과 임시 캐싱 (5분)

---

## 📚 향후 확장 가능성

### 1. 엔드포인트 관리

각 REST API 연결에 대해 자주 사용하는 엔드포인트를 사전 등록하여 빠른 호출 가능

### 2. 요청 템플릿

HTTP 메서드별 요청 바디 템플릿 관리

### 3. 응답 매핑

REST API 응답을 내부 데이터 구조로 변환하는 매핑 룰 설정

### 4. 로그 및 모니터링

- API 호출 이력 기록
- 응답 시간 모니터링
- 오류율 추적

---

## ✅ 완료 체크리스트

### 백엔드

- [ ] 데이터베이스 테이블 생성
- [ ] 타입 정의
- [ ] 서비스 계층 CRUD
- [ ] 연결 테스트 로직
- [ ] API 라우트
- [ ] 민감 정보 암호화

### 프론트엔드

- [ ] 탭 구조
- [ ] REST API 연결 목록
- [ ] 연결 설정 모달
- [ ] 헤더 관리 컴포넌트
- [ ] 인증 설정 컴포넌트
- [ ] API 클라이언트
- [ ] 연결 테스트 UI

### 테스트

- [ ] 단위 테스트
- [ ] 통합 테스트
- [ ] 사용자 시나리오 테스트

### 문서

- [ ] API 문서
- [ ] 사용자 가이드
- [ ] 배포 가이드

---

**작성일**: 2025-10-20  
**버전**: 1.0  
**담당**: AI Assistant