kt-event-marketing-fe/README.md

KT 이벤트 파트너

• AI 기반 소상공인 마케팅 지원 서비스

1. 소개

KT 이벤트 파트너는 소상공인이 AI를 활용하여 효과적인 이벤트를 쉽게 기획하고 관리할 수 있도록 지원하는 플랫폼입니다. 매장 정보와 AI 추천을 기반으로 이벤트를 생성하고, SNS 콘텐츠를 자동 생성하며, 다양한 채널로 배포하고, 실시간으로 성과를 분석할 수 있습니다.

1.1 핵심 기능

• AI 기반 이벤트 추천: 매장 정보, 업종, 지역 트렌드를 분석하여 최적의 이벤트 아이디어 제공
• 자동 콘텐츠 생성: AI가 생성한 이벤트 내용을 바탕으로 SNS 이미지 자동 생성
• 다중 채널 배포: KT 유휴 채널(우리동네TV, 링고비즈, 지니TV)과 다양한 SNS 채널로 원클릭 배포
• 참여자 관리: 이벤트 참여자 접수 및 당첨자 추첨 기능
• 실시간 성과 분석: 조회수, 참여율, ROI 등 실시간 대시보드 제공

1.2 MVP 산출물

• 발표자료: https://www.miricanvas.com/v2/design2/v/7102e2d0-53b3-4a4a-9c93-7042a7706357
• 설계결과:
  • 유저스토리
  • 논리 아키텍처
  • UI/UX 설계서
  • API 설계서
• Git Repo:
  • 프론트엔드: https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing-fe.git
  • 백엔드: https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing.git
• 시연 동영상: https://drive.google.com/file/d/1VYd7NEG-DBdSKyU7hRtVfAaNHF4lBpWy/view?usp=sharing

2. 시스템 아키텍처

2.1 전체 구조

프론트엔드(Next.js)와 마이크로서비스 백엔드(Spring Boot)로 구성된 애플리케이션입니다. Event-Driven 아키텍처와 CQRS 패턴을 적용하여 확장성과 성능을 고려한 설계입니다.

2.2 마이크로서비스 구성

• User Service: 사용자 인증 및 매장정보 관리
• Event Service: 이벤트 생성, 수정, 삭제, 조회 및 전체 플로우 오케스트레이션
• AI Service: AI 기반 트렌드 분석 및 이벤트 추천
• Content Service: SNS 콘텐츠(이미지) 자동 생성
• Distribution Service: 다중 채널(네이버, 카카오톡, 인스타그램) 배포
• Participation Service: 이벤트 참여자 접수 및 당첨자 관리
• Analytics Service: 실시간 성과 분석 및 통합 대시보드

2.3 기술 스택

• 프론트엔드: Next.js 14, React 18, TypeScript 5, Material UI v6, React Query, Zustand 4.5
• 백엔드: Spring Boot 3.3, Java 21, Kafka (Event Bus + Job Queue)
• 인프라: Azure Kubernetes Service (AKS), Azure Container Registry (ACR)
• CI/CD: GitHub Actions, Argo CD
• 백킹 서비스:
  • Database: PostgreSQL
  • Cache: Redis
  • Message Queue: Kafka

3. 로컬 실행 가이드

3.1 사전 요구사항

• Node.js: 18.x 이상
• npm: 9.x 이상
• Git: 2.x 이상

3.2 프로젝트 클론

git clone https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing-fe.git
cd kt-event-marketing-fe

git clone https://gitea.cbiz.kubepia.net/shared-dg05-dodari/kt-event-marketing.git
cd kt-event-marketing

3.3 환경 변수 설정

.env.example 파일을 복사하여 .env.local 파일을 생성합니다:

cp .env.example .env.local

.env.local 파일을 열어 백엔드 API 호스트를 설정합니다:

# API Hosts (로컬 개발 환경)
NEXT_PUBLIC_USER_HOST=http://localhost:8081
NEXT_PUBLIC_EVENT_HOST=http://localhost:8080
NEXT_PUBLIC_CONTENT_HOST=http://localhost:8084
NEXT_PUBLIC_AI_HOST=http://localhost:8083
NEXT_PUBLIC_PARTICIPATION_HOST=http://localhost:8084
NEXT_PUBLIC_DISTRIBUTION_HOST=http://localhost:8085
NEXT_PUBLIC_ANALYTICS_HOST=http://localhost:8086

# API Version prefix
NEXT_PUBLIC_API_VERSION=api

참고: 백엔드 서비스가 다른 포트나 호스트에서 실행 중이라면 해당 주소로 변경하세요.

3.4 의존성 설치

npm install

3.5 개발 서버 실행

npm run dev

브라우저에서 http://localhost:3000으로 접속하여 애플리케이션을 확인합니다.

3.6 빌드 및 타입 체크

# TypeScript 타입 체크
npm run type-check

# 프로덕션 빌드
npm run build

# 프로덕션 서버 실행
npm run start

4. Docker 빌드 및 로컬 실행

4.1 Docker 이미지 빌드

docker build -t kt-event-marketing-frontend:latest .

4.2 Docker 컨테이너 실행

docker run -p 8080:8080 kt-event-marketing-frontend:latest

브라우저에서 http://localhost:8080으로 접속합니다.

4.3 Health Check 확인

curl http://localhost:8080/health

5. Kubernetes 배포 가이드

5.1 사전 준비

5.1.1 Azure 로그인

az login
az account show

5.1.2 AKS 자격 증명 설정

az aks get-credentials --resource-group <리소스그룹명> --name aks-digitalgarage-01
kubectl cluster-info

5.1.3 Namespace 생성

kubectl create namespace kt-event-marketing

5.1.4 ImagePullSecret 생성

ACR에서 이미지를 가져오기 위한 시크릿을 생성합니다:

kubectl create secret docker-registry kt-event-marketing-frontend \
  --docker-server=acrdigitalgarage01.azurecr.io \
  --docker-username=<ACR_USERNAME> \
  --docker-password=<ACR_PASSWORD> \
  --namespace=kt-event-marketing

5.2 이미지 빌드 및 푸시

5.2.1 이미지 빌드

docker build -t kt-event-marketing-frontend:latest .

5.2.2 ACR 태깅

docker tag kt-event-marketing-frontend:latest \
  acrdigitalgarage01.azurecr.io/kt-event-marketing/kt-event-marketing-frontend:latest

5.2.3 ACR 로그인

az acr login --name acrdigitalgarage01

5.2.4 이미지 푸시

docker push acrdigitalgarage01.azurecr.io/kt-event-marketing/kt-event-marketing-frontend:latest

5.3 Kubernetes 배포

5.3.1 ConfigMap 수정 (선택 사항)

배포 환경에 맞게 백엔드 API 호스트를 수정합니다:

# ConfigMap 편집
kubectl edit configmap cm-kt-event-marketing-frontend -n kt-event-marketing

또는 deployment/k8s/configmap.yaml 파일을 직접 수정한 후 적용합니다.

5.3.2 매니페스트 적용

# 모든 매니페스트 일괄 적용
kubectl apply -f deployment/k8s/

또는 개별적으로 적용:

kubectl apply -f deployment/k8s/configmap.yaml
kubectl apply -f deployment/k8s/service.yaml
kubectl apply -f deployment/k8s/deployment.yaml
kubectl apply -f deployment/k8s/ingress.yaml

5.4 배포 확인

5.4.1 Pod 상태 확인

kubectl get pods -n kt-event-marketing -l app=kt-event-marketing-frontend

5.4.2 Service 확인

kubectl get svc kt-event-marketing-frontend -n kt-event-marketing

5.4.3 Ingress 확인

kubectl get ingress kt-event-marketing-frontend -n kt-event-marketing

5.4.4 로그 확인

kubectl logs -n kt-event-marketing -l app=kt-event-marketing-frontend --tail=100 -f

5.5 접속 테스트

1. 프론트 페이지 주소 구하기:

kubens {namespace}
k get svc 

2. 로그인

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

참고: External IP는 환경에 따라 다를 수 있습니다. 다음 명령으로 확인하세요:

kubectl get svc ingress-nginx-controller -n ingress-nginx

6. 재배포 가이드

6.1 코드 수정 후 재배포

# 1. 이미지 빌드
docker build -t kt-event-marketing-frontend:latest .

# 2. ACR 태깅
docker tag kt-event-marketing-frontend:latest \
  acrdigitalgarage01.azurecr.io/kt-event-marketing/kt-event-marketing-frontend:latest

# 3. 이미지 푸시
docker push acrdigitalgarage01.azurecr.io/kt-event-marketing/kt-event-marketing-frontend:latest

# 4. Kubernetes Deployment 재시작
kubectl rollout restart deployment kt-event-marketing-frontend -n kt-event-marketing

# 5. 롤아웃 상태 확인
kubectl rollout status deployment/kt-event-marketing-frontend -n kt-event-marketing

6.2 ConfigMap 수정 후 재배포

# ConfigMap 수정
kubectl apply -f deployment/k8s/configmap.yaml

# Pod 재시작
kubectl rollout restart deployment kt-event-marketing-frontend -n kt-event-marketing

6.3 롤백

# 이전 버전으로 롤백
kubectl rollout undo deployment/kt-event-marketing-frontend -n kt-event-marketing

# 롤아웃 히스토리 확인
kubectl rollout history deployment/kt-event-marketing-frontend -n kt-event-marketing

7. 트러블슈팅

7.1 Pod가 Running 상태가 아닌 경우

ImagePullBackOff 에러

# ImagePullSecret 확인
kubectl get secret kt-event-marketing-frontend -n kt-event-marketing

# Secret 재생성
kubectl delete secret kt-event-marketing-frontend -n kt-event-marketing
kubectl create secret docker-registry kt-event-marketing-frontend \
  --docker-server=acrdigitalgarage01.azurecr.io \
  --docker-username=<ACR_USERNAME> \
  --docker-password=<ACR_PASSWORD> \
  --namespace=kt-event-marketing

CrashLoopBackOff 에러

# Pod 로그 확인
kubectl logs -n kt-event-marketing -l app=kt-event-marketing-frontend --tail=100

# 이전 컨테이너 로그 확인
kubectl logs -n kt-event-marketing -l app=kt-event-marketing-frontend --previous

7.2 Ingress로 접속이 안 되는 경우

# Ingress Controller 확인
kubectl get svc ingress-nginx-controller -n ingress-nginx

# Ingress 상태 확인
kubectl describe ingress kt-event-marketing-frontend -n kt-event-marketing

# Service Endpoint 확인
kubectl get endpoints kt-event-marketing-frontend -n kt-event-marketing

7.3 ConfigMap이 적용되지 않는 경우

# Pod 내부 확인
kubectl exec -n kt-event-marketing -it $(kubectl get pod -n kt-event-marketing -l app=kt-event-marketing-frontend -o jsonpath='{.items[0].metadata.name}') \
  -- cat /usr/share/nginx/html/runtime-env.js

8. 개발 가이드

8.1 프로젝트 구조

kt-event-marketing-fe/
├── src/
│   ├── app/              # Next.js App Router 페이지
│   ├── components/       # React 컴포넌트
│   ├── hooks/            # Custom React Hooks
│   ├── lib/              # 유틸리티 함수 및 설정
│   ├── services/         # API 서비스 레이어
│   ├── store/            # Zustand 상태 관리
│   └── types/            # TypeScript 타입 정의
├── public/               # 정적 파일
├── design/               # 설계 문서
├── deployment/           # 배포 관련 파일
│   ├── container/        # Nginx 설정
│   └── k8s/              # Kubernetes 매니페스트
├── Dockerfile            # Docker 이미지 빌드 파일
└── package.json          # 프로젝트 의존성

8.2 코딩 컨벤션

• TypeScript: 타입 안정성을 위해 엄격한 타입 체크 사용
• ESLint: Next.js 표준 ESLint 설정 적용
• Prettier: 코드 포맷팅 자동화
• Component: 함수형 컴포넌트 + React Hooks 사용
• State Management: Zustand 활용 (전역 상태), React Query (서버 상태)

8.3 API 통신

• Axios: HTTP 클라이언트
• React Query: 서버 상태 관리 및 캐싱
• 환경 변수: NEXT_PUBLIC_* 접두사 사용

8.4 스타일링

• Material UI: 주요 UI 컴포넌트 라이브러리
• Emotion: CSS-in-JS (Material UI 기본 엔진)
• 반응형 디자인: Mobile-first 접근 (375px 기준)

9. 참고 자료

9.1 내부 문서

• 유저스토리
• 논리 아키텍처
• UI/UX 설계서
• API 매핑 설계서
• 스타일 가이드
• Kubernetes 배포 가이드

9.2 기술 문서

• Next.js Documentation
• React Documentation
• Material UI
• React Query
• Zustand

10. 팀

• 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: 이선민 (복치)