# KT AI 기반 소상공인 이벤트 자동 생성 서비스 - API 설계서

## 문서 정보
- **작성일**: 2025-10-23
- **버전**: 1.0
- **작성자**: System Architect
- **관련 문서**:
  - [유저스토리](../../userstory.md)
  - [논리 아키텍처](../logical/logical-architecture.md)
  - [외부 시퀀스 설계](../sequence/outer/)
  - [내부 시퀀스 설계](../sequence/inner/)

---

## 목차
1. [개요](#1-개요)
2. [API 설계 원칙](#2-api-설계-원칙)
3. [서비스별 API 명세](#3-서비스별-api-명세)
4. [API 통합 가이드](#4-api-통합-가이드)
5. [보안 및 인증](#5-보안-및-인증)
6. [에러 처리](#6-에러-처리)
7. [API 테스트 가이드](#7-api-테스트-가이드)

---

## 1. 개요

### 1.1 설계 범위
본 API 설계서는 KT AI 기반 소상공인 이벤트 자동 생성 서비스의 7개 마이크로서비스 API를 정의합니다.

### 1.2 마이크로서비스 구성
1. **User Service**: 사용자 인증 및 매장정보 관리
2. **Event Service**: 이벤트 전체 생명주기 관리
3. **AI Service**: AI 기반 이벤트 추천
4. **Content Service**: SNS 콘텐츠 생성
5. **Distribution Service**: 다중 채널 배포 관리
6. **Participation Service**: 이벤트 참여 및 당첨자 관리
7. **Analytics Service**: 실시간 효과 측정 및 통합 대시보드

### 1.3 파일 구조
```
design/backend/api/
├── user-service-api.yaml           (31KB, 1,011 lines)
├── event-service-api.yaml          (41KB, 1,373 lines)
├── ai-service-api.yaml             (26KB, 847 lines)
├── content-service-api.yaml        (37KB, 1,158 lines)
├── distribution-service-api.yaml   (21KB, 653 lines)
├── participation-service-api.yaml  (25KB, 820 lines)
├── analytics-service-api.yaml      (28KB, 1,050 lines)
└── API-설계서.md                   (this file)
```

---

## 2. API 설계 원칙

### 2.1 OpenAPI 3.0 표준 준수
- 모든 API는 OpenAPI 3.0 스펙을 따릅니다
- Swagger UI/Editor에서 직접 테스트 가능합니다
- 자동 코드 생성 및 문서화를 지원합니다

### 2.2 RESTful 설계
- **리소스 중심 URL 구조**: `/api/{resource}/{id}`
- **HTTP 메서드**: GET (조회), POST (생성), PUT (수정), DELETE (삭제)
- **상태 코드**: 200 (성공), 201 (생성), 400 (잘못된 요청), 401 (인증 실패), 403 (권한 없음), 404 (리소스 없음), 500 (서버 오류)

### 2.3 유저스토리 기반 설계
- 각 API 엔드포인트는 유저스토리와 매핑됩니다
- **x-user-story** 필드로 유저스토리 ID를 명시합니다
- **x-controller** 필드로 담당 컨트롤러를 명시합니다

### 2.4 서비스 독립성
- 각 서비스는 독립적인 OpenAPI 명세를 가집니다
- 공통 스키마는 각 서비스에서 필요에 따라 정의합니다
- 서비스 간 통신은 REST API, Kafka 이벤트, Redis 캐시를 통해 이루어집니다

### 2.5 Example 데이터 제공
- 모든 스키마에 example 데이터가 포함됩니다
- Swagger UI에서 즉시 테스트 가능합니다
- 성공/실패 시나리오 모두 포함합니다

---

## 3. 서비스별 API 명세

### 3.1 User Service (사용자 인증 및 매장정보 관리)

**파일**: `user-service-api.yaml`
**관련 유저스토리**: UFR-USER-010, 020, 030, 040

#### API 엔드포인트 (7개)

| 메서드 | 경로 | 설명 | 유저스토리 | 인증 |
|--------|------|------|-----------|------|
| POST | /api/users/register | 회원가입 | UFR-USER-010 | - |
| POST | /api/users/login | 로그인 | UFR-USER-020 | - |
| POST | /api/users/logout | 로그아웃 | UFR-USER-040 | JWT |
| GET | /api/users/profile | 프로필 조회 | UFR-USER-030 | JWT |
| PUT | /api/users/profile | 프로필 수정 | UFR-USER-030 | JWT |
| PUT | /api/users/password | 비밀번호 변경 | UFR-USER-030 | JWT |
| GET | /api/users/{userId}/store | 매장정보 조회 (서비스 연동용) | - | JWT |

#### 주요 기능
- JWT 토큰 기반 인증 (TTL 7일)
- 사업자번호 검증 (국세청 API 연동)
- Redis 세션 관리
- BCrypt 비밀번호 해싱
- AES-256-GCM 사업자번호 암호화

#### 주요 스키마
- `UserRegisterRequest`: 회원가입 요청
- `UserLoginRequest`: 로그인 요청
- `UserProfileResponse`: 프로필 응답
- `StoreInfoResponse`: 매장정보 응답

---

### 3.2 Event Service (이벤트 전체 생명주기 관리)

**파일**: `event-service-api.yaml`
**관련 유저스토리**: UFR-EVENT-010 ~ 070

#### API 엔드포인트 (14개)

**Dashboard & Event List:**
| 메서드 | 경로 | 설명 | 유저스토리 | 인증 |
|--------|------|------|-----------|------|
| GET | /api/events | 이벤트 목록 조회 | UFR-EVENT-010, 070 | JWT |
| GET | /api/events/{eventId} | 이벤트 상세 조회 | UFR-EVENT-060 | JWT |

**Event Creation Flow (5 Steps):**
| 메서드 | 경로 | 설명 | 유저스토리 | 인증 |
|--------|------|------|-----------|------|
| POST | /api/events/objectives | Step 1: 이벤트 목적 선택 | UFR-EVENT-020 | JWT |
| POST | /api/events/{eventId}/ai-recommendations | Step 2: AI 추천 요청 | UFR-EVENT-030 | JWT |
| PUT | /api/events/{eventId}/recommendations | Step 2-2: AI 추천 선택 | UFR-EVENT-030 | JWT |
| POST | /api/events/{eventId}/images | Step 3: 이미지 생성 요청 | UFR-CONT-010 | JWT |
| PUT | /api/events/{eventId}/images/{imageId}/select | Step 3-2: 이미지 선택 | UFR-CONT-010 | JWT |
| PUT | /api/events/{eventId}/images/{imageId}/edit | Step 3-3: 이미지 편집 | UFR-CONT-020 | JWT |
| PUT | /api/events/{eventId}/channels | Step 4: 배포 채널 선택 | UFR-EVENT-040 | JWT |
| POST | /api/events/{eventId}/publish | Step 5: 최종 승인 및 배포 | UFR-EVENT-050 | JWT |

**Event Management:**
| 메서드 | 경로 | 설명 | 유저스토리 | 인증 |
|--------|------|------|-----------|------|
| PUT | /api/events/{eventId} | 이벤트 수정 | UFR-EVENT-060 | JWT |
| DELETE | /api/events/{eventId} | 이벤트 삭제 | UFR-EVENT-070 | JWT |
| POST | /api/events/{eventId}/end | 이벤트 조기 종료 | UFR-EVENT-060 | JWT |

**Job Status:**
| 메서드 | 경로 | 설명 | 유저스토리 | 인증 |
|--------|------|------|-----------|------|
| GET | /api/jobs/{jobId} | Job 상태 폴링 | UFR-EVENT-030, UFR-CONT-010 | JWT |

#### 주요 기능
- 이벤트 생명주기 관리 (DRAFT → PUBLISHED → ENDED)
- Kafka Job 발행 (ai-event-generation-job, image-generation-job)
- Kafka Event 발행 (EventCreated)
- Distribution Service 동기 호출
- Redis 기반 AI/이미지 데이터 캐싱
- Job 상태 폴링 메커니즘 (PENDING, PROCESSING, COMPLETED, FAILED)

#### 주요 스키마
- `EventObjectiveRequest`: 이벤트 목적 선택
- `EventResponse`: 이벤트 응답
- `JobStatusResponse`: Job 상태 응답
- `AIRecommendationSelection`: AI 추천 선택
- `ChannelSelectionRequest`: 배포 채널 선택

---

### 3.3 AI Service (AI 기반 이벤트 추천)

**파일**: `ai-service-api.yaml`
**관련 유저스토리**: UFR-AI-010

#### API 엔드포인트 (3개)

| 메서드 | 경로 | 설명 | 유저스토리 | 인증 |
|--------|------|------|-----------|------|
| GET | /health | 서비스 헬스체크 | - | - |
| GET | /internal/jobs/{jobId}/status | Job 상태 조회 (내부 API) | UFR-AI-010 | JWT |
| GET | /internal/recommendations/{eventId} | AI 추천 결과 조회 (내부 API) | UFR-AI-010 | JWT |

#### Kafka Consumer (비동기 처리)
- **Topic**: `ai-event-generation-job`
- **Consumer Group**: `ai-service-consumers`
- **처리 시간**: 최대 5분
- **결과 저장**: Redis (TTL 24시간)

#### 주요 기능
- 업종/지역/시즌 트렌드 분석
- 3가지 차별화된 이벤트 기획안 생성
- 예상 성과 계산 (참여자 수, ROI, 매출 증가율)
- Circuit Breaker 패턴 (5분 timeout, 캐시 fallback)
- Claude API / GPT-4 API 연동

#### 주요 스키마
- `KafkaAIJobMessage`: Kafka Job 입력
- `AIRecommendationResult`: AI 추천 결과 (트렌드 분석 + 3가지 옵션)
- `TrendAnalysis`: 업종/지역/시즌 트렌드
- `EventRecommendation`: 이벤트 기획안 (컨셉, 경품, 참여방법, 예상성과)

---

### 3.4 Content Service (SNS 콘텐츠 생성)

**파일**: `content-service-api.yaml`
**관련 유저스토리**: UFR-CONT-010, 020

#### API 엔드포인트 (6개)

| 메서드 | 경로 | 설명 | 유저스토리 | 인증 |
|--------|------|------|-----------|------|
| POST | /api/content/images/generate | 이미지 생성 요청 (비동기) | UFR-CONT-010 | JWT |
| GET | /api/content/images/jobs/{jobId} | Job 상태 폴링 | UFR-CONT-010 | JWT |
| GET | /api/content/events/{eventDraftId} | 이벤트 전체 콘텐츠 조회 | UFR-CONT-020 | JWT |
| GET | /api/content/events/{eventDraftId}/images | 이미지 목록 조회 | UFR-CONT-020 | JWT |
| GET | /api/content/images/{imageId} | 이미지 상세 조회 | UFR-CONT-020 | JWT |
| POST | /api/content/images/{imageId}/regenerate | 이미지 재생성 | UFR-CONT-020 | JWT |

#### Kafka Consumer (비동기 처리)
- **Topic**: `image-generation-job`
- **Consumer Group**: `content-service-consumers`
- **처리 시간**: 최대 5분
- **결과 저장**: Redis (CDN URL, TTL 7일)

#### 주요 기능
- 3가지 스타일 이미지 생성 (SIMPLE, FANCY, TRENDY)
- 플랫폼별 최적화 (Instagram 1080x1080, Naver 800x600, Kakao 800x800)
- Circuit Breaker 패턴 (Stable Diffusion → DALL-E → Default Template)
- Azure Blob Storage (CDN) 연동
- Redis 기반 AI 데이터 읽기

#### 주요 스키마
- `ImageGenerationJob`: Kafka Job 입력
- `ImageGenerationRequest`: 이미지 생성 요청
- `GeneratedImage`: 생성된 이미지 (style, platform, CDN URL)
- `ContentResponse`: 전체 콘텐츠 응답

---

### 3.5 Distribution Service (다중 채널 배포 관리)

**파일**: `distribution-service-api.yaml`
**관련 유저스토리**: UFR-DIST-010, 020

#### API 엔드포인트 (2개)

| 메서드 | 경로 | 설명 | 유저스토리 | 인증 |
|--------|------|------|-----------|------|
| POST | /api/distribution/distribute | 다중 채널 배포 (동기) | UFR-DIST-010 | JWT |
| GET | /api/distribution/{eventId}/status | 배포 상태 조회 | UFR-DIST-020 | JWT |

#### 주요 기능
- **배포 채널**: 우리동네TV, 링고비즈, 지니TV, Instagram, Naver Blog, Kakao Channel
- **병렬 배포**: 6개 채널 동시 배포 (1분 이내)
- **Resilience 패턴**:
  - Circuit Breaker: 채널별 독립 적용
  - Retry: 최대 3회 재시도 (지수 백오프: 1s, 2s, 4s)
  - Bulkhead: 채널별 스레드 풀 격리
  - Fallback: 실패 채널 스킵 + 알림
- **Kafka Event 발행**: DistributionCompleted
- **로깅**: Event DB에 distribution_logs 저장

#### 주요 스키마
- `DistributionRequest`: 배포 요청
- `DistributionResponse`: 배포 응답 (채널별 결과)
- `DistributionStatusResponse`: 배포 상태
- `ChannelDistributionResult`: 채널별 배포 결과

---

### 3.6 Participation Service (이벤트 참여 및 당첨자 관리)

**파일**: `participation-service-api.yaml`
**관련 유저스토리**: UFR-PART-010, 020, 030

#### API 엔드포인트 (5개)

| 메서드 | 경로 | 설명 | 유저스토리 | 인증 |
|--------|------|------|-----------|------|
| POST | /api/events/{eventId}/participate | 이벤트 참여 | UFR-PART-010 | - |
| GET | /api/events/{eventId}/participants | 참여자 목록 조회 | UFR-PART-020 | JWT |
| GET | /api/events/{eventId}/participants/{participantId} | 참여자 상세 조회 | UFR-PART-020 | JWT |
| POST | /api/events/{eventId}/draw-winners | 당첨자 추첨 | UFR-PART-030 | JWT |
| GET | /api/events/{eventId}/winners | 당첨자 목록 조회 | UFR-PART-030 | JWT |

#### 주요 기능
- 중복 참여 체크 (전화번호 기반)
- 매장 방문 고객 가산점 적용
- 난수 기반 무작위 추첨
- Kafka Event 발행 (ParticipantRegistered)
- 개인정보 수집/이용 동의 관리
- 페이지네이션 지원

#### 주요 스키마
- `ParticipationRequest`: 참여 요청
- `ParticipationResponse`: 참여 응답 (응모번호)
- `ParticipantListResponse`: 참여자 목록
- `WinnerDrawRequest`: 당첨자 추첨 요청
- `WinnerResponse`: 당첨자 정보

---

### 3.7 Analytics Service (실시간 효과 측정 및 통합 대시보드)

**파일**: `analytics-service-api.yaml`
**관련 유저스토리**: UFR-ANAL-010

#### API 엔드포인트 (4개)

| 메서드 | 경로 | 설명 | 유저스토리 | 인증 |
|--------|------|------|-----------|------|
| GET | /api/events/{eventId}/analytics | 성과 대시보드 조회 | UFR-ANAL-010 | JWT |
| GET | /api/events/{eventId}/analytics/channels | 채널별 성과 분석 | UFR-ANAL-010 | JWT |
| GET | /api/events/{eventId}/analytics/timeline | 시간대별 참여 추이 | UFR-ANAL-010 | JWT |
| GET | /api/events/{eventId}/analytics/roi | 투자 대비 수익률 상세 | UFR-ANAL-010 | JWT |

#### Kafka Event 구독
- **EventCreated**: 이벤트 기본 통계 초기화
- **ParticipantRegistered**: 실시간 참여자 수 증가
- **DistributionCompleted**: 배포 채널 통계 업데이트

#### 주요 기능
- **실시간 대시보드**: Redis 캐싱 (TTL 5분)
- **외부 API 통합**: 우리동네TV, 지니TV, SNS APIs (조회수, 노출수, 소셜 인터랙션)
- **Circuit Breaker**: 외부 API 실패 시 캐시 fallback
- **ROI 계산**: 비용 대비 수익률 자동 계산
- **성과 집계**: 채널별, 시간대별 성과 분석

#### 주요 스키마
- `AnalyticsDashboardResponse`: 대시보드 전체 데이터
- `ChannelPerformanceResponse`: 채널별 성과
- `TimelineDataResponse`: 시간대별 참여 추이
- `RoiDetailResponse`: ROI 상세 분석

---

## 4. API 통합 가이드

### 4.1 이벤트 생성 플로우 (Event-Driven)

```
1. 이벤트 목적 선택 (Event Service)
   POST /api/events/objectives
   → EventCreated 이벤트 발행 (Kafka)
   → Analytics Service 구독 (통계 초기화)

2. AI 추천 요청 (Event Service → AI Service)
   POST /api/events/{eventId}/ai-recommendations
   → ai-event-generation-job 발행 (Kafka)
   → AI Service 구독 및 처리 (비동기)
   → Redis에 결과 저장 (TTL 24시간)
   → 클라이언트 폴링: GET /api/jobs/{jobId}

3. AI 추천 선택 (Event Service)
   PUT /api/events/{eventId}/recommendations
   → Redis에서 AI 추천 데이터 읽기
   → Event DB에 선택된 추천 저장

4. 이미지 생성 요청 (Event Service → Content Service)
   POST /api/events/{eventId}/images
   → image-generation-job 발행 (Kafka)
   → Content Service 구독 및 처리 (비동기)
   → Redis에서 AI 데이터 읽기
   → CDN에 이미지 업로드
   → Redis에 CDN URL 저장 (TTL 7일)
   → 클라이언트 폴링: GET /api/jobs/{jobId}

5. 이미지 선택 및 편집 (Event Service)
   PUT /api/events/{eventId}/images/{imageId}/select
   PUT /api/events/{eventId}/images/{imageId}/edit

6. 배포 채널 선택 (Event Service)
   PUT /api/events/{eventId}/channels

7. 최종 승인 및 배포 (Event Service → Distribution Service)
   POST /api/events/{eventId}/publish
   → Distribution Service 동기 호출: POST /api/distribution/distribute
   → 다중 채널 병렬 배포 (1분 이내)
   → DistributionCompleted 이벤트 발행 (Kafka)
   → Analytics Service 구독 (배포 통계 업데이트)
```

### 4.2 고객 참여 플로우 (Event-Driven)

```
1. 이벤트 참여 (Participation Service)
   POST /api/events/{eventId}/participate
   → 중복 참여 체크
   → Participation DB 저장
   → ParticipantRegistered 이벤트 발행 (Kafka)
   → Analytics Service 구독 (참여자 수 실시간 증가)

2. 당첨자 추첨 (Participation Service)
   POST /api/events/{eventId}/draw-winners
   → 난수 기반 무작위 추첨
   → Winners DB 저장
```

### 4.3 성과 분석 플로우 (Event-Driven)

```
1. 실시간 대시보드 조회 (Analytics Service)
   GET /api/events/{eventId}/analytics
   → Redis 캐시 확인 (TTL 5분)
   → 캐시 HIT: 즉시 반환
   → 캐시 MISS:
     - Analytics DB 조회 (이벤트/참여 통계)
     - 외부 APIs 조회 (우리동네TV, 지니TV, SNS) [Circuit Breaker]
     - Redis 캐싱 후 반환

2. Kafka 이벤트 구독 (Analytics Service Background)
   - EventCreated 구독 → 이벤트 기본 정보 초기화
   - ParticipantRegistered 구독 → 참여자 수 실시간 증가
   - DistributionCompleted 구독 → 배포 채널 통계 업데이트
   - 캐시 무효화 → 다음 조회 시 최신 데이터 갱신
```

### 4.4 서비스 간 통신 패턴

| 패턴 | 사용 시나리오 | 통신 방식 | 예시 |
|------|-------------|----------|------|
| **동기 REST API** | 즉시 응답 필요 | HTTP/JSON | Distribution Service 배포 요청 |
| **Kafka Job Topics** | 장시간 비동기 작업 | Kafka 메시지 큐 | AI 추천, 이미지 생성 |
| **Kafka Event Topics** | 상태 변경 알림 | Kafka Pub/Sub | EventCreated, ParticipantRegistered |
| **Redis Cache** | 데이터 공유 | Redis Get/Set | AI 결과, 이미지 URL |

---

## 5. 보안 및 인증

### 5.1 JWT 기반 인증

**토큰 발급:**
- User Service에서 로그인/회원가입 시 JWT 토큰 발급
- 토큰 만료 시간: 7일
- Redis에 세션 정보 저장 (TTL 7일)

**토큰 검증:**
- API Gateway에서 모든 요청의 JWT 토큰 검증
- Authorization 헤더: `Bearer {token}`
- 검증 실패 시 401 Unauthorized 응답

**보호된 엔드포인트:**
- 모든 API (회원가입, 로그인, 이벤트 참여 제외)

### 5.2 민감 정보 암호화

- **비밀번호**: BCrypt 해싱 (Cost Factor: 10)
- **사업자번호**: AES-256-GCM 암호화
- **개인정보**: 전화번호 마스킹 (010-****-1234)

### 5.3 API Rate Limiting

- API Gateway에서 사용자당 100 req/min 제한
- Redis 기반 Rate Limiting 구현

---

## 6. 에러 처리

### 6.1 표준 에러 응답 포맷

```json
{
  "success": false,
  "errorCode": "ERROR_CODE",
  "message": "사용자 친화적인 에러 메시지",
  "details": "상세 에러 정보 (선택)",
  "timestamp": "2025-10-23T16:30:00Z"
}
```

### 6.2 HTTP 상태 코드

| 상태 코드 | 설명 | 사용 예시 |
|----------|------|----------|
| 200 OK | 성공 | GET 요청 성공 |
| 201 Created | 생성 성공 | POST 요청으로 리소스 생성 |
| 400 Bad Request | 잘못된 요청 | 유효성 검증 실패 |
| 401 Unauthorized | 인증 실패 | JWT 토큰 없음/만료 |
| 403 Forbidden | 권한 없음 | 접근 권한 부족 |
| 404 Not Found | 리소스 없음 | 존재하지 않는 이벤트 조회 |
| 409 Conflict | 충돌 | 중복 참여, 동시성 문제 |
| 500 Internal Server Error | 서버 오류 | 서버 내부 오류 |
| 503 Service Unavailable | 서비스 불가 | Circuit Breaker Open |

### 6.3 서비스별 주요 에러 코드

**User Service:**
- `USER_001`: 중복 사용자
- `USER_002`: 사업자번호 검증 실패
- `USER_003`: 사용자 없음
- `AUTH_001`: 인증 실패
- `AUTH_002`: 유효하지 않은 토큰

**Event Service:**
- `EVENT_001`: 이벤트 없음
- `EVENT_002`: 유효하지 않은 상태 전환
- `EVENT_003`: 필수 데이터 누락 (AI 추천, 이미지)
- `JOB_001`: Job 없음
- `JOB_002`: Job 실패

**Participation Service:**
- `PART_001`: 중복 참여
- `PART_002`: 이벤트 기간 아님
- `PART_003`: 참여자 없음

**Distribution Service:**
- `DIST_001`: 배포 실패
- `DIST_002`: Circuit Breaker Open

**Analytics Service:**
- `ANALYTICS_001`: 데이터 없음
- `EXTERNAL_API_ERROR`: 외부 API 장애

---

## 7. API 테스트 가이드

### 7.1 Swagger UI를 통한 테스트

**방법 1: Swagger Editor**
1. https://editor.swagger.io/ 접속
2. 각 서비스의 YAML 파일 내용 붙여넣기
3. 우측 Swagger UI에서 API 테스트

**방법 2: SwaggerHub**
1. 각 API 명세의 `servers` 섹션에 SwaggerHub Mock Server URL 포함
2. Mock Server를 통한 즉시 테스트 가능

**방법 3: Redocly**
```bash
# 각 API 명세 검증
npx @redocly/cli lint design/backend/api/*.yaml

# 문서 HTML 생성
npx @redocly/cli build-docs design/backend/api/user-service-api.yaml \
  --output docs/user-service-api.html
```

### 7.2 테스트 시나리오 예시

**1. 회원가입 → 로그인 → 이벤트 생성 플로우**
```bash
# 1. 회원가입
POST /api/users/register
{
  "name": "김사장",
  "phoneNumber": "010-1234-5678",
  "email": "owner@example.com",
  "password": "SecurePass123!",
  "store": {
    "name": "맛있는 고깃집",
    "industry": "RESTAURANT",
    "address": "서울시 강남구 테헤란로 123",
    "businessNumber": "123-45-67890"
  }
}

# 2. 로그인
POST /api/users/login
{
  "phoneNumber": "010-1234-5678",
  "password": "SecurePass123!"
}
# → JWT 토큰 수신

# 3. 이벤트 목적 선택
POST /api/events/objectives
Authorization: Bearer {token}
{
  "objective": "NEW_CUSTOMER_ACQUISITION"
}
# → eventId 수신

# 4. AI 추천 요청
POST /api/events/{eventId}/ai-recommendations
Authorization: Bearer {token}
# → jobId 수신

# 5. Job 상태 폴링 (5초 간격)
GET /api/jobs/{jobId}
Authorization: Bearer {token}
# → status: COMPLETED 확인

# 6. AI 추천 선택
PUT /api/events/{eventId}/recommendations
Authorization: Bearer {token}
{
  "selectedOption": 1,
  "customization": {
    "title": "봄맞이 삼겹살 50% 할인 이벤트",
    "prizeName": "삼겹살 1인분 무료"
  }
}

# ... (이미지 생성, 배포 채널 선택, 최종 승인)
```

### 7.3 Mock 데이터 활용

- 모든 API 명세에 example 데이터 포함
- Swagger UI의 "Try it out" 기능으로 즉시 테스트
- 성공/실패 시나리오 모두 example 제공

### 7.4 통합 테스트 도구

**Postman Collection 생성:**
```bash
# OpenAPI 명세를 Postman Collection으로 변환
npx openapi-to-postmanv2 -s design/backend/api/user-service-api.yaml \
  -o postman/user-service-collection.json
```

**Newman (CLI 테스트 실행):**
```bash
# Postman Collection 실행
newman run postman/user-service-collection.json \
  --environment postman/dev-environment.json
```

---

## 부록

### A. 파일 통계

| 서비스 | 파일명 | 크기 | 라인 수 | API 수 |
|--------|--------|------|--------|--------|
| User | user-service-api.yaml | 31KB | 1,011 | 7 |
| Event | event-service-api.yaml | 41KB | 1,373 | 14 |
| AI | ai-service-api.yaml | 26KB | 847 | 3 |
| Content | content-service-api.yaml | 37KB | 1,158 | 6 |
| Distribution | distribution-service-api.yaml | 21KB | 653 | 2 |
| Participation | participation-service-api.yaml | 25KB | 820 | 5 |
| Analytics | analytics-service-api.yaml | 28KB | 1,050 | 4 |
| **합계** | - | **209KB** | **6,912** | **41** |

### B. 주요 의사결정

1. **OpenAPI 3.0 표준 채택**: 업계 표준 준수, 자동 코드 생성 지원
2. **서비스별 독립 명세**: 서비스 독립성 보장, 독립 배포 가능
3. **유저스토리 기반 설계**: x-user-story 필드로 추적성 확보
4. **Example 데이터 포함**: Swagger UI 즉시 테스트 가능
5. **JWT 인증 표준화**: 모든 서비스에서 일관된 인증 방식
6. **에러 응답 표준화**: 일관된 에러 응답 포맷
7. **Kafka + Redis 통합**: Event-Driven 아키텍처 지원
8. **Circuit Breaker 패턴**: 외부 API 장애 대응

### C. 다음 단계

1. **외부 시퀀스 설계**: 서비스 간 API 호출 흐름 상세 설계
2. **내부 시퀀스 설계**: 서비스 내부 컴포넌트 간 호출 흐름 설계
3. **클래스 설계**: 서비스별 클래스 다이어그램 작성
4. **데이터 설계**: 서비스별 데이터베이스 스키마 설계
5. **백엔드 개발**: OpenAPI 명세 기반 코드 생성 및 구현

---

**문서 버전**: 1.0
**최종 수정일**: 2025-10-23
**작성자**: System Architect