7개 마이크로서비스 API 설계 완료

- User Service API (7 APIs, 31KB) - Event Service API (14 APIs, 41KB) - AI Service API (3 APIs, 26KB) - Content Service API (6 APIs, 37KB) - Distribution Service API (2 APIs, 21KB) - Participation Service API (5 APIs, 25KB) - Analytics Service API (4 APIs, 28KB) 총 41개 API 엔드포인트, 6,912줄, OpenAPI 3.0 표준 준수 유저스토리 기반 설계, JWT 인증, Kafka/Redis 통합 문서화 API 설계서 작성 완료 (종합 가이드 포함) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-06-13 11:39:11 +00:00 · 2025-10-23 16:56:54 +09:00
parent 781c3944ed
commit b9745f24e5
8 changed files with 5019 additions and 3323 deletions
@@ -2,61 +2,73 @@ openapi: 3.0.3
 info:
  title: Distribution Service API
  description: |
-    KT AI 기반 소상공인 이벤트 자동 생성 서비스 - 배포 관리 서비스 API
+    KT AI 기반 소상공인 이벤트 자동 생성 서비스의 다중 채널 배포 관리 API

-    **주요 기능:**
-    - 다중 채널 배포 관리
-    - 배포 상태 모니터링
-    - 채널별 배포 결과 추적
+    ## 주요 기능
+    - 다중 채널 동시 배포 (우리동네TV, 링고비즈, 지니TV, SNS)
+    - 배포 상태 실시간 모니터링
+    - Circuit Breaker 기반 장애 격리
+    - Retry 패턴 및 Fallback 처리
+
+    ## 배포 채널
+    - **우리동네TV**: 영상 콘텐츠 업로드
+    - **링고비즈**: 연결음 업데이트
+    - **지니TV**: 광고 등록
+    - **SNS**: Instagram, Naver Blog, Kakao Channel
+
+    ## Resilience 패턴
+    - Circuit Breaker: 채널별 독립적 장애 격리
+    - Retry: 지수 백오프 (1s, 2s, 4s) 최대 3회
+    - Bulkhead: 리소스 격리
+    - Fallback: 실패 채널 스킵 및 알림

-    **지원 배포 채널:**
-    - 우리동네TV
-    - 링고비즈 (연결음)
-    - 지니TV 광고
-    - Instagram
-    - Naver Blog
-    - Kakao Channel
  version: 1.0.0
  contact:
-    name: KT Event Marketing Team
-    email: support@kt-event-marketing.com
+    name: Backend Development Team
+    email: backend@kt-event-marketing.com

 servers:
-  - url: http://localhost:8085
+  - url: http://localhost:8083
    description: Local Development Server
-  - url: https://api-dev.kt-event-marketing.com
-    description: Development Server
-  - url: https://api.kt-event-marketing.com
-    description: Production Server
+  - url: http://distribution-service:8083
+    description: Docker/Kubernetes Service
+  - url: https://api-dev.kt-event-marketing.com/distribution
+    description: Development Environment
+  - url: https://api.kt-event-marketing.com/distribution
+    description: Production Environment

 tags:
  - name: Distribution
    description: 다중 채널 배포 관리
-  - name: Status
-    description: 배포 상태 조회 및 모니터링
+  - name: Monitoring
+    description: 배포 상태 모니터링

 paths:
  /api/distribution/distribute:
    post:
      tags:
        - Distribution
-      summary: 다중 채널 배포 실행
+      summary: 다중 채널 배포 요청
      description: |
-        선택된 모든 채널에 동시 배포를 실행합니다.
+        이벤트 콘텐츠를 선택된 채널들에 동시 배포합니다.

-        **배포 프로세스:**
-        1. 배포 이력 초기화 (상태: PENDING)
-        2. 각 채널별 병렬 배포 처리
-        3. 배포 결과 집계 및 저장
-        4. Kafka 이벤트 발행 (Analytics Service 구독)
-        5. Redis 캐시 저장 (TTL: 1시간)
+        ## 처리 흐름
+        1. 배포 요청 검증 (이벤트 ID, 채널 목록, 콘텐츠 데이터)
+        2. 채널별 병렬 배포 실행 (1분 이내 완료 목표)
+        3. Circuit Breaker로 장애 채널 격리
+        4. 실패 시 Retry (지수 백오프: 1s, 2s, 4s)
+        5. Fallback: 실패 채널 스킵 및 알림
+        6. 배포 결과 집계 및 로그 저장
+        7. DistributionCompleted 이벤트 Kafka 발행

-        **Sprint 2 제약사항:**
-        - 외부 API 호출 없음 (Mock 처리)
-        - 모든 배포 요청은 성공으로 처리
-        - 배포 로그만 DB에 기록
+        ## Resilience 처리
+        - 각 채널별 독립적인 Circuit Breaker 적용
+        - 최대 3회 재시도 (지수 백오프)
+        - 일부 채널 실패 시에도 성공 채널은 유지
+        - 실패 채널 정보는 응답에 포함

-        **유저스토리:** UFR-DIST-010
+      x-user-story: UFR-DIST-010
+      x-controller: DistributionController
      operationId: distributeToChannels
      requestBody:
        required: true
@@ -165,23 +177,26 @@ paths:
  /api/distribution/{eventId}/status:
    get:
      tags:
-        - Status
+        - Monitoring
      summary: 배포 상태 조회
      description: |
-        이벤트의 배포 상태를 조회합니다.
+        특정 이벤트의 배포 상태를 실시간으로 조회합니다.

-        **조회 프로세스:**
-        1. Cache-Aside 패턴 적용 (Redis 캐시 우선 조회)
-        2. 캐시 MISS 시 DB에서 배포 이력 조회
-        3. 진행중(IN_PROGRESS) 상태일 때만 외부 API로 실시간 상태 확인
-        4. Circuit Breaker 패턴 적용 (외부 API 호출 시)
-        5. 배포 상태 캐싱 (TTL: 1시간)
+        ## 조회 정보
+        - 전체 배포 상태 (진행중, 완료, 부분성공, 실패)
+        - 채널별 배포 상태 및 결과
+        - 실패 채널 상세 정보 (오류 유형, 재시도 횟수)
+        - 배포 시작/완료 시간 및 소요 시간
+        - 외부 채널 ID 및 배포 URL

-        **응답 시간:**
-        - 캐시 HIT: 0.1초
-        - 캐시 MISS: 0.5초 ~ 2초
+        ## 상태 값
+        - **IN_PROGRESS**: 배포 진행 중
+        - **COMPLETED**: 모든 채널 배포 완료
+        - **PARTIAL_SUCCESS**: 일부 채널 배포 성공
+        - **FAILED**: 모든 채널 배포 실패

-        **유저스토리:** UFR-DIST-020
+      x-user-story: UFR-DIST-020
+      x-controller: DistributionController
      operationId: getDistributionStatus
      parameters:
        - name: eventId
@@ -285,80 +300,6 @@ paths:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

-  /api/distribution/{eventId}/retry:
-    post:
-      tags:
-        - Distribution
-      summary: 실패한 채널 재시도
-      description: |
-        실패한 채널에 대해 배포를 재시도합니다.
-
-        **재시도 프로세스:**
-        1. 실패한 채널 목록 검증
-        2. 새로운 배포 시도 로그 생성
-        3. Circuit Breaker 및 Retry 로직 적용
-        4. 캐시 무효화
-        5. 재시도 결과 반환
-
-        **재시도 제한:**
-        - 최대 재시도 횟수: 3회
-        - Circuit Breaker가 OPEN 상태일 경우 30초 대기 후 시도
-      operationId: retryDistribution
-      parameters:
-        - name: eventId
-          in: path
-          required: true
-          description: 이벤트 ID
-          schema:
-            type: string
-            example: "evt-12345"
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/RetryRequest'
-            examples:
-              retryFailedChannels:
-                summary: 실패한 채널 재시도
-                value:
-                  channels:
-                    - "INSTAGRAM"
-                    - "KAKAO_CHANNEL"
-      responses:
-        '200':
-          description: 재시도 완료
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/RetryResponse'
-              examples:
-                success:
-                  summary: 재시도 성공
-                  value:
-                    eventId: "evt-12345"
-                    retryStatus: "COMPLETED"
-                    retriedAt: "2025-11-01T09:05:00Z"
-                    results:
-                      - channel: "INSTAGRAM"
-                        status: "SUCCESS"
-                        postUrl: "https://instagram.com/p/retry-post-id"
-                      - channel: "KAKAO_CHANNEL"
-                        status: "SUCCESS"
-                        messageId: "kakao-retry-12345"
-        '400':
-          description: 잘못된 요청
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
-        '404':
-          description: 배포 이력을 찾을 수 없음
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ErrorResponse'
-
 components:
  schemas:
    DistributionRequest:
@@ -682,58 +623,6 @@ components:
          description: 마지막 재시도 시각
          example: "2025-11-01T08:59:30Z"

-    RetryRequest:
-      type: object
-      required:
-        - channels
-      properties:
-        channels:
-          type: array
-          description: 재시도할 채널 목록
-          minItems: 1
-          items:
-            type: string
-            enum:
-              - WOORIDONGNE_TV
-              - RINGO_BIZ
-              - GENIE_TV
-              - INSTAGRAM
-              - NAVER_BLOG
-              - KAKAO_CHANNEL
-          example:
-            - "INSTAGRAM"
-            - "KAKAO_CHANNEL"
-
-    RetryResponse:
-      type: object
-      required:
-        - eventId
-        - retryStatus
-        - results
-      properties:
-        eventId:
-          type: string
-          description: 이벤트 ID
-          example: "evt-12345"
-        retryStatus:
-          type: string
-          description: 재시도 전체 상태
-          enum:
-            - COMPLETED
-            - PARTIAL_FAILURE
-            - FAILED
-          example: "COMPLETED"
-        retriedAt:
-          type: string
-          format: date-time
-          description: 재시도 시각
-          example: "2025-11-01T09:05:00Z"
-        results:
-          type: array
-          description: 채널별 재시도 결과
-          items:
-            $ref: '#/components/schemas/ChannelResult'
-
    ErrorResponse:
      type: object
      required: