kt-event-marketing/README.md

KT 이벤트 파트너

AI 기반 이벤트 자동 생성 및 관리 서비스의 백엔드 시스템

마이크로서비스 아키텍처 기반으로 설계된 확장 가능한 이벤트 관리 플랫폼

🚀 빠른 시작 (Quick Start)

사전 요구사항

Java 21, Gradle 8.x, Docker & Docker Compose

3단계 실행

# 1. 백킹 서비스 시작 (PostgreSQL, Redis, Kafka)
docker-compose up -d

# 2. 프로젝트 빌드
./gradlew clean build -x test

# 3. 서비스 실행 (IntelliJ 실행 프로파일 또는 명령줄)
# IntelliJ: .run/*.run.xml 프로파일 사용
# 명령줄: java -jar {service-name}/build/libs/{service-name}.jar

동작 확인

# Health Check
curl http://localhost:8080/actuator/health  # Event Service
curl http://localhost:8081/actuator/health  # User Service

# Swagger UI
http://localhost:8080/swagger-ui.html

---

📋 목차

• 1. 소개
• 2. 프로젝트 구조
• 3. 시스템 아키텍처
• 4. 로컬 개발 환경 설정
• 5. Docker 컨테이너 빌드 및 실행
• 6. Kubernetes 배포
• 7. CI/CD
• 8. 테스트
• 9. 모니터링 및 로깅
• 10. 트러블슈팅
• 11. 개발 참고 자료
• 12. 팀
• 13. 라이선스
• 14. 문의

---

1. 소개

KT AI 기반 소상공인 이벤트 자동 생성 서비스는 고객 유치와 매출 증대를 위한 이벤트를 하고 싶지만, 기획·제작·운영 역량과 시간이 부족한 소상공인 및 중소기업의 업무를 지원하는 AI 기반 자동화 서비스입니다.

본 저장소는 백엔드 마이크로서비스를 포함하며, Spring Boot 3.3.0 기반의 7개 독립 서비스로 구성됩니다.

1.1 관련 저장소

구분	설명	저장소 URL
사내 통합	설계 문서 및 통합 관리	https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing
백엔드	Spring Boot 마이크로서비스 (현재 저장소)	https://github.com/ktds-dg0501/kt-event-marketing
프론트엔드	React 기반 웹 애플리케이션	https://github.com/ktds-dg0501/kt-event-marketing-fe
K8s Manifest	Kubernetes 배포 매니페스트	{Manifest Repo}

1.2 핵심 기능

• AI 이벤트 기획: 업종과 목적에 맞는 이벤트 자동 기획
• 이벤트 콘텐츠 생성: AI 기반 이미지 및 텍스트 콘텐츠 자동 생성
• 참여자 관리: 이벤트 참여자 등록 및 당첨자 추첨 자동화
• 실시간 분석: 이벤트 진행 상황 및 성과 실시간 모니터링
• 다채널 배포: 다양한 채널로 이벤트 자동 배포

1.3 MVP 산출물

• 발표자료: {발표자료 링크}
• 설계결과:
  • 유저스토리
  • UI/UX 설계서
  • 아키텍처 패턴
  • High-Level 아키텍처
  • API 설계서
  • 논리 아키텍처
  • 시퀀스 설계
  • 클래스 설계
  • 데이터베이스 설계
  • 프론트엔드 설계
• Git Repository:
  • 사내 통합 저장소: https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing
  • 백엔드 (GitHub): https://github.com/ktds-dg0501/kt-event-marketing.git
  • 프론트엔드 (GitHub): https://github.com/ktds-dg0501/kt-event-marketing-fe.git
  • K8s Manifest: {Manifest Repo}
• 시연 동영상: {시연 동영상 링크}

2. 프로젝트 구조

2.1 디렉토리 구조

kt-event-marketing/
├── user-service/              # 사용자 인증 및 회원 관리
├── event-service/             # 이벤트 생성, 관리, 스케줄링
├── content-service/           # AI 콘텐츠 생성 (Python)
├── ai-service/                # AI 이벤트 추천 및 분석
├── participation-service/     # 참여자 관리 및 당첨자 추첨
├── analytics-service/         # 통계 분석
├── distribution-service/      # 다채널 배포
├── .run/                      # IntelliJ 실행 프로파일
├── design/                    # 설계 문서
│   ├── userstory.md
│   ├── uiux/
│   ├── backend/
│   │   ├── api/              # API 설계서
│   │   ├── logical/          # 논리 아키텍처
│   │   ├── sequence/         # 시퀀스 다이어그램
│   │   ├── class/            # 클래스 다이어그램
│   │   └── database/         # 데이터베이스 설계
│   ├── frontend/
│   ├── pattern/
│   └── high-level-architecture.md
├── deployment/
│   ├── container/            # Docker 관련 파일
│   ├── k8s/                  # Kubernetes 매니페스트
│   └── cicd/                 # CI/CD 파이프라인
├── docker-compose.yml        # 백킹 서비스 실행
└── README.md                 # 본 문서

3. 시스템 아키텍처

3.1 전체 구조

마이크로서비스 아키텍처 기반의 백엔드 서비스와 React 기반 프론트엔드로 구성된 웹 애플리케이션

┌─────────────────┐
│  프론트엔드      │
│  (React)        │
└────────┬────────┘
         │
    ┌────┴─────────────────────────────┐
    │     API Gateway (Ingress)        │
    └────┬─────────────────────────────┘
         │
    ┌────┴────────────────────────────────────────────┐
    │                  백엔드 서비스                    │
    ├──────────┬──────────┬──────────┬──────────────┤
    │  User    │  Event   │  Content │  Participation│
    │ Service  │ Service  │ Service  │   Service     │
    ├──────────┼──────────┼──────────┼──────────────┤
    │   AI     │Analytics │Distribution│             │
    │ Service  │ Service  │  Service  │              │
    └──────────┴──────────┴──────────┴──────────────┘
         │           │           │
    ┌────┴───────────┴───────────┴────┐
    │  백킹 서비스                      │
    ├──────────┬──────────┬───────────┤
    │PostgreSQL│  Redis   │   Kafka   │
    └──────────┴──────────┴───────────┘

3.2 마이크로서비스 구성

서비스	포트	설명	API Path
user-service	8081	사용자 인증 및 회원 관리	/api/v1/users
event-service	8080	이벤트 생성 및 관리, 스케줄링	/api/v1/events, /api/v1/jobs
content-service	8085	AI 기반 콘텐츠 생성 (이미지, 텍스트)	/api/v1/content
ai-service	8083	AI 이벤트 추천 및 분석	/api/v1/ai-service
participation-service	8084	이벤트 참여자 관리 및 당첨자 추첨	/api/v1/participations, /api/v1/winners
analytics-service	8086	이벤트 및 사용자 통계 분석	/api/v1/events/.../analytics, /api/v1/users/.../analytics
distribution-service	8087	다채널 이벤트 배포	/api/v1/distribution

4.3 기술 스택

• 백엔드:
  • Java 21
  • Spring Boot 3.3.0
  • Spring Data JPA
  • Spring Security
  • Spring Kafka
  • MapStruct
  • OpenAPI (Swagger)
• 프론트엔드: {React 버전 및 주요 라이브러리}
• 인프라:
  • Azure Kubernetes Service (AKS)
  • Azure Container Registry (ACR)
  • Ingress Controller
• CI/CD: GitHub Actions, Jenkins
• 백킹 서비스:
  • Database: PostgreSQL (서비스별 독립 DB)
  • Cache: Redis (서비스별 독립 DB)
  • Message Queue: Apache Kafka

4. 로컬 개발 환경 설정

4.1 사전 요구사항

• Java 21
• Gradle 8.x
• Docker & Docker Compose
• PostgreSQL, Redis, Kafka (Docker로 설치 가능)

4.2 백킹 서비스 설치

4.2.1 Docker Compose로 백킹 서비스 설치

프로젝트 루트에 있는 docker-compose.yml 사용:

# 모든 백킹 서비스 시작 (PostgreSQL, Redis, Kafka)
docker-compose up -d

# 상태 확인
docker-compose ps

# 로그 확인
docker-compose logs -f

4.2.2 개별 설치 (선택사항)

PostgreSQL 설치

# 각 서비스별 데이터베이스 생성
docker run -d \
  --name postgres-user \
  -e POSTGRES_USER=admin \
  -e POSTGRES_PASSWORD=Passw0rd \
  -e POSTGRES_DB=user_db \
  -p 5432:5432 \
  postgres:15

docker run -d \
  --name postgres-event \
  -e POSTGRES_USER=admin \
  -e POSTGRES_PASSWORD=Passw0rd \
  -e POSTGRES_DB=event_db \
  -p 5433:5432 \
  postgres:15

docker run -d \
  --name postgres-participation \
  -e POSTGRES_USER=admin \
  -e POSTGRES_PASSWORD=Passw0rd \
  -e POSTGRES_DB=participation_db \
  -p 5434:5432 \
  postgres:15

docker run -d \
  --name postgres-analytics \
  -e POSTGRES_USER=admin \
  -e POSTGRES_PASSWORD=Passw0rd \
  -e POSTGRES_DB=analytics_db \
  -p 5435:5432 \
  postgres:15

Redis 설치

docker run -d \
  --name redis \
  -p 6379:6379 \
  redis:7-alpine

Kafka 설치

# Zookeeper
docker run -d \
  --name zookeeper \
  -p 2181:2181 \
  -e ZOOKEEPER_CLIENT_PORT=2181 \
  confluentinc/cp-zookeeper:latest

# Kafka
docker run -d \
  --name kafka \
  -p 9092:9092 \
  -e KAFKA_ZOOKEEPER_CONNECT=localhost:2181 \
  -e KAFKA_ADVERTISED_LISTENERS=PLAINTEXT://localhost:9092 \
  -e KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR=1 \
  confluentinc/cp-kafka:latest

4.3 애플리케이션 빌드 및 실행

4.3.1 전체 프로젝트 빌드

# 프로젝트 루트에서 실행
./gradlew clean build -x test

# 테스트 포함 빌드
./gradlew clean build

4.3.2 개별 서비스 빌드 및 실행

서비스별 빌드

# User Service
./gradlew :user-service:clean :user-service:build -x test

# Event Service
./gradlew :event-service:clean :event-service:build -x test

# Content Service (Python)
cd content-service
pip install -r requirements.txt

# AI Service
./gradlew :ai-service:clean :ai-service:build -x test

# Participation Service
./gradlew :participation-service:clean :participation-service:build -x test

# Analytics Service
./gradlew :analytics-service:clean :analytics-service:build -x test

# Distribution Service
./gradlew :distribution-service:clean :distribution-service:build -x test

서비스 실행

IntelliJ IDEA를 사용하는 경우:

1. .run 디렉토리에 있는 실행 프로파일 사용
2. 각 서비스별 실행 프로파일 선택 후 실행

명령줄에서 실행:

# User Service
java -jar user-service/build/libs/user-service.jar

# Event Service
java -jar event-service/build/libs/event-service.jar

# Content Service (Python)
cd content-service
python app.py

# AI Service
java -jar ai-service/build/libs/ai-service.jar

# Participation Service
java -jar participation-service/build/libs/participation-service.jar

# Analytics Service
java -jar analytics-service/build/libs/analytics-service.jar

# Distribution Service
java -jar distribution-service/build/libs/distribution-service.jar

4.3.3 서비스 동작 확인

# User Service Health Check
curl http://localhost:8081/actuator/health

# Event Service Health Check
curl http://localhost:8080/actuator/health

# Content Service Health Check
curl http://localhost:8085/health

# AI Service Health Check
curl http://localhost:8083/actuator/health

# Participation Service Health Check
curl http://localhost:8084/actuator/health

# Analytics Service Health Check
curl http://localhost:8086/actuator/health

# Distribution Service Health Check
curl http://localhost:8087/actuator/health

4.3.4 API 문서 확인

각 서비스의 Swagger UI 접근:

• User Service: http://localhost:8081/swagger-ui.html
• Event Service: http://localhost:8080/swagger-ui.html
• AI Service: http://localhost:8083/swagger-ui.html
• Participation Service: http://localhost:8084/swagger-ui.html
• Analytics Service: http://localhost:8086/swagger-ui.html
• Distribution Service: http://localhost:8087/swagger-ui.html

5. Docker 컨테이너 빌드 및 실행

5.1 컨테이너 이미지 빌드

5.1.1 Java 서비스 이미지 빌드

# User Service
docker build \
  --build-arg SERVICE_NAME=user-service \
  -f user-service/Dockerfile \
  -t acrdigitalgarage01.azurecr.io/kt-event/user-service:latest .

# Event Service
docker build \
  --build-arg SERVICE_NAME=event-service \
  -f event-service/Dockerfile \
  -t acrdigitalgarage01.azurecr.io/kt-event/event-service:latest .

# AI Service
docker build \
  --build-arg SERVICE_NAME=ai-service \
  -f ai-service/Dockerfile \
  -t acrdigitalgarage01.azurecr.io/kt-event/ai-service:latest .

# Participation Service
docker build \
  --build-arg SERVICE_NAME=participation-service \
  -f participation-service/Dockerfile \
  -t acrdigitalgarage01.azurecr.io/kt-event/participation-service:latest .

# Analytics Service
docker build \
  --build-arg SERVICE_NAME=analytics-service \
  -f analytics-service/Dockerfile \
  -t acrdigitalgarage01.azurecr.io/kt-event/analytics-service:latest .

# Distribution Service
docker build \
  --build-arg SERVICE_NAME=distribution-service \
  -f distribution-service/Dockerfile \
  -t acrdigitalgarage01.azurecr.io/kt-event/distribution-service:latest .

5.1.2 Python 서비스 이미지 빌드

# Content Service
docker build \
  -f content-service/Dockerfile \
  -t acrdigitalgarage01.azurecr.io/kt-event/content-service:latest \
  content-service/

5.2 컨테이너 실행

5.2.1 Docker Compose로 전체 실행

# deployment/container 디렉토리로 이동
cd deployment/container

# 전체 서비스 시작
docker-compose up -d

# 상태 확인
docker-compose ps

# 로그 확인
docker-compose logs -f

5.2.2 개별 컨테이너 실행

# User Service
docker run -d \
  --name user-service \
  -p 8081:8081 \
  -e DB_HOST=host.docker.internal \
  -e DB_PORT=5432 \
  -e DB_NAME=user_db \
  -e REDIS_HOST=host.docker.internal \
  -e KAFKA_BOOTSTRAP_SERVERS=host.docker.internal:9092 \
  acrdigitalgarage01.azurecr.io/kt-event/user-service:latest

# Event Service
docker run -d \
  --name event-service \
  -p 8080:8080 \
  -e DB_HOST=host.docker.internal \
  -e DB_PORT=5433 \
  -e DB_NAME=event_db \
  -e REDIS_HOST=host.docker.internal \
  -e KAFKA_BOOTSTRAP_SERVERS=host.docker.internal:9092 \
  acrdigitalgarage01.azurecr.io/kt-event/event-service:latest

자세한 컨테이너 실행 가이드는 run-container-guide-back.md를 참조하세요.

6. Kubernetes 배포

6.1 사전 요구사항

• Azure CLI 설치 및 로그인
• kubectl 설치
• AKS 클러스터 접근 권한

6.2 Azure 로그인 및 AKS 연결

# Azure 로그인
az login

# AKS Credential 가져오기
az aks get-credentials \
  --resource-group rg-digitalgarage-01 \
  --name aks-digitalgarage-01

# 연결 확인
kubectl cluster-info

6.3 네임스페이스 생성

# 네임스페이스 생성
kubectl create namespace kt-event-marketing

# 네임스페이스 확인
kubectl get namespace kt-event-marketing

6.4 백킹 서비스 설치 (Kubernetes)

6.4.1 PostgreSQL 설치

# Helm 저장소 추가
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

# User Service용 DB
helm install user-postgresql bitnami/postgresql \
  --namespace kt-event-marketing \
  --set global.postgresql.auth.postgresPassword=Passw0rd \
  --set global.postgresql.auth.username=admin \
  --set global.postgresql.auth.password=Passw0rd \
  --set global.postgresql.auth.database=user_db

# Event Service용 DB
helm install event-postgresql bitnami/postgresql \
  --namespace kt-event-marketing \
  --set global.postgresql.auth.postgresPassword=Passw0rd \
  --set global.postgresql.auth.username=admin \
  --set global.postgresql.auth.password=Passw0rd \
  --set global.postgresql.auth.database=event_db

# Participation Service용 DB
helm install participation-postgresql bitnami/postgresql \
  --namespace kt-event-marketing \
  --set global.postgresql.auth.postgresPassword=Passw0rd \
  --set global.postgresql.auth.username=admin \
  --set global.postgresql.auth.password=Passw0rd \
  --set global.postgresql.auth.database=participation_db

# Analytics Service용 DB
helm install analytics-postgresql bitnami/postgresql \
  --namespace kt-event-marketing \
  --set global.postgresql.auth.postgresPassword=Passw0rd \
  --set global.postgresql.auth.username=admin \
  --set global.postgresql.auth.password=Passw0rd \
  --set global.postgresql.auth.database=analytics_db

6.4.2 Redis 설치

helm install redis bitnami/redis \
  --namespace kt-event-marketing \
  --set auth.password=Passw0rd \
  --set master.persistence.enabled=false \
  --set replica.replicaCount=0

6.4.3 Kafka 설치

helm install kafka bitnami/kafka \
  --namespace kt-event-marketing \
  --set persistence.enabled=false \
  --set zookeeper.persistence.enabled=false

6.5 컨테이너 이미지 푸시

6.5.1 ACR 로그인

az acr login --name acrdigitalgarage01

6.5.2 이미지 푸시

# 모든 서비스 이미지 푸시
docker push acrdigitalgarage01.azurecr.io/kt-event/user-service:latest
docker push acrdigitalgarage01.azurecr.io/kt-event/event-service:latest
docker push acrdigitalgarage01.azurecr.io/kt-event/content-service:latest
docker push acrdigitalgarage01.azurecr.io/kt-event/ai-service:latest
docker push acrdigitalgarage01.azurecr.io/kt-event/participation-service:latest
docker push acrdigitalgarage01.azurecr.io/kt-event/analytics-service:latest
docker push acrdigitalgarage01.azurecr.io/kt-event/distribution-service:latest

6.6 Kubernetes 매니페스트 배포

6.6.1 Secret 및 ConfigMap 생성

# Common Secret 생성
kubectl apply -f deployment/k8s/common/secret-common.yaml -n kt-event-marketing

# Common ConfigMap 생성
kubectl apply -f deployment/k8s/common/cm-common.yaml -n kt-event-marketing

# Image Pull Secret 생성
kubectl apply -f deployment/k8s/common/secret-imagepull.yaml -n kt-event-marketing

6.6.2 서비스별 배포

# User Service
kubectl apply -f deployment/k8s/user-service/ -n kt-event-marketing

# Event Service
kubectl apply -f deployment/k8s/event-service/ -n kt-event-marketing

# Content Service
kubectl apply -f deployment/k8s/content-service/ -n kt-event-marketing

# AI Service
kubectl apply -f deployment/k8s/ai-service/ -n kt-event-marketing

# Participation Service
kubectl apply -f deployment/k8s/participation-service/ -n kt-event-marketing

# Analytics Service
kubectl apply -f deployment/k8s/analytics-service/ -n kt-event-marketing

# Distribution Service
kubectl apply -f deployment/k8s/distribution-service/ -n kt-event-marketing

# Ingress 생성
kubectl apply -f deployment/k8s/common/ingress.yaml -n kt-event-marketing

6.6.3 배포 확인

# Pod 상태 확인
kubectl get pods -n kt-event-marketing

# Service 확인
kubectl get svc -n kt-event-marketing

# Ingress 확인
kubectl get ingress -n kt-event-marketing

# Pod 로그 확인
kubectl logs -f <pod-name> -n kt-event-marketing

자세한 Kubernetes 배포 가이드는 deploy-k8s-guide.md를 참조하세요.

7. CI/CD

7.1 GitHub Actions CI/CD

GitHub Actions를 사용한 자동 빌드 및 배포 파이프라인이 구성되어 있습니다.

워크플로우 파일: .github/workflows/

주요 단계:

1. 코드 체크아웃
2. Java 환경 설정
3. Gradle 빌드
4. Docker 이미지 빌드
5. ACR에 이미지 푸시
6. AKS에 배포

7.2 Jenkins CI/CD

Jenkins를 사용한 CI/CD 파이프라인 구성이 가능합니다.

자세한 CI/CD 가이드는 CICD-GUIDE.md를 참조하세요.

8. 테스트

8.1 프론트엔드 접근

# Ingress External IP 확인
kubectl get ingress -n kt-event-marketing

# 브라우저에서 접근
http://<INGRESS_EXTERNAL_IP>

8.2 API 테스트

# User Service API 테스트
curl http://<INGRESS_EXTERNAL_IP>/api/v1/users/health

# Event Service API 테스트
curl http://<INGRESS_EXTERNAL_IP>/api/v1/events

# API 문서 확인
http://<INGRESS_EXTERNAL_IP>/api/v1/users/swagger-ui.html

8.3 테스트 계정

• ID: dodari@naver.com
• PW: p123456789

9. 모니터링 및 로깅

9.1 애플리케이션 로그 확인

# 특정 서비스 로그 확인
kubectl logs -f deployment/user-service -n kt-event-marketing

# 전체 로그 스트리밍
kubectl logs -f -l app=kt-event-marketing -n kt-event-marketing

9.2 Health Check

각 서비스는 Spring Boot Actuator를 통해 헬스 체크를 제공합니다:

• /actuator/health: 서비스 헬스 상태
• /actuator/info: 서비스 정보
• /actuator/metrics: 메트릭 정보

10. 트러블슈팅

10.1 일반적인 문제

문제: Pod가 CrashLoopBackOff 상태

# Pod 상세 정보 확인
kubectl describe pod <pod-name> -n kt-event-marketing

# 로그 확인
kubectl logs <pod-name> -n kt-event-marketing

# 이전 컨테이너 로그 확인
kubectl logs <pod-name> -n kt-event-marketing --previous

문제: 데이터베이스 연결 실패

• Secret 및 ConfigMap의 환경 변수 확인
• 데이터베이스 서비스 상태 확인
• 네트워크 정책 및 방화벽 규칙 확인

문제: 이미지 Pull 실패

• ACR 로그인 확인
• Image Pull Secret 확인
• 이미지 이름 및 태그 확인

10.2 유용한 명령어

# 전체 리소스 확인
kubectl get all -n kt-event-marketing

# 특정 리소스 재시작
kubectl rollout restart deployment/<service-name> -n kt-event-marketing

# ConfigMap 확인
kubectl get configmap -n kt-event-marketing

# Secret 확인
kubectl get secret -n kt-event-marketing

11. 개발 참고 자료

11.1 프로젝트 문서

• 유저스토리
• UI/UX 설계서
• 아키텍처 패턴
• High-Level 아키텍처
• API 설계서
• 논리 아키텍처
• 시퀀스 설계
• 클래스 설계
• 데이터베이스 설계서
• 프론트엔드 설계
• 개발 변경 이력

11.2 가이드 문서

• 백킹 서비스 설치 방법
• 컨테이너 이미지 빌드
• Kubernetes 배포 가이드
• CI/CD 가이드

12. 팀

• Product Owner, Content Service Developer: 김채리 (체리)
• Scrum Master, Participation Service Developer: 김도연 (도다리)
• DevOps Engineer, User Service Developer: 장원호 (티모)
• Analytics Service Developer: 양효원 (와와)
• AI Service Developer: 박세원 (뚜이)
• Event Service Developer: 송하영 (홍차)
• Distribution Service Developer: 이선민 (복치)