impl-integrations

외부 서비스 통합 (B6)

ultrathink

당신은 인프라/백엔드 개발자입니다. TS에 명시된 외부 서비스 연동을 구현합니다.

컨텍스트 로드

• 프로젝트 설정: backend.md — external_services

입력

$ARGUMENTS 의 기술 명세서(TS) → Read. 인프라, 비동기 처리, 외부 호출 관련 섹션이 주 입력입니다.

★ B3/B4 시뮬레이션 교체 ★

B3 서비스에서 외부 서비스 호출을 TODO/stub으로 남긴 부분을 실제 코드로 교체합니다.

구현 항목 (TS 해당 시)

1. 메시지 큐 / 비동기 작업

backend.md의 external_services.message_queue에 따름:

BullMQ (Redis):

// jobs/embedding.processor.ts
@Processor('embedding')
export class EmbeddingProcessor {
  @Process()
  async process(job: Job<EmbeddingJobData>): Promise<void> {
    // TS 비동기 처리 흐름 구현
    // 타임아웃: TS에 명시된 값
    // 재시도: TS에 명시된 횟수/전략
    // 최종 실패: 상태 업데이트 + 로깅
  }
}

// jobs/embedding.producer.ts
@Injectable()
export class EmbeddingProducer {
  async enqueue(data: EmbeddingJobData): Promise<void> {
    await this.queue.add('process', data, {
      attempts: 3,          // TS 재시도 횟수
      backoff: { type: 'exponential', delay: 1000 },
      timeout: 30_000,      // TS 타임아웃
    })
  }
}

2. 실시간 통신

backend.md의 external_services.realtime에 따름:

SSE:

// controllers/events.controller.ts
@Sse('events')
async events(@Query('speaker_id') speakerId: string): Observable<MessageEvent> {
  // TS에 명시된 이벤트 구독/해제 패턴
  // 연결 종료 시 리소스 정리
}

WebSocket:

// gateways/notification.gateway.ts
@WebSocketGateway()
export class NotificationGateway {
  // TS에 명시된 이벤트 타입/페이로드
}

3. 파일 스토리지

backend.md의 external_services.storage에 따름:

// services/storage.service.ts
@Injectable()
export class StorageService {
  // TS에 명시된 업로드/다운로드/삭제 패턴
  // 크기 제한, 형식 제한
  // 서명된 URL (해당 시)
}

4. 캐시

backend.md의 external_services.cache에 따름:

// services/cache.service.ts 또는 데코레이터
// TS에 명시된 캐시 정책 (TTL, 무효화 조건)

5. 이메일/알림

backend.md의 external_services.email에 따름:

// services/notification.service.ts
// TS에 명시된 알림 트리거 + 템플릿

모든 외부 호출 공통 패턴

TS에 "모든 외부 호출에 타임아웃, 재시도, 실패 경로"가 명시되어 있으므로:

// 공통 외부 호출 래퍼
async function withRetry<T>(
  fn: () => Promise<T>,
  options: { maxRetries: number; timeout: number; backoff: 'exponential' | 'fixed' }
): Promise<T> {
  // 구현
}

환경 변수

TS 인프라 섹션의 환경 변수 목록 → .env.example에 추가:

# 메시지 큐
REDIS_URL=redis://localhost:6379

# 스토리지
S3_BUCKET=
S3_REGION=
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=

품질 자가 점검

• TS의 모든 비동기 처리가 큐/이벤트로 구현되었는가
• 모든 외부 호출에 타임아웃 + 재시도 + 실패 경로가 있는가
• 큐 job 실패 시 DLQ 또는 상태 업데이트가 있는가
• SSE/WebSocket 연결 해제 시 리소스 정리가 있는가
• 환경 변수가 .env.example에 추가되었는가
• 외부 서비스 설정이 하드코딩 없이 환경 변수로 관리되는가