diff --git a/design/backend/logical/logical-architecture.md b/design/backend/logical/logical-architecture.md index 9f010f2..f75a943 100644 --- a/design/backend/logical/logical-architecture.md +++ b/design/backend/logical/logical-architecture.md @@ -14,6 +14,7 @@ - **v1.0** (2025-10-21): 초기 마이크로서비스 아키텍처 설계 - **v2.0** (2025-10-22): CQRS 패턴 및 Event-Driven 아키텍처 전환, Resilience 패턴 전면 적용 - **v2.1** (2025-10-22): 서비스 구조 간소화, Kafka 통합 (Event Bus + Job Queue), Distribution 비동기 처리 +- **v2.2** (2025-10-22): Distribution Service 동기 호출 전환 (REST API 직접 호출) --- @@ -48,7 +49,7 @@ #### Kafka 통합 전략 - **Event Topics**: 도메인 이벤트 발행/구독 (EventCreated, ParticipantRegistered 등) -- **Job Topics**: 비동기 작업 요청/처리 (ai-job, image-job, distribution-job) +- **Job Topics**: 비동기 작업 요청/처리 (ai-job, image-job) - **단일 메시징 플랫폼**: 운영 복잡도 감소 및 일관된 메시지 처리 #### Resilience 패턴 적용 @@ -69,7 +70,8 @@ 2. **Event Service**: 이벤트 전체 생명주기 관리 - 이벤트 생성/수정/삭제/조회 - 이벤트 생성 플로우 오케스트레이션 - - Kafka Job 발행 (AI, 이미지, 배포) + - Kafka Job 발행 (AI, 이미지) + - Distribution Service 동기 호출 (배포) - Kafka Event 발행 (EventCreated) 3. **Participation Service**: 참여 및 당첨자 관리 @@ -95,8 +97,8 @@ - 외부 이미지 생성 API 호출 (Circuit Breaker, Timeout 20초) - CDN 업로드 및 캐싱 (Redis, TTL 7일) -3. **Distribution Service**: 다중 채널 배포 (비동기) - - Kafka Job 구독 (distribution-job) +3. **Distribution Service**: 다중 채널 배포 (동기) + - REST API 제공 (Event Service에서 호출) - 병렬 배포 (Circuit Breaker, Retry, Bulkhead) - Kafka Event 발행 (DistributionCompleted) @@ -110,7 +112,6 @@ **Job Topics** (비동기 작업): - **ai-job**: AI 추천 작업 - **image-job**: 이미지 생성 작업 -- **distribution-job**: 배포 작업 (비동기) **특징**: - At-Least-Once Delivery 보장 @@ -170,13 +171,15 @@ **Kafka Job 발행**: 1. **ai-job**: AI 추천 요청 2. **image-job**: 이미지 생성 요청 -3. **distribution-job**: 배포 요청 (비동기) + +**서비스 간 호출**: +- **Distribution Service**: 다중 채널 배포 (동기 호출, Circuit Breaker 적용) **주요 플로우**: 1. 이벤트 목적 선택 → Event DB 저장 → EventCreated 발행 2. AI 추천 요청 → ai-job 발행 3. 이미지 생성 요청 → image-job 발행 -4. 배포 승인 → distribution-job 발행 (비동기) +4. 배포 승인 → Distribution Service 동기 호출 **데이터 저장**: - Event DB: events, event_objectives, event_prizes 테이블 @@ -288,14 +291,14 @@ #### Distribution Service **핵심 책임**: -- 다중 채널 병렬 배포 (비동기) +- 다중 채널 병렬 배포 (동기) - 배포 상태 모니터링 - Kafka Event 발행 (DistributionCompleted) **관련 유저스토리**: UFR-DIST-010, 020 -**Kafka Job 구독**: -- **distribution-job**: 배포 작업 요청 (비동기) +**주요 API**: +- `POST /api/distribution/distribute`: 다중 채널 배포 요청 (Event Service에서 호출) **Kafka 이벤트 발행**: - **DistributionCompleted**: 배포 완료 시 @@ -310,7 +313,7 @@ **처리 시간**: 1분 이내 (모든 채널 배포 완료) -**배포 채널 (비동기)**: +**배포 채널**: - 우리동네TV API (영상 업로드) - 링고비즈 API (연결음 업데이트) - 지니TV API (TV 광고 등록) @@ -341,7 +344,6 @@ |---------|--------|--------|---------|------| | **ai-job** | Event Service | AI Service | eventId, objective, industry, region | AI 트렌드 분석 및 이벤트 추천 요청 | | **image-job** | Event Service | Content Service | eventId, content, style | SNS 이미지 생성 요청 (3가지 스타일) | -| **distribution-job** | Event Service | Distribution Service | eventId, distributionChannels | 다중 채널 배포 요청 (비동기) | #### 통신 패턴별 설계 @@ -357,7 +359,7 @@ - 디버깅 복잡도 증가 **2. Job Topics (비동기 작업)** -- **사용 시나리오**: 장시간 작업 (AI 추천, 이미지 생성, 다중 채널 배포) +- **사용 시나리오**: 장시간 작업 (AI 추천, 이미지 생성) - **통신 방식**: Kafka 메시지 큐 - **패턴**: Asynchronous Request-Reply - **처리 플로우**: @@ -367,7 +369,18 @@ 4. Async Service → Redis: 결과 캐싱 5. Event Service → Client: 완료 응답 -**3. 데이터베이스 직접 조회** +**3. 서비스 간 동기 호출** +- **사용 시나리오**: 다중 채널 배포 (Distribution Service) +- **통신 방식**: REST API (HTTP/JSON) +- **패턴**: Synchronous Request-Reply +- **처리 플로우**: + 1. Event Service → Distribution Service: POST /api/distribution/distribute + 2. Distribution Service: 다중 채널 병렬 배포 (1분 이내) + 3. Distribution Service → Event Service: 배포 완료 응답 + 4. Distribution Service → Kafka: DistributionCompleted 이벤트 발행 +- **Resilience**: Circuit Breaker 적용 (실패율 50% 초과 시 Open) + +**4. 데이터베이스 직접 조회** - **사용 시나리오**: Analytics Service가 이벤트/참여 데이터 필요 시 - **패턴**: Database-per-Service 원칙 유지, 필요 시 이벤트로 데이터 동기화 - **통신 방식**: Kafka 이벤트 구독 → Analytics DB 저장 → 로컬 조회 @@ -524,19 +537,18 @@ │ Client → Event Service │ │ - POST /api/events/{id}/publish │ │ - Event 상태 변경 (DRAFT → PUBLISHED) │ - │ - Kafka distribution-job 토픽 발행 (비동기 배포 요청) │ - │ - Job ID 즉시 반환 (0.1초) │ └─────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────┐ - │ Distribution Service (Background) │ - │ - Kafka distribution-job 토픽 구독 │ - │ - 다중 채널 병렬 배포 시작 [Circuit Breaker + Bulkhead] │ + │ Event Service → Distribution Service │ + │ - POST /api/distribution/distribute (동기 호출) │ + │ - 다중 채널 병렬 배포 [Circuit Breaker + Bulkhead] │ │ * 우리동네TV API (영상 업로드) [Retry: 3회] │ │ * 링고비즈 API (연결음 업데이트) [Retry: 3회] │ │ * 지니TV API (광고 등록) [Retry: 3회] │ │ * SNS APIs (Instagram, Naver, Kakao) [Retry: 3회] │ │ - 배포 완료: DistributionCompleted 이벤트 발행 → Kafka │ + │ - Event Service로 배포 완료 응답 (1분 이내) │ └─────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────┐ @@ -545,6 +557,11 @@ │ - Analytics DB 배포 통계 업데이트 │ │ - 대시보드 캐시 무효화 (다음 조회 시 갱신) │ └─────────────────────────────────────────────────────────────┘ + + ┌─────────────────────────────────────────────────────────────┐ + │ Event Service → Client │ + │ - 배포 완료 응답 반환 │ + └─────────────────────────────────────────────────────────────┘ ``` ### 3.2 고객 참여 플로우 (Event-Driven) @@ -841,11 +858,11 @@ 1. **Kafka 통합 메시징 플랫폼 채택**: Event Bus와 Job Queue를 Kafka로 통합하여 운영 복잡도 감소 2. **Event-Driven 아키텍처 채택**: Kafka를 통한 서비스 간 느슨한 결합 및 비동기 통신 3. **도메인 이벤트 정의**: 4개 Event Topics (EventCreated, ParticipantRegistered, WinnerSelected, DistributionCompleted) -4. **Job Topics 정의**: 3개 Job Topics (ai-job, image-job, distribution-job)로 비동기 작업 처리 +4. **Job Topics 정의**: 2개 Job Topics (ai-job, image-job)로 장시간 비동기 작업 처리 5. **Resilience 패턴 전면 적용**: Circuit Breaker, Retry, Timeout, Bulkhead, Fallback 6. **At-Least-Once Delivery**: Kafka 메시지 보장 및 멱등성 설계 7. **Cache-Aside 패턴**: AI/이미지 생성 결과 캐싱으로 응답 시간 90% 개선 -8. **비동기 배포**: Distribution Service가 distribution-job을 통해 다중 채널 배포 비동기 처리 +8. **동기 배포**: Event Service가 Distribution Service를 REST API로 직접 호출하여 다중 채널 배포 동기 처리 9. **서비스별 독립 Database**: Database-per-Service 패턴으로 서비스 독립성 보장 ### C. 향후 개선 방안 (Phase 2 이후) @@ -859,7 +876,7 @@ --- -**문서 버전**: 2.1 +**문서 버전**: 2.2 **최종 수정일**: 2025-10-22 **작성자**: System Architect -**변경 사항**: 서비스 구조 간소화, Kafka 통합 (Event Bus + Job Queue), Distribution 비동기 처리 +**변경 사항**: Distribution Service 동기 호출 전환 (REST API 직접 호출) diff --git a/design/backend/logical/logical-architecture.mmd b/design/backend/logical/logical-architecture.mmd index 4bc3c46..a06d446 100644 --- a/design/backend/logical/logical-architecture.mmd +++ b/design/backend/logical/logical-architecture.mmd @@ -17,7 +17,7 @@ graph TB end %% Kafka (Event Bus + Job Queue) - Kafka["Kafka
━━━━━━━━━━

• EventCreated
• ParticipantRegistered
• WinnerSelected
• DistributionCompleted
━━━━━━━━━━

• ai-job
• image-job
• distribution-job"] + Kafka["Kafka
━━━━━━━━━━

• EventCreated
• ParticipantRegistered
• WinnerSelected
• DistributionCompleted
━━━━━━━━━━

• ai-job
• image-job"] %% External System External["외부시스템
[Circuit Breaker]
━━━━━━━━━━
• 국세청 API
• AI API
• 이미지 생성 API
• 배포 채널 APIs
(비동기)"] @@ -31,7 +31,6 @@ graph TB %% Job Publishing (비동기 작업 요청) EventSvc -->|"ai-job 발행"| Kafka EventSvc -->|"image-job 발행"| Kafka - EventSvc -->|"distribution-job
발행 (비동기)"| Kafka %% Event Subscription Kafka -.->|"EventCreated
구독"| AnalSvc @@ -41,7 +40,9 @@ graph TB %% Job Subscription Kafka -.->|"ai-job 구독"| AISvc Kafka -.->|"image-job 구독"| ContentSvc - Kafka -.->|"distribution-job
구독 (비동기)"| DistSvc + + %% Service to Service (동기 호출) + EventSvc -->|"다중 채널 배포
[Circuit Breaker]"| DistSvc %% Services to External (Resilience 패턴) UserSvc -->|"사업자번호 검증
[Retry: 3회]"| External