mirror of https://github.com/ktds-dg0501/kt-event-marketing.git synced 2025-12-06 10:46:23 +00:00

cherry2250 b9745f24e5 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>

2025-10-23 16:56:54 +09:00

23 KiB

Raw Blame History

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

문서 정보

작성일: 2025-10-23
버전: 1.0
작성자: System Architect
관련 문서:

1. 개요

1.1 설계 범위

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

1.2 마이크로서비스 구성

User Service: 사용자 인증 및 매장정보 관리
Event Service: 이벤트 전체 생명주기 관리
AI Service: AI 기반 이벤트 추천
Content Service: SNS 콘텐츠 생성
Distribution Service: 다중 채널 배포 관리
Participation Service: 이벤트 참여 및 당첨자 관리
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: 이벤트 기획안 (컨셉, 경품, 참여방법, 예상성과)

파일: 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 표준 에러 응답 포맷

{
  "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

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

방법 2: SwaggerHub

각 API 명세의 servers 섹션에 SwaggerHub Mock Server URL 포함
Mock Server를 통한 즉시 테스트 가능

방법 3: Redocly

# 각 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. 회원가입 → 로그인 → 이벤트 생성 플로우

# 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 생성:

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

Newman (CLI 테스트 실행):

# 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. 주요 의사결정

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

C. 다음 단계

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

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

23 KiB Raw Blame History

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

문서 정보

목차

1. 개요

1.1 설계 범위

1.2 마이크로서비스 구성

1.3 파일 구조

2. API 설계 원칙

2.1 OpenAPI 3.0 표준 준수

2.2 RESTful 설계

2.3 유저스토리 기반 설계

2.4 서비스 독립성

2.5 Example 데이터 제공

3. 서비스별 API 명세

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

API 엔드포인트 (7개)

주요 기능

주요 스키마

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

API 엔드포인트 (14개)

주요 기능

주요 스키마

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

API 엔드포인트 (3개)

Kafka Consumer (비동기 처리)

주요 기능

주요 스키마

3.4 Content Service (SNS 콘텐츠 생성)

API 엔드포인트 (6개)

Kafka Consumer (비동기 처리)

주요 기능

주요 스키마

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

API 엔드포인트 (2개)

주요 기능

주요 스키마

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

API 엔드포인트 (5개)

주요 기능

주요 스키마

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

API 엔드포인트 (4개)

Kafka Event 구독

주요 기능

주요 스키마

4. API 통합 가이드

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

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

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

4.4 서비스 간 통신 패턴

5. 보안 및 인증

5.1 JWT 기반 인증

5.2 민감 정보 암호화

5.3 API Rate Limiting

6. 에러 처리

6.1 표준 에러 응답 포맷

6.2 HTTP 상태 코드

6.3 서비스별 주요 에러 코드

7. API 테스트 가이드

7.1 Swagger UI를 통한 테스트

7.2 테스트 시나리오 예시

7.3 Mock 데이터 활용

7.4 통합 테스트 도구

부록

A. 파일 통계

B. 주요 의사결정

C. 다음 단계

23 KiB

Raw Blame History